M-Pesa Daraja API Integration: A Practical Guide for Kenyan SMEs
What the M-Pesa Daraja API does, how STK Push and C2B work, how to reconcile payments safely, and the errors to expect when going live in Kenya.
Key takeaways
- Daraja is Safaricom's developer platform for M-Pesa. It exposes APIs such as STK Push, C2B, B2C, transaction status and reversal.
- STK Push sends a payment prompt to the customer's phone; C2B receives Paybill or Till payments and sends confirmation callbacks.
- Always verify callbacks, store the raw payload, and make payment processing idempotent using CheckoutRequestID or MpesaReceiptNumber.
- Match payments to customers and orders so WhatsApp conversations, receipts and books agree.
- Test in the Daraja sandbox, handle common error codes, and never trust a screenshot as proof of payment.
What is the M-Pesa Daraja API?
Daraja is Safaricom's developer portal for M-Pesa. It gives approved businesses and developers access to M-Pesa functions over HTTPS instead of using the SIM toolkit or manual confirmations. You create an app, get credentials, request access to specific APIs, and point them at a callback URL you control.
Daraja is not a payment gateway in the Stripe sense. It is a set of M-Pesa APIs with separate approval, sandbox and production environments. You still need a Paybill or Till number, and production access requires an application explaining your use case.
Which Daraja APIs matter for an SME?
| API | What it does | Typical SME use |
|---|---|---|
| STK Push (Lipa na M-Pesa Online) | Sends a payment prompt to the customer's phone | Checkout on a website, WhatsApp order deposit |
| C2B | Receives customer payments to a Paybill or Till and sends callbacks | Automatic confirmation and reconciliation |
| Transaction Status | Checks the state of a transaction | Recovering from timeouts or missing callbacks |
| B2C | Sends money from a business to a customer | Refunds, supplier payouts, winnings |
| Reversal | Reverses a completed transaction | Duplicate or wrong payments |
| Account Balance | Returns the balance of a shortcode | Finance and daily reconciliation |
For a WhatsApp-first business, STK Push and C2B cover most needs. B2C and reversal need additional approval and stricter controls.
How STK Push works
STK Push is the familiar M-Pesa prompt that appears on a customer's phone asking them to enter their PIN. The flow has five steps:
- Your system authenticates with Daraja and gets an OAuth access token.
- You send a request with the amount, customer phone number, shortcode, account reference and callback URL.
- Safaricom returns a
CheckoutRequestIDandMerchantRequestIDimmediately. - The customer receives the prompt and enters their M-Pesa PIN, or cancels.
- Safaricom posts the result to your callback URL.
ResultCode0 means success.
A minimal STK Push request includes the shortcode, a password made from the shortcode, passkey and timestamp, the transaction type (CustomerPayBillOnline or CustomerBuyGoodsOnline), amount, payer phone, payee shortcode, callback URL, account reference and description. Keep the passkey server-side.
How C2B works
C2B handles payments that customers initiate themselves, such as sending money to your Paybill. Your system registers validation and confirmation URLs, then Safaricom sends a callback for each payment. The confirmation payload includes the receipt number, amount, phone number, bill reference and transaction time.
C2B is the better fit when customers already know your Paybill or Till and do not need a prompt. Many Kenyan businesses publish a Till number on WhatsApp and use C2B confirmation to send an automatic receipt.
Reconciling M-Pesa payments with WhatsApp
Getting the money is only half the job. The business needs to know who paid, for what, and what to do next. A reliable reconciliation flow has four parts:
- A stable identifier. Use the account reference or an order ID that also appears in the WhatsApp conversation.
- Idempotency. Store each callback by receipt number and ignore duplicates. Webhooks retry.
- Raw payload storage. Keep the original callback JSON with a timestamp for audit and disputes.
- A visible status. Show paid, pending or failed in the inbox and the order record so agents do not ask the customer for a screenshot.
For WhatsApp orders, a good pattern is: customer confirms the order in chat, your system sends an STK Push, the callback marks the deal as paid, and an approved template sends the receipt and delivery details. If the callback fails, the agent sees a pending payment instead of guessing.
Security checklist
- Verify the source and structure of callbacks, and reject unexpected IPs where your provider supports it.
- Never expose the consumer secret, passkey or initiator password in client-side code.
- Use HTTPS with a valid certificate for callback URLs.
- Make callbacks idempotent and store the raw request before processing.
- Log who triggered a B2C or reversal, and require a second approval for high amounts.
- Reconcile daily against the M-Pesa statement; callbacks can be delayed.
Common Daraja errors and what they mean
| Code | Meaning | What to check |
|---|---|---|
| 1032 | Request cancelled by user | Customer pressed cancel; offer another payment method |
| 1037 | Timeout / no response from user | Customer did not enter PIN; retry once, then follow up |
| 1 | Insufficient funds | Ask the customer to top up or pay a deposit |
| 2001 | Wrong initiator credentials | Check B2C initiator name and security credential |
| 400.002.02 | Bad request | Validate amount, phone format and required fields |
| 500.001.1001 | System error | Retry with backoff and check transaction status |
Phone numbers must be in the expected format (2547XXXXXXXX). Amounts should be integers or correctly formatted decimals. A single wrong field can fail an otherwise correct request.
Sandbox vs production
The sandbox lets you test credentials, payloads and callbacks without moving real money. It does not perfectly reproduce production behaviour, especially around approvals, limits and timing. Before launch, run a small live test with a real shortcode and a real phone, then compare the callback with the M-Pesa statement.
Going live usually requires a Paybill or Till, a Daraja app with the relevant APIs approved, and a clear description of your business. Approval is not instant, so start early if a launch date depends on it.
Frequently asked questions
These answers cover the Daraja questions we see most often from Kenyan SMEs and their developers.
Frequently asked questions
Is the M-Pesa Daraja API free?
Daraja API access itself is generally free, but normal M-Pesa transaction charges apply. Some providers charge for integration, hosting or support. Confirm the current Safaricom tariffs for your shortcode.
Do I need a Paybill or Till number to use Daraja?
Yes. STK Push and C2B work with a Paybill or Till shortcode. The API does not replace the need for a merchant shortcode.
What is the difference between STK Push and C2B?
STK Push sends a payment prompt to the customer's phone. C2B receives payments that customers initiate themselves to your Paybill or Till. STK Push is better for checkout; C2B is better for published payment details and automatic confirmations.
How do I confirm a payment if the callback never arrives?
Use the Transaction Status API with the CheckoutRequestID or transaction receipt, and reconcile against your M-Pesa statement. Do not mark an order as paid based only on a customer screenshot.
Can I integrate M-Pesa with WhatsApp?
Yes. A WhatsApp CRM can send an STK Push when a customer confirms an order, receive the Daraja callback, mark the deal as paid and send a receipt or delivery message on WhatsApp.
Is it safe to store M-Pesa phone numbers and receipts?
Yes, if you protect them. Store only what you need, encrypt sensitive data, restrict access, keep an audit trail and follow the Kenya Data Protection Act 2019.
Sources and further reading
Cite this guide
Tubonge Team (2026). “M-Pesa Daraja API Integration: A Practical Guide for Kenyan SMEs.” Tubonge WhatsApp CRM. https://tubongewhatsapp.co.ke/blog/mpesa-daraja-api-integration
Tubonge Team
Product and growth team, Tubonge WhatsApp CRM
We build Tubonge, a WhatsApp CRM for Kenyan SMEs. We write about WhatsApp Business API, M-Pesa Daraja, sales operations and practical ways small businesses can sell more on WhatsApp.