Safaricom Developer Sandbox: Best Practices and Pitfalls

Why the sandbox matters

Safaricom's sandbox lets you emulate Daraja flows without touching real money. Use it to verify your request/response handling, callback reliability, and reconciliation logic.

Best practices

1. Respect rate limits

1. Don't hammer endpoints in tight loops. Use exponential backoff for retries.
2. Use realistic concurrency in tests to mirror expected production traffic.

2. Simulate real-world errors

1. Test timeouts, network flips, and duplicate webhooks.
2. Simulate user cancellations and failed STK pushes — ensure your system handles ResultCode != 0.

3. Test callback security & idempotency

1. Make callbacks idempotent by checking CheckoutRequestID or MerchantRequestID before creating records.
2. Persist raw payloads for forensic debugging.

4. Local dev to public endpoint

1. Tools like ngrok (or a permanent staging URL) make local testing of webhooks easier; ensure your endpoint is HTTPS.

Common gotchas

1. Using expired OAuth tokens — cache tokens until expiry.
2. Not using the exact Timestamp and Password format required by Daraja.
3. Assuming the initial STK push response is final — always rely on the callback/transaction query for finality.

Closing

Treat the sandbox like a contract testing environment: mimic production conditions, test failures thoroughly, and instrument observability so you know when things go wrong.