The verdict in three sentences
A reliable test environment is what separates a calm go-live from a weekend spent refunding angry customers. In 2026, set up a webhook tunnel (ngrok or equivalent), simulate the STK push callbacks, and replay every event until success, timeout and cancellation are all handled. The rule: never ship a payment flow that has not passed a checklist of at least 12 test cases.
Building the sandbox step by step
M-Pesa Daraja uses an STK push (a prompt on the customer's phone), while other operators like Orange Money use a web redirect with a notification URL. The testing principle is the same: an isolated environment, test credentials, and a callback endpoint reachable from the internet.
| Test element | 2026 value / tool | Role |
|---|---|---|
| Local tunnel | ngrok, cloudflared | Expose localhost to the callback |
| Callback URL | https://xxxx.ngrok.io/webhook | Receive payment status |
| Test account | Provided by operator | Pay with no real money |
| STK timeout | 60 seconds | Simulate expiration |
| Daraja test shortcode | 174379 | Safaricom sandbox |
| Event replay | Log + manual POST | Test idempotency |
| Webhook signature | Header to verify | Reject fake calls |
The classic trap: coding only the happy path (the customer pays, everything works). In reality 20 to 30 % of attempts end in timeout, cancellation or insufficient balance. Each of these cases needs a defined and tested behavior.
The 12-case checklist and their actions
Here are the statuses to cover and the expected action from your back end. Do not sign off the test phase until all 12 are green.
| # | Test case | Status received | Expected action |
|---|---|---|---|
| 1 | Successful payment | success | Fulfill, mark paid |
| 2 | Insufficient balance | failed | Fulfill nothing, clear message |
| 3 | Customer cancels | cancelled | Release the cart |
| 4 | STK timeout 60 s | timeout | Mark pending, retry |
| 5 | Double callback | success x2 | Idempotency, one fulfillment |
| 6 | Wrong amount | mismatch | Reject, alert |
| 7 | Invalid signature | — | Ignore, log |
| 8 | Unknown reference | 404 | Log, no fulfillment |
| 9 | Late callback | success | Fulfill if not already done |
| 10 | Customer network drop | pending | Server verify on return |
| 11 | Refund | refunded | Cancel the order |
| 12 | Manual replay | success | No double effect |
Cases 5 and 9 are the most often forgotten and the most costly: they test idempotency, the ability to receive the same event twice without fulfilling twice.
Mini case study
Grace, who runs an online-ordering eatery in Nairobi, launched without serious testing. The first Friday night, a traffic spike on mobile data generated dozens of timeouts. Her system, handling only the happy path, left orders stuck without ever confirming or cancelling. The result: 23 phantom orders, a paralyzed kitchen, and 34,000 KES of tickets impossible to reconcile that evening. After building a sandbox and validating the 12 cases (especially timeout and replay), the stuck-order rate fell below 1 %. The test phase cost 2 days of work; the ruined weekend had cost far more.
Need a professional website?
Kolonell builds websites that attract clients, optimized for the Sénégalese market. Free quote in 2 minutes.
FAQ
How long does an M-Pesa STK push stay active in the 2026 sandbox?
About 60 seconds. Without a PIN entry in that window, the request expires and you get a failure or timeout status. Test this case explicitly, it is one of the most common in production.
Do I need a tunnel like ngrok to test webhooks?
Yes, in local development. The operator must reach your callback from the internet, and localhost is not accessible. A tunnel exposes your local URL during testing.
Which shortcode do I use for the Daraja sandbox?
The test shortcode 174379 in the Safaricom sandbox environment. It lets you simulate an STK push with no real money movement.
How many cases should I test before production?
At least 12: success, failure, cancellation, timeout, double callback, refund and manual replay. The idempotency cases (double callback, late callback) are non-negotiable.
Can I replay a webhook event to test?
Yes, and it is essential. Keep the payload in your logs and re-POST it manually: your system must produce exactly the same result as the first time, with no double effect.
Let's talk about your project. We build your mobile money sandbox and validate every webhook before go-live. WhatsApp +221 77 596 93 33.
Mohamed Bah
Fondateur, Kolonell
Passionate about digital and entrepreneurship in Africa, Mohamed has been helping Sénégalese businesses with their digital transformation since 2020. Founder of Kolonell, he believes every SME deserves a professional and accessible online présence.
