Daraja Sandbox to Production: The Go-Live Checklist

The sandbox and production environments are structurally identical. The same endpoints, the same JSON structure, the same callback format. The differences are:

• Base URL: sandbox.safaricom.co.ke becomes api.safaricom.co.ke
• Consumer Key and Secret: you get a new pair tied to your production app
• Shortcode: the sandbox shortcode 174379 is replaced by your real paybill or till number
• Passkey: Safaricom issues a production passkey specific to your shortcode
• Phone numbers: in sandbox, only the test number works. In production, any Safaricom number can pay
• Real money moves: production transactions debit real M-Pesa balances

If your code is well structured with environment variables for all these values, the switch is a matter of updating your .env file. No code changes required.

You need a Safaricom shortcode (paybill or buy goods till number) before you can go live. If your business already has one, skip to the next step.

There are two types:

• Paybill: customers pay to an account number (e.g., pay to paybill 123456, account "Order789"). Best for businesses that need to distinguish between multiple payment streams.
• Buy Goods (Till): customers pay to a simple till number with no account field. Best for retail and simple payment collection.

To apply:

1. Visit the Safaricom Business portal or contact your Safaricom Business account manager
2. Submit your business registration documents (certificate of incorporation, KRA PIN, business permit)
3. Provide your business bank account details for settlement
4. Wait for approval (typically 1 to 3 weeks)

You can also use a shortcode through an aggregator like Kopokopo, IntaSend, or Flutterwave. Aggregators let you use their shortcode and handle the Safaricom relationship, which is faster but means you share the shortcode with other businesses.

Once you have your shortcode, you need to activate API access for it on the Daraja portal.

1. Log into developer.safaricom.co.ke
2. Navigate to your existing sandbox app (or create a new one)
3. Click "Go Live" and fill in the application form
4. Provide your production shortcode and the APIs you need (Lipa Na M-Pesa, C2B, B2C, etc.)
5. Provide a publicly accessible callback URL (HTTPS required)
6. Safaricom reviews your application and may request a test demonstration

Once approved, you receive:

• Production Consumer Key and Consumer Secret
• Production passkey for your shortcode
• Confirmation of which API products are enabled

Store these securely. Do not commit them to version control. Use a secrets manager or encrypted environment variables in your deployment platform.

Before flipping the switch, walk through every item on this list:

Environment configuration

• Base URL updated to api.safaricom.co.ke
• Production Consumer Key and Secret set in environment variables
• Production shortcode and passkey configured
• Callback URL is a publicly accessible HTTPS endpoint (no ngrok, no HTTP)
• All sandbox-specific test values removed from config

Security

• HTTPS enforced on all callback endpoints
• Callback validation: verify the request actually came from Safaricom (check source IPs or implement signature verification)
• Idempotency: duplicate callbacks for the same CheckoutRequestID do not create double entries
• No credentials in source code, logs, or error messages
• Access token is cached and refreshed before expiry, not fetched on every request

Reliability

• Callback endpoint responds within 5 seconds with HTTP 200
• Heavy processing (database writes, emails) runs asynchronously after acknowledging the callback
• Transaction Status Query implemented as a fallback when callbacks do not arrive
• Timeout handling: your UI shows clear feedback when STK Push times out
• Error logging captures result codes and request IDs for debugging

Money handling

• Amounts stored as integers (whole KES), never floats
• Reconciliation logic matches callback amounts against expected order amounts
• Partial payment handling defined (reject, hold, or accept with balance)

Testing

• End-to-end test with a real phone number and a small amount (KES 1)
• Test the cancel flow (dismiss the STK prompt)
• Test the timeout flow (let the prompt expire)
• Test callback failure recovery (stop your server, trigger a payment, restart, then query status)

These are the issues that catch teams most often during the switch to production:

Mixed credentials: using the production shortcode with the sandbox Consumer Key (or vice versa). Every credential must match the same environment. Double-check all four values.

HTTP callback URL: production requires HTTPS. If your callback URL uses plain HTTP, Safaricom rejects it silently. Make sure your SSL certificate is valid and not self-signed.

ngrok in production: ngrok URLs are for development only. They change every time you restart (on the free plan) and have rate limits. Deploy your callback endpoint on your production server.

Hardcoded sandbox shortcode: if 174379 appears anywhere outside your environment variables, you have a bug waiting to surface.

Timestamp timezone issues: the timestamp in your STK Push password must use the same timezone Safaricom expects. Use UTC or East African Time (UTC+3) consistently. Mismatched timestamps cause "Invalid password" errors that are painful to debug.

Missing error handling for production error codes: production surfaces error codes you never see in sandbox, like "Initiator information is invalid" or "The transaction amount is less than the minimum." Handle unknown error codes gracefully with a user-facing "Payment could not be processed" message and log the raw response for investigation.