M-Pesa STK Push: Timeout, Callback & Retry Handling in Nairobi (2026)

The verdict in three sentences

STK Push is the best M-Pesa payment flow for the web: the customer gets a prompt, enters their PIN, and it's done, without leaving your site. But it's fragile by nature: the prompt expires in 60 seconds, about 14 % of customers abandon before entering the PIN, and Daraja callbacks sometimes get lost. Without systematic query status and SMS retries, you lose sales you'd already won.

The STK Push flow, step by step

The SIM Toolkit (STK) Push triggers a prompt directly on the customer's phone. Server-side, the cycle is: you call STK Push on the Daraja API, M-Pesa sends the prompt, the customer enters their PIN, then Daraja notifies the result to your callback URL. Golden rule: never trust the callback alone. Pair it with an STK Push Query call to confirm the real status, because missing callbacks are the number-one cause of orders stuck as "pending".

Callback validation requires checking the MerchantRequestID, CheckoutRequestID, and ResultCode. A ResultCode of 0 means success; any other value is a failure with its cause.

Daraja error codes and abandonment rate

Understanding the returned codes stops you from treating a mere timeout as a real payment failure. Here are the most frequent codes and recommended handling.

Code 1037 (timeout) is the most misleading: the customer may have just missed the 60-second window. An immediate SMS retry with a resume link recovers on average +11 % of these transactions.

Mini case study

Wanjiru runs a meal-delivery platform in Nairobi, with 6,000 STK payment attempts per month. Without fine handling: 82 % success, or 4,920 payments. The 1,080 failures include about 480 timeouts (code 1037). By adding an automatic SMS retry on timeouts, she recovers 11 % of those 480, or 53 orders/month, plus fewer abandonments thanks to a clear message on insufficient balance. At a 1,500 KES average basket, that's +79,500 KES/month recovered for a negligible SMS cost.

FAQ

Why do my orders stay "pending"?

Because the Daraja callback got lost and you're not doing a query status. Implement an automatic STK Push Query 30 to 60 seconds after init to resolve the status reliably.

How long does the customer have to enter their PIN?

The STK prompt expires after 60 seconds. Beyond that, you get a 1037 code and should offer a retry rather than write off the sale.

Should I automatically retry a timed-out payment?

Yes, but sparingly: a single retry triggered by the customer via an SMS link, never an automatic loop that would spam prompts and annoy the user.

What's the difference between callback and C2B confirmation?

The STK callback confirms the result of the payment request; the C2B confirmation supports accounting reconciliation on the merchant account. Both are useful for reliable reconciliation.

Does the Daraja sandbox simulate timeouts?

The sandbox lets you test the nominal flow and some error codes, but not real network loss faithfully. So keep robust query and retry logic in production.

Let's talk about your project. We set up a hardened M-Pesa STK Push, with query status and automatic SMS retries. WhatsApp +221 77 596 93 33.