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 (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 (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.
Testing with Daraja Sandbox (Recommended First)
- Create a Daraja Developer Account: Visit developer.safaricom.co.ke and click Sign Up.
- Create a New App: Navigate to the My Apps menu and click Add a New App.
- Select API Products: Check Lipa Na M-Pesa Sandbox and Customer to Business (C2B), then submit.
- Copy Keys: Once generated, click on your app to reveal your
Consumer KeyandConsumer Secret.
Production Go-Live (Live Merchant Payments)
To collect real payments from customer M-Pesa wallets into your business till or bank account, complete Safaricom's Go-Live process:
- Prepare Verification Documents: Have your Business Registration Certificate / Certificate of Incorporation, Director National ID/Passport, and an official M-Pesa Business Nominated Phone Number.
- Apply for Go-Live on Daraja: In your Daraja account, click Go Live in the top navigation.
- Select Organization Type: Choose Shortcode (Paybill or Buy Goods Till), enter your commercial shortcode, and attach required KYC documents.
- Verification OTP: Safaricom will send an SMS verification token to the Nominated Administrator phone number registered on the business shortcode.
- Generate Production App: After approval, Daraja will display your Production Consumer Key and Production Consumer Secret.
- 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:
Field Reference Table
| Field Name | Value Type | Requirement | Description |
|---|---|---|---|
| Environment | SANDBOX | PRODUCTION | Required | Select Sandbox for testing or Production for real money settlement. |
| M-Pesa Type | PAYBILL | TILL | Required | Select whether your shortcode is a Paybill or a Buy Goods Till. |
| ShortCode | 5 - 7 digits | Required | Your Safaricom Paybill or Till number (e.g. 174379, 600000). |
| Consumer Key | Alpha-numeric string | Required | Generated in your Daraja App dashboard. |
| Consumer Secret | Alpha-numeric string | Required | Generated alongside Consumer Key in your Daraja dashboard. |
| Pass Key | Hex-encoded hash | Required (STK Push) | Lipa Na M-Pesa Online passkey required to trigger automated PIN prompts. |
| Initiator Password | Encrypted string | Optional | Required if your organization performs automated B2C disbursements or refunds. |
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:
The customer saw the STK prompt on their phone and pressed Cancel or dismissed the SIM dialog.
The customer’s M-Pesa wallet does not have sufficient balance to cover the bill amount and carrier transaction fees.
Initiator credentials specified in Scryme settings do not match Safaricom Daraja records for disbursement operations.
Safaricom was unable to deliver the SIM push notification because the customer’s phone was off, out of network coverage, or delayed.
The transaction completed successfully. Safaricom returned an official M-Pesa receipt code (e.g., QGH48X192K).
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.