Payments & Fintech
28 articles in this topic.
Your spare Android phone is a payment gateway: an offline-first SMS relay for M-Pesa
M-Pesa till confirmations arrive as an SMS, and Daraja is not open to every merchant. So we turned a spare Android phone into a self-hosted SMS-to-HTTP gateway: encrypted on-device, HMAC-signed on the wire, and built so that it never loses a message.
A payment source, not a payment parser: what keeping the pipe dumb actually buys
The SMS gateway could have extracted the M-Pesa transaction code on the phone. It deliberately does not. Here is what that bought, what it cost, and the boundary question every integration eventually has to answer: where does meaning belong?
Daraja API in Production: STK Push, C2B and B2C With Callbacks That Actually Work
A build-order guide to Safaricom's Daraja API with real payloads: OAuth token caching, STK Push, C2B v2 registration, B2C v3 with RSA security credentials, and the callback URL rules nobody documents.
Your M-Pesa Callback Will Fire Twice: Idempotency, Retries and the 1037 Problem
Daraja callbacks are unreliable notifications, not a source of truth. Seven production failure modes, with the database constraints, pollers and parsers that make double charges structurally impossible.
M-Pesa Reconciliation That Scales: From Paybill Statement to Trial Balance
Stop reconciling in spreadsheets. A three-way match between the Safaricom statement, your callback events and a double-entry ledger, with named break categories and a daily close job in Python and SQL.
Build a Payments Port, Not a Daraja Wrapper: Provider-Agnostic Money Movement in Africa
The right payments abstraction is a normalised state machine plus a normalised event, not a charge() function. Ports, adapters, webhook signature handling, minor-unit traps and config-driven routing.
KRA eTIMS Survival Guide: OSCU, cmcKey and the Rules the Spec Leaves Out
eTIMS is a fiscal device protocol, not an invoicing API. Real OSCU endpoints, the device handshake, a full saveTrnsSalesOsdc payload, the tax type codes, and six gotchas that will get invoices rejected.
Daraja invalid access token: 401.003.01 is not 404.001.03
Two Daraja errors say 'Invalid Access Token' and mean different things. One is a wrong-environment token you can fix in code, the other is an entitlement problem only Safaricom can fix.
KES, TZS and UGX: Multi-Currency Ledgers and the FX Gap Eating Your Margin
There is no single exchange rate in East Africa. Minor-unit traps, largest-remainder allocation, quote expiry, realised versus unrealised FX, and a schema that records the rate you actually transacted at.
M-Pesa 1001 Transaction In Progress: Why Retrying Instantly Fails
Daraja error 1001 is a subscriber lock, not a transient error, and the usual retry loop makes it worse. The cooldown, the state machine and the copy customers can act on.
Daraja Returns 429 With a Body Your Error Parser Cannot Read
An HTTP 429 from M-Pesa Daraja is an Apigee spike arrest fault, not Daraja JSON, so most error handlers log undefined and swallow it. Here is how to classify, pace and back off.
M-Pesa C2B Sandbox Callbacks Only Fire Half the Time
Daraja's C2B sandbox drops most confirmation callbacks, so developers debug ngrok and nginx for days. Here is why it happens and the deploy-first workflow that replaces it.
M-Pesa 'Unable to Send STK Prompt' (1025/9999): Check the Length
Daraja returns 1025 for both a too-long TransactionDesc and a genuine M-Pesa outage. One retries successfully, the other never will. Here is how to tell them apart.
M-Pesa error 2001 invalid initiator: the stale certificate trap
M-Pesa B2C returns ResultCode 2001, 'The initiator information is invalid.' It is rarely the initiator name. It is usually a certificate copied from the wrong place.
M-Pesa Daraja 500.001.1001 when your consumer key is actually correct
Daraja's 'Wrong credentials' error hides two unrelated causes, and neither is your API key. Usually it is a timestamp generated twice that drifts by one second.
M-Pesa "Invalid BusinessShortCode": The Python requests Bug Behind It
Daraja error 400.002.02 blames your shortcode, but the real cause is usually data=payload instead of json=payload in Python requests. Here is how to prove it.
M-Pesa ResultCode 4999 Is Not a Failure: Handling Undocumented Daraja Codes
Daraja's STK query can return 4999, which no Safaricom document defines. Treating it as failed causes double charges. Here is the three-bucket model that prevents it.
M-Pesa Invalid Access Token After Go-Live: It Is Not Your OAuth Code
Daraja returns 404.001.03 Invalid Access Token when your shortcode is not whitelisted, not just when the token is bad. One curl tells you which, and saves two days.
Daraja Error 1032 'Request Cancelled by User' Is Not a Bug in Your M-Pesa Integration
M-Pesa STK Push ResultCode 1032 means the customer pressed Cancel, not that anything broke. Stop paging on it and handle it as the user action it is.
Daraja 404.001.03: Cache the Access Token, Don't Mint a New One
M-Pesa Daraja tokens live about an hour. Fetching one per request gets you throttled; caching forever gets you 404.001.03. The proactive refresh pattern Safaricom never documents.
M-Pesa error 1037: the STK push that never reached the phone
Daraja 1037 is not a declined payment. It means the handset never answered the SIM toolkit prompt. How to classify it, poll for it, and retry without creating duplicate orders.
M-Pesa 1019 vs 1037 vs 1032: three STK failures that look identical and are not
1019 means the prompt arrived and the user was too slow. 1037 means it never arrived. 1032 means they cancelled. Conflating them hides whether your problem is network, copy or timeout.
Testing Payment Integrations When the Sandbox Itself Is Flaky
M-Pesa, Stripe and Paystack callbacks are where payments break, and the sandbox that fires them is unreliable. Stop chasing it: record the payloads once and test your handler against fixtures.
Your M-Pesa Integration Needs Nightly Reconciliation, Not Just Callbacks
A missing M-Pesa callback is not a failed payment, it is an unknown outcome. Build a scheduled Transaction Status reconciliation job so lost callbacks never strand a paid order.
M-Pesa STK Push Callback Never Arrives? Reconcile With the Transaction Status Query API
STK Push callbacks are not guaranteed even with a perfect URL. Build a reconciliation job that treats the Transaction Status Query API as the real source of truth.
Payment Webhook Signature Fails on One Server: The Clock-Drift Check Nobody Runs
Stripe webhook verification fails on one box but not the others? Its signature is time-bound and your clock drifted. Why Paystack and Flutterwave are immune, and the NTP fix.
When the Webhook Succeeds but Your Database Write Doesn't: Handling Orphaned Payments
The provider took the money, your write crashed, and now you have a payment with no order. Why try/catch cannot fix it, and the idempotency, outbox and reconciliation design that can.
Lipa Na M-Pesa Online With Daraja: The Callback Is the Payment, Not the Response
A working STK Push against Safaricom's Daraja API, and the mistake almost every first integration makes: treating the 200 OK from the push as proof that money moved.