How M-Pesa Works: Behind the Scenes

Overview

M-Pesa is Kenya's dominant mobile money platform. For businesses it provides a set of merchant flows like Lipa na M-Pesa (Paybill/Buy Goods) and developer APIs (Daraja) that enable programmatic collection and push payment flows.

This post explains the building blocks merchants and developers care about: accounts vs wallets, typical API flows (STK Push / Lipa na M-Pesa Online), reconciliation basics, and where to place reliability & audit checks.

Key flows

1. Customer-initiated: Lipa na M-Pesa (Customer → Merchant)

1. Customer chooses Paybill or Buy Goods.
2. Merchant provides BusinessShortCode and AccountReference.
3. The customer initiates payment on their phone (or via STK Push initiated by the merchant's server).
4. Merchant receives an immediate callback and later receives a settlement report from Safaricom for reconciliation.

2. Merchant-initiated: STK Push (server starts the Lipa flow)

1. Merchant server calls Daraja STKPush endpoint with phone, amount, and a CallBackURL.
2. Safaricom prompts the user's phone for PIN.
3. Callback (server-to-server) indicates transaction result; the merchant should then verify using the transaction status endpoint.

Idempotency & reconciliation

1. Always store a local merchant_reference per transaction.
2. Persist incoming webhook data and verify signatures (where applicable) to prevent fraud and duplicate processing.
3. Reconcile daily with settlement files from Safaricom using the transaction IDs.

Practical engineer checklist

1. Use strong retry/backoff on network calls.
2. Implement idempotency keys for actions that may be retried.
3. Log request/response payloads (redact sensitive fields) for debugging.
4. Keep a queue for webhook processing so the user-facing flow is responsive.

Where to learn more

1. Safaricom's Daraja documentation and the Central Bank of Kenya pages for regulatory requirements (always verify the latest docs).
2. Join developer forums and communities for real-world tips and troubleshooting.