Integrate the M-Pesa Daraja API in Nairobi: developer guide 2026

The verdict in three sentences

The M-Pesa Daraja API collects through STK Push: you obtain an OAuth access token, send a CustomerPayBillOnline request, and the buyer receives a USSD prompt to enter their PIN. The non-negotiable rule is that the callback ResultCode is the source of truth, not any browser return, which is only a display signal. Plan a token valid roughly 1 hour, a public HTTPS callback URL, and idempotent references to absorb network latency without double charges.

Browser return or server callback: the decision that avoids disputes

Many naive integrations validate the order on a success page. That is the leading cause of paid-but-unfulfilled and unpaid-but-shipped orders. The browser return can be missing (tab closed, dropped 4G), whereas the server callback is queued and retried.

Concretely: on the browser side show a waiting screen that polls your backend; on the backend, only validate after the signed callback is received and the status confirmed.

M-Pesa Daraja technical parameters in 2026

Here are the values to lock down before writing the first line. They are stable on the Kenyan market in 2026.

Comparison with Orange Money Web (Abidjan)

In francophone West Africa, Orange Money Web uses a redirect plus OAuth flow, with a server notification on notify_url as the source of truth.

Mini case study

Grace runs a food delivery service in Nairobi, taking 400 online orders per month at an average basket of 850 KES, i.e. 340,000 KES. Initially she validated on the success page: 6 % of orders were either fulfilled without confirmed payment or lost, about 20,400 KES of monthly friction. By switching to the callback ResultCode as the source of truth with idempotent references, she brings these losses under 1 %, recovering over 17,000 KES per month.

FAQ

Why does the callback outrank the browser return? Because the return may never arrive (closed tab, dropped network) while the callback is queued by Safaricom until acknowledged. Validating on the return means accepting phantom orders.

How long is the OAuth access token valid? Roughly 60 minutes in 2026. Cache it server-side and renew before expiry rather than requesting one per transaction.

Must the callback URL be public? Yes, it must be an HTTPS URL reachable from the internet. In development, expose your backend through a secure tunnel to receive sandbox callbacks.

How do I avoid double charges? By passing a unique, idempotent reference on the STK request and ignoring any callback already processed for that same reference.

What is the STK prompt timeout? 60 seconds in 2026: the buyer has that window to enter their PIN. Past it, treat the transaction as failed and offer a retry.

Let's talk about your project. We integrate the M-Pesa Daraja API in Nairobi with the callback ResultCode as the source of truth, retries and idempotency included. WhatsApp +221 77 596 93 33.