Daraja sandbox vs production.

Sandbox is Safaricom's free test environment with fake shortcodes and test phone numbers; production uses your real Paybill or Till and real customer phones. Moving between them is one credentials swap and one Safaricom Go-Live application — but three details (callback URL reachability, sandbox-vs-production passkey, and timestamp drift) account for the majority of failed first-deploys.

This guide is for the developer who has Daraja working in sandbox and wants to ship live without surprises. It covers what actually changes between the two environments, the Go-Live checklist Safaricom uses, the credentials swap, the three production-only failure modes, and the smoke test that protects real customers.

Sandbox vs production — side by side

The Safaricom Go-Live checklist

The Go-Live request is a form on the Daraja portal. You attach your shortcode, your validation and confirmation callback URLs, and proof the shortcode belongs to you. Safaricom approves in 3–10 business days.

Before you click submit, have these ready:

1. Active Paybill or Till registered to the business at M-Pesa for Business.
2. Production callback URL(s) — HTTPS, real domain, publicly reachable, no IP-allowlist that excludes Safaricom. Test by curling the URL from a different machine before submitting.
3. Validation and confirmation URLs for C2B (the two are paired — Safaricom posts to validation, your server replies "accepted" or "rejected", then Safaricom posts the actual confirmation).
4. Proof of shortcode ownership — typically the M-Pesa for Business confirmation email or a screenshot from the business portal.
5. Business KYC documents if not already on file.

Swapping the credentials

On approval, Safaricom issues a production consumer key, consumer secret and passkey. These replace the sandbox values in your environment variables. Nothing in your application code should change.

A well-organised Daraja integration reads four values from env vars: MPESA_ENV (sandbox or production), MPESA_CONSUMER_KEY, MPESA_CONSUMER_SECRET, and MPESA_PASSKEY. The shortcode usually lives in env too. Switching to production is a config change plus a redeploy. If you find yourself editing code to go live, the integration was built wrong.

Three production-only gotchas

Sandbox-passing code can still fail in production for three reasons. They are not bugs in the integration; they are environment differences.

1. Callback URL unreachable from Safaricom. The most common failure. Safaricom's servers must reach your callback URL over the public internet on port 443. No self-signed certs, no localhost, no IP allowlist that doesn't include Safaricom's egress range. Test from a server outside your network: curl -i https://yourdomain.com/api/mpesa/callback.
2. Sandbox passkey on production shortcode. Quietly fatal. The passkey is environment-specific. If your env vars still reference the sandbox passkey when MPESA_ENV=production, every STK Push will fail with an authentication error that mentions "invalid initiator information" — not "wrong passkey." Always log which environment you're hitting on boot.
3. Server clock drift. The STK Push password is a base64-encoded SHA256 of shortcode + passkey + timestamp. If your server's clock is more than ~5 minutes off, the password Safaricom recomputes won't match. NTP your server. Don't rely on the cloud provider's default.

The KES 1 smoke test

The first production payment must be your own — KES 1, from your own phone, with every step in the server logs. If anything is going to fail, it fails on you, not on a customer.

The flow to watch:

1. Access token issued — log it (just the prefix; never the full token). Confirm the env vars came through.
2. STK Push request sent — log the shortcode, phone, amount, timestamp. Confirm the password hashes against the expected inputs.
3. Phone prompts — physical confirmation: the M-Pesa screen pops up.
4. Callback arrives — log the raw payload. Confirm the MpesaReceiptNumber, ResultCode 0.
5. DB updates — your order/invoice/student account moves to "paid".
6. Customer receipt — your SMS or in-app confirmation fires.

Only after this one round-trip lands cleanly should you point the checkout at real customers. See the M-Pesa Daraja Integration guide for the full request shape, and the schools-specific build for the reconciliation pattern.

Frequently asked questions

← All articles · Full M-Pesa Daraja Integration guide →