M-Pesa is the payment rail for Kenyan digital commerce. It's also one of the least forgiving integrations in mobile money, and most teams shipping their first build hit the same five walls. Here they are.
1. The sandbox lies a little.
Daraja's sandbox is fine — until you hit production and discover subtle differences in timeout behaviour, callback retries, and edge-case error codes. Plan for a real-traffic rehearsal week with small amounts before you open the gates.
2. Reconciliation is a separate product.
STK Push is not payment confirmation. A successful STK Push means the customer saw a prompt — not that money moved. You must reconcile against the C2B confirmation callback and the transaction listing. Build the reconciliation engine before you go live; retrofitting it is 3x the work.
3. Callback URLs die quietly.
If your callback URL goes down, Safaricom does not scream. Transactions will complete at the customer's end and never reach your database. Add:
- A queue in front of your callback handler.
- An out-of-band reconciliation job that pulls the transaction listing nightly.
- An alert when the callback rate drops below historical baseline.
4. Paybill vs Till vs STK Push is not just UX.
They have different settlement timelines, different dispute flows, and different transaction fee structures. Pick the wrong one and you'll spend a year re-training customer support. Do the treasury-level thinking before the engineering thinking.
5. Your timezone handling will bite you.
Safaricom sends timestamps in EAT. Your server is probably in UTC. If your reporting is in UTC and your ops team works in EAT, every end-of-day report will be wrong for three hours. Store in UTC, display in EAT, and test at 23:30 EAT.
Every one of these has cost a real client of ours real money at some point. We've added them to our build checklist so they don't cost the next one. If you're about to ship an M-Pesa build and want a review of the integration plan, send it to us — happy to read.