Skip to content
Tubonge logoTubonge WhatsAppBiashara Yako, Simu MojaChat
M-PesaGuide

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.

Tubonge Team Published 14 October 2026 Updated 22 October 2026 10 min read

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?

APIWhat it doesTypical SME use
STK Push (Lipa na M-Pesa Online)Sends a payment prompt to the customer's phoneCheckout on a website, WhatsApp order deposit
C2BReceives customer payments to a Paybill or Till and sends callbacksAutomatic confirmation and reconciliation
Transaction StatusChecks the state of a transactionRecovering from timeouts or missing callbacks
B2CSends money from a business to a customerRefunds, supplier payouts, winnings
ReversalReverses a completed transactionDuplicate or wrong payments
Account BalanceReturns the balance of a shortcodeFinance 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:

  1. Your system authenticates with Daraja and gets an OAuth access token.
  2. You send a request with the amount, customer phone number, shortcode, account reference and callback URL.
  3. Safaricom returns a CheckoutRequestID and MerchantRequestID immediately.
  4. The customer receives the prompt and enters their M-Pesa PIN, or cancels.
  5. Safaricom posts the result to your callback URL. ResultCode 0 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

CodeMeaningWhat to check
1032Request cancelled by userCustomer pressed cancel; offer another payment method
1037Timeout / no response from userCustomer did not enter PIN; retry once, then follow up
1Insufficient fundsAsk the customer to top up or pay a deposit
2001Wrong initiator credentialsCheck B2C initiator name and security credential
400.002.02Bad requestValidate amount, phone format and required fields
500.001.1001System errorRetry with backoff and check transaction status
Common Daraja result codes. Always confirm against Safaricom's current documentation.

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

TB

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.

WhatsApp CRM for Kenyan SMEs

Turn WhatsApp chats into paid orders.

Shared inbox, approved broadcasts, sales pipeline and M-Pesa receipts in one dashboard.

Keep reading

All guides
WhatsApp CRM

WhatsApp CRM in Kenya: The Complete 2026 Guide

Everything a Kenyan SME needs to know before buying a WhatsApp CRM: features that matter, real pricing, M-Pesa integration, data protection and a vendor checklist.

22 October 2026 · 11 min