paylod
Go live

Guides

Go live on production Daraja credentials

.md

Move from sandbox to production: production Daraja credentials, the callback URL you paste into the Daraja portal, and the go-live checklist.

What changes

Almost nothing changes. Your code is the same. Three items change.

  1. Put your production Daraja credentials and your real shortcode into the Production environment of your application.
  2. Copy the production callback URL into the Daraja portal.
  3. Change mp_test_… to mp_live_… in your backend.

The endpoints, the request bodies, the webhook envelope and the result codes are the same. This is the reason to build against sandbox first.

1. Get production Daraja credentials

Safaricom issues production credentials for your real till or paybill. Get the credentials on the Daraja portal, under "Go Live". You need these values:

  • Your consumer key and your consumer secret for the production app.
  • Your shortcode — the till number or the paybill number that customers already pay.
  • Your Lipa na M-Pesa Online passkey.
  • For payouts, reversals and the admin queries: an Initiator Name and an Initiator Password. Safaricom issues these two values separately. The Initiator Password is also called the security credential.

Copy the values into the Production environment of the application. paylod encrypts the values at rest, and never reads the values back.

2. Set the callback URL in the Daraja portal

paylod hosts the callback receiver. Thus you copy into Daraja the URL that paylod shows on the application's Endpoints & Webhooks tab.

You must do this step yourself, because Safaricom has no API that registers a callback URL. You can automate all the other steps of a paylod integration.

Keep the callback URL secret. The callback URL contains a token for one application.

3. Replace the key

Create an mp_live_… key on the API Keys tab. Then put the key into the secret store of your server. Your code does not change:

.env
PAYLOD_API_KEY=mp_live_YOUR_API_KEY

The key alone selects production. There is no environment flag that you can forget.

Go-live checklist

  • Keep the API key on your server. Never put the API key in a browser or a mobile app.
  • Take the amount from your own order record. Never take the amount from the client.
  • Verify the HMAC signature in your webhook handler before you parse the body. paylod.webhookHandler() does this for you.
  • Compare data.amount with the order total before you fulfil the order.
  • Use one Idempotency-Key for each payment attempt, and not for each order or product. A retry after a failure is a new attempt, and needs a new key.
  • After a 409 indeterminate reply, read the payment status. Do not retry the same key.
  • Handle a 429 with a backoff. Do not let your program stop.
  • Test your failure paths (1032, 1037, 2001) at least one time.
  • If you use payouts or admin queries, set the Initiator Name and the Initiator Password on the Production environment.

Secure integration explains the reason for each item above.

Then monitor it

The dashboard shows payments, webhook deliveries and delivery retries. If a delivery fails, the dashboard shows the attempts and the response of your endpoint.