What the Daraja API actually is
Daraja is Safaricom's official API for M-Pesa. It replaced older integration methods and is the supported way for software to send payment prompts, receive payment notifications, disburse funds and query transactions. You do not talk to the phone or the till directly - you talk to Daraja over HTTPS, and Daraja talks to the M-Pesa system.
Everything you can automate - Lipa na M-Pesa Online (STK Push), paybill and till payments (C2B), payouts (B2C), reversals and balance queries - is exposed as a set of endpoints you authenticate against and call.
Step one: register an app and get credentials
You start on Safaricom's developer portal. Create an account, create an app, and you receive a consumer key and consumer secret. These are the root of your access. Keep them secret - they belong in server-side configuration or a secrets manager, never in client-side code or a public repository.
For production you also register or link your business short code and obtain the extra values specific endpoints need, such as the STK Push passkey and, for payouts, an initiator name and security credential.
Step two: generate access tokens
Daraja uses OAuth. You exchange your consumer key and secret for a short-lived access token, then include that token in the authorization header of every subsequent call. Tokens expire within about an hour, so your integration must request a fresh token automatically when the current one is near expiry.
A classic mistake is generating one token at deploy time and reusing it forever. Payments work for a while, then every call starts failing with an authentication error. Build token handling so it refreshes on its own and this whole class of bug disappears.
Step three: STK Push for initiated payments
STK Push (the Lipa na M-Pesa Online request) is how your system asks a customer to pay a specific amount. You send the customer phone number, amount, your short code, the passkey-based password, a timestamp, an account reference and a callback URL. Safaricom pushes a PIN prompt to the phone and, once the customer responds or the request times out, posts the result to your callback.
The key discipline here is state. Between sending the request and receiving the result, the payment is pending - not paid, not failed. Your system must represent that pending state and only confirm on the actual callback result, never assume success.
Step four: register C2B callbacks for direct payments
For customers who pay your paybill or till directly, you use the C2B register-URL call to tell Safaricom two endpoints: a validation URL and a confirmation URL. When a customer pays, Safaricom can call your validation endpoint first (if enabled) and then your confirmation endpoint with the final transaction details.
These endpoints must be public, served over HTTPS, and reliably online. Your confirmation handler should record the raw payload immediately, then process it - matching to an invoice, updating the ledger - so that even if downstream logic fails, you never lose the fact that a payment happened.
Common mistakes that derail Daraja integrations
The same issues come up again and again, and none of them show up in a quick demo.
- Callback URL not reachable: behind a firewall, not HTTPS, or on a server that sleeps - so confirmations never arrive.
- No idempotency: the same callback is processed twice and a payment is double-counted.
- Ignoring pending and failed STK results: assuming a prompt succeeded when the customer cancelled or ran out of time.
- Weak account references: making automatic reconciliation impossible and forcing manual matching.
- Skipping the go-live steps: testing only in sandbox and being surprised when production behaves differently.
- Leaking credentials: putting the consumer secret or passkey in front-end code.
Going live and staying reliable
Before production, Safaricom requires a go-live process for your short code and app. Once live, treat the integration as revenue infrastructure. Monitor that callbacks are still arriving, alert when payments stop, keep an audit trail of every raw message, and reconcile daily against your M-Pesa statement so any gap is caught fast.
Reliability is a moving target - certificates expire, servers move, credentials rotate - so ongoing care matters as much as the initial build.
How Upeosoft builds Daraja integrations
We build Daraja integrations designed for production from the start: automatic token handling, resilient callback capture, idempotent processing, automatic reconciliation against your invoices, and monitoring that tells you the moment payments stop flowing. We connect it to your ERP or accounting system so the ledger updates itself, and we take you through Safaricom's go-live process.
Whether you are starting fresh or rescuing an integration that keeps dropping payments, talk to Upeosoft and we will build it to be reliable, not just functional.
