The M-Pesa Integration Playbook.

1. What you're about to build

M-Pesa STK push (Lipa na M-Pesa Online) is the easiest way to take money from a Kenyan customer in 2026. The customer hits "Pay", a prompt lands on their phone, they enter their M-Pesa PIN, money moves. No card forms. No leaving your site. No memorising a Paybill number.

This playbook covers the complete production-ready integration: sandbox, code, callbacks, reconciliation, production approvals, and the eight failure modes that block Go-Live.

2. Daraja in five minutes

The Safaricom Daraja API is the public face of M-Pesa. Inside Daraja there are several products: Customer to Business (C2B), Business to Customer (B2C), Account Balance, Transaction Status, and the one you want for ecommerce: M-PESA Express (also called Lipa na M-Pesa Online or STK push).

STK push triggers a real-time payment dialog on the customer's phone. Behind the scenes it is a webhook-style protocol: you POST to Daraja, Daraja sends a prompt to the SIM, the customer acts, Daraja calls your callback URL with the result.

3. Sandbox setup

1. Sign up at developer.safaricom.co.ke
2. Create an app, attach the "M-PESA Express Sandbox" product
3. Copy the Consumer Key and Consumer Secret
4. Use the shared sandbox shortcode 174379 and shared passkey bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919
5. Test handset: 254708374149 (the only number that gets sandbox prompts)

4. The four-step protocol

See our companion piece How M-Pesa STK push works for the full code walkthrough. The four steps:

1. OAuth: get a 1-hour access token using Consumer Key + Secret
2. Build the request password: base64(shortcode + passkey + timestamp)
3. POST to /mpesa/stkpush/v1/processrequest
4. Handle the callback (always return 200)

5. Code structure that scales

Keep these three concerns separate:

• Daraja client (pure functions for OAuth, password building, STK push request)
• Order state machine (PLACED → PAID → FULFILLED, with CheckoutRequestID as the link)
• Callback handler (parses Daraja's payload, updates the order, never throws back to Daraja)

Angazé's open-source helper library (releasing Q3 2026) handles all three out of the box.

6. Production approval

Detailed in our Daraja sandbox to production checklist. The headline: have your business documents, HTTPS callback, and Privacy/Terms/Refund pages ready before you click Go-Live. Otherwise the application rejects and the queue restarts.

7. Reconciliation in production

Match every Daraja receipt against your order ledger nightly. Discrepancies usually come from:

• Callbacks that failed to reach you (network blips)
• Duplicate STK pushes (customer hit Pay twice)
• Late callbacks (more than 60 seconds after payment)

Use the Daraja Transaction Status API to query CheckoutRequestIDs your DB shows as PENDING after 5 minutes. Mark them ABANDONED after 24 hours.

8. The eight mistakes that block Go-Live

1. Non-HTTPS callback URL
2. Callback returning anything other than 200
3. Localhost or self-signed cert in sandbox testing
4. OAuth token cached past 1 hour
5. Timestamp in UTC instead of EAT
6. Account Reference longer than 20 chars
7. Amount as a float instead of an integer
8. Missing Privacy / Refund pages on your website

9. Want us to do it for you?

We ship Daraja STK push integrations as part of every Angazé build, with Studio at KES 80,000 flat. That includes sandbox setup, production migration support, callback handler, reconciliation, and two weeks of post-launch warranty.

Book a 20-minute call and we will scope the integration to your existing stack within 48 hours.