ScrymeDeveloper Docs
M-Pesa Payments & Daraja Guide

Safaricom M-Pesa Integration

Scryme natively connects your physical POS terminals, online checkout counters, and billing invoices to Safaricom M-Pesa. This guide walks you through acquiring Daraja API credentials, understanding Paybill versus Buy Goods (Till) configurations, configuring your Scryme workspace, and managing real-time payment reconciliation.

Instant STK Push

Prompt customer phones directly with the exact bill amount. Payer merely enters their M-Pesa PIN.

Auto Customer Saving

Automatically parses payer phone number and name into your CRM, building customer order history seamlessly.

Encrypted Credentials

All API consumer secrets and passkeys are encrypted at rest with hardware-backed KMS before storage.

Step 1: Understand Paybill vs. Buy Goods (Till)

Before configuring credentials, select the M-Pesa shortcode model that matches your Safaricom business contract:

PAYBILL NUMBER

Paybill (5-7 digits)

Customers input your Business Number and an Account Number (e.g., Order #, Invoice #, or Customer ID).

  • Supports STK Push and C2B customer payments
  • Allows custom Account Reference for invoice matching
  • Payer fees can be shared or borne by merchant/customer
  • Ideal for e-commerce, services, subscriptions, and POS
BUY GOODS / TILL

Buy Goods Till (5-7 digits)

Customers choose "Buy Goods and Services" and enter your Till Number directly without typing an account number.

  • Free for customers to pay (standard merchant fee applies)
  • Supports Lipa Na M-Pesa Online STK Push via Head Office shortcode
  • Commonly deployed in retail stores, restaurants, and supermarkets
  • Settles to nominated merchant bank account or store till

Step 2: Obtain Credentials from Safaricom Daraja Portal

Safaricom requires API keys through their developer portal (Daraja) to authorize transactions between Scryme and your M-Pesa till/paybill.

A

Testing with Daraja Sandbox (Recommended First)

Development & Testing
  1. Create a Daraja Developer Account: Visit developer.safaricom.co.ke and click Sign Up.
  2. Create a New App: Navigate to the My Apps menu and click Add a New App.
  3. Select API Products: Check Lipa Na M-Pesa Sandbox and Customer to Business (C2B), then submit.
  4. Copy Keys: Once generated, click on your app to reveal your Consumer Key and Consumer Secret.
Daraja Standard Test Sandbox Credentials:
Test ShortCode: 174379
Test Type: Paybill
Test PassKey: bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
B

Production Go-Live (Live Merchant Payments)

Live Store Settlement

To collect real payments from customer M-Pesa wallets into your business till or bank account, complete Safaricom's Go-Live process:

  1. Prepare Verification Documents: Have your Business Registration Certificate / Certificate of Incorporation, Director National ID/Passport, and an official M-Pesa Business Nominated Phone Number.
  2. Apply for Go-Live on Daraja: In your Daraja account, click Go Live in the top navigation.
  3. Select Organization Type: Choose Shortcode (Paybill or Buy Goods Till), enter your commercial shortcode, and attach required KYC documents.
  4. Verification OTP: Safaricom will send an SMS verification token to the Nominated Administrator phone number registered on the business shortcode.
  5. Generate Production App: After approval, Daraja will display your Production Consumer Key and Production Consumer Secret.
  6. Obtain the Online Passkey:
    • For Paybill: Safaricom emails the live PassKey to your administrator email address, or displays it under Lipa Na M-Pesa Online within the production app.
    • For Till (Buy Goods): The PassKey is generated against your Store or Head Office shortcode.

Security Reminder: Never share your Consumer Secret, Passkey, or Initiator Password via unencrypted chat or email. Scryme uses AES-256 GCM encryption at rest to protect these credentials.

Step 3: Configure Credentials in Scryme

Once you have your credentials, link them to your Scryme workspace to enable POS checkout, invoicing, and webhooks:

Navigation Path
Workspace→Settings→Organization Settings→Payment Options (M-Pesa)

Field Reference Table

Field NameValue TypeRequirementDescription
EnvironmentSANDBOX | PRODUCTIONRequiredSelect Sandbox for testing or Production for real money settlement.
M-Pesa TypePAYBILL | TILLRequiredSelect whether your shortcode is a Paybill or a Buy Goods Till.
ShortCode5 - 7 digitsRequiredYour Safaricom Paybill or Till number (e.g. 174379, 600000).
Consumer KeyAlpha-numeric stringRequiredGenerated in your Daraja App dashboard.
Consumer SecretAlpha-numeric stringRequiredGenerated alongside Consumer Key in your Daraja dashboard.
Pass KeyHex-encoded hashRequired (STK Push)Lipa Na M-Pesa Online passkey required to trigger automated PIN prompts.
Initiator PasswordEncrypted stringOptionalRequired if your organization performs automated B2C disbursements or refunds.
Click Save changes. Your settings immediately apply across all connected POS devices and online checkouts without requiring app restarts.

Step 4: Payment Processing & Automated Tracking

How Scryme processes and reconciles customer payments in real time:

1STK Push (Lipa Na M-Pesa Online)

When a cashier rings up a sale or a customer checks out on web/invoicing:

  • Cashier selects M-Pesa and inputs customer phone (accepts 07..., 254..., or +254...).
  • Scryme standardizes the phone to Kenyan E.164 format (254XXXXXXXXX).
  • A real-time STK push appears on the customer's mobile device displaying your business name and amount.
  • Customer enters PIN → Safaricom dispatches webhook callback → Scryme marks the sale as PAID within seconds.

2Manual C2B Paybill Payments & Unclaimed Reconciliations

For customers who pay through their SIM toolkit without a prompt:

  • Customer sends money to your Paybill using Order or Invoice number as Account Reference.
  • Safaricom sends a C2B Confirmation webhook to Scryme.
  • Scryme matches the transaction code or allows cashiers to search and claim the payment by receipt code.

3Autonomous Customer Directory Linking

Every successful M-Pesa payment automatically links or registers the payer in your workspace:

  • Existing customers with matching phone numbers have this new purchase recorded to their profile.
  • New walk-in customers are automatically created with their name (from C2B records) or standardized phone number.
  • CRM triggers (like welcome messages, loyalty points, or digital receipts) dispatch automatically.

Troubleshooting & Daraja Error Codes

Reference for common Safaricom response codes when processing M-Pesa transactions:

ResultCode 1032Request Cancelled by User

The customer saw the STK prompt on their phone and pressed Cancel or dismissed the SIM dialog.

Recommended Action: Prompt the customer to re-attempt payment, or offer manual Paybill/Till entry.
ResultCode 1Insufficient Funds

The customer’s M-Pesa wallet does not have sufficient balance to cover the bill amount and carrier transaction fees.

Recommended Action: Advise customer to top up their M-Pesa balance or split the bill with an alternative payment method.
ResultCode 2001Invalid Initiator Password / PIN

Initiator credentials specified in Scryme settings do not match Safaricom Daraja records for disbursement operations.

Recommended Action: Verify and reset your Operator/Initiator password in the Safaricom M-Pesa Business portal.
ResultCode 1037User Timeout / SIM Unreachable

Safaricom was unable to deliver the SIM push notification because the customer’s phone was off, out of network coverage, or delayed.

Recommended Action: Ensure the customer has cellular signal. Scryme will automatically poll or allow manual retry.
ResultCode 0Success

The transaction completed successfully. Safaricom returned an official M-Pesa receipt code (e.g., QGH48X192K).

Recommended Action: Payment is marked COMPLETED, receipt printed/emailed, and customer linked automatically.
Ready to accept payments

Start ringing up sales on Scryme POS

Now that your shortcode and credentials are saved, launch the POS app or web checkout. M-Pesa will appear as a primary payment method alongside cash and card.