M-Pesa Daraja: what you wish you would have known

Kwame: Kelvin, you have shipped Daraja integrations for years. What is the thing you wish someone had told you on day one? Kelvin: That Daraja is not one API. It is at least six APIs with overlapping conventions and inconsistent behaviors. STK push, B2C, B2B, C2B, transaction status, account balance. Each has its own quirks. The naming overlaps but the semantics do not. If you write a single wrapper for 'Daraja', you will paint yourself into a corner within six months. Write a wrapper per product. Share the auth layer. Do not share the request building. Adaobi: Sandbox versus production? Kelvin: The sandbox is a fiction. It does not enforce the same validation rules. It does not produce callbacks in the same shape. It does not rate-limit you the way production does. Build against the sandbox to get the happy path working. Then negotiate access to the staging environment, which is a closer approximation. Then plan for a week of bug-fixing in production. There is no shortcut. Kwame: Idempotency? Kelvin: The callback is the issue. Safaricom retries callbacks. The retry is not always perfectly identical. Your callback handler has to be idempotent on the originator conversation ID, not on the raw payload. We had a production incident where a duplicated callback double-credited an account because our handler keyed on a different field. Take this seriously. Adaobi: Reconciliation? Kelvin: Reconcile every day. Reconcile every product separately. Have a human glance at the recon report every morning. Automated alerting is necessary but not sufficient. The human reads the report and notices when something is off in a way the alert thresholds did not catch. That ten-minute habit has caught more issues for us than any monitoring system. Kwame: When do you call Safaricom support? Kelvin: When you have collected the evidence. They are a busy team. The interactions that go best are the ones where you walk in with timestamps, conversation IDs, expected behavior, observed behavior. They will close the loop fast if you do the work for them. They will deprioritize you politely if you do not. Adaobi: What do you wish you knew on day one? Kelvin: That M-Pesa is not just an API. It is an ecosystem with conventions, with politics, and with a depth of operational knowledge that nobody writes down. Spend time with people who have been in the trenches. Buy them lunch. The lunch will save you six months. Kwame: Thanks, Kelvin. Kelvin: Pleasure.