M-Pesa Integration in 2026: The Complete Developer Guide

With over 50 million active users in Kenya, M-Pesa isn't just a payment method — it's the financial infrastructure most Kenyans rely on daily. If your software product serves the Kenyan market and doesn't have native M-Pesa integration, you're losing revenue. This is the complete guide to getting it right in 2026.

Understanding the Daraja API Landscape

Safaricom's Daraja 2.0 API is the gateway to all M-Pesa transactions. It supports five main payment flows: STK Push (Lipa Na M-Pesa Online) for customer-initiated payments, C2B for Paybill and Till payments, B2C for payouts and disbursements, B2B for business transfers, and the Transaction Status and Reversal APIs.

Most Kenyan applications need STK Push for checkout and C2B for Paybill reconciliation. We'll cover both in depth.

STK Push: The Gold Standard for Checkout

STK Push is the smoothest payment experience available. Your backend sends a payment request, Safaricom pushes a prompt to the user's phone, they enter their M-Pesa PIN, and your server receives a callback. No redirects, no USSD codes, no friction.

The implementation has three steps. First, authenticate by POSTing to the OAuth endpoint with your Consumer Key and Secret (Base64 encoded) to get a Bearer token — cache this for 3,500 seconds. Second, initiate the STK Push with the customer phone, amount, Paybill or Till number, and your callback URL — you'll get a CheckoutRequestID back, store it. Third, handle the callback: Safaricom POSTs the result to your callback URL, match it to the CheckoutRequestID, check ResultCode (0 = success), and update your database.

Handling Webhooks Securely

M-Pesa callbacks come from Safaricom's IP ranges: 196.201.214.0/24 and 196.201.213.0/24. Whitelist these in Nginx or your firewall. Never process a callback from outside these ranges.

Callbacks must be processed idempotently — Safaricom can and does send the same callback more than once. Always check whether a transaction with that CheckoutRequestID has already been processed before updating balances or fulfilling orders.

Always implement a polling fallback. If no callback arrives within 30 seconds, query the Transaction Status API directly. Network issues between Safaricom and your server are more common than you'd expect.

C2B Paybill Integration

C2B lets customers pay to your Paybill directly from their M-Pesa menu. You register validation and confirmation callback URLs with Safaricom. The validation URL is called first — respond Accept or Reject. The confirmation URL fires after payment completes — this is where you credit accounts or trigger fulfilment.

One critical gotcha: in some C2B configurations, the phone number in the callback is a SHA256 hash of the actual number, not the real MSISDN. We've handled this in production across multiple systems and built PhoneHash lookup tables to resolve it. Don't assume you're getting the real phone number.

Common Pitfalls We See Every Time

Phone number formatting. M-Pesa expects 254XXXXXXXXX format — not +254, not 07XX, not 7XX. Normalise every number before sending to Daraja.

Token caching. Don't request a new access token for every transaction. Cache with a 3,500-second TTL — requesting a new token per transaction hits rate limits fast.

Callback URL accessibility. Your callback URL must be publicly reachable. Safaricom cannot reach localhost. Use ngrok in development; in production ensure Safaricom's IPs aren't blocked at the firewall.

Sandbox reliability. The Daraja sandbox is unreliable — callbacks often don't fire, and test credentials behave differently from production. Test in production with KES 1. Yes, really.

Duplicate callbacks. Use MpesaReceiptNumber as a unique constraint in your transactions table. Double-processing a payment callback is a real production bug we've fixed for multiple clients.

Going Live: The Safaricom Process

Getting a production Daraja app approved takes 3–10 business days. You need a registered M-Pesa Paybill or Till number, a business registration certificate, and a working sandbox demo. The Daraja portal go-live process is more streamlined than it used to be.

We've done this across Tikiti, Parcel Track, Water VE.KE, RentalLink, and more. If you need help with the integration or go-live, get in touch.