Go-live checklist
Everything to test in the sandbox before you take real money through the API.
Work through this in the sandbox before you apply for live access, and again before you switch your production traffic.
Keys
- Keys live only on servers, in a secret manager.
- Live keys have the fewest scopes and an IP allowlist of your fixed egress IPs.
- You know how to roll and revoke a key, and who gets the expiry emails.
Payouts
- Every create sends an Idempotency-Key saved with your record before the first attempt.
- Network errors, 5xx, RATE_LIMITED, IDEMPOTENCY_IN_PROGRESS and CAPABILITY_PAUSED retry with backoff and the same key.
- 4xx errors aren't retried blindly; you show or log error, code and requestId.
- Amounts are KES cents, whole shillings, as integers.
- You tested all six statuses in the sandbox, including in_review and reversed.
- A failed payout is retried, if at all, as a new payout with a new key.
Webhooks
- Signatures and the 5-minute timestamp window are checked on the raw body.
- You answer 2xx within 10 seconds and process in the background.
- Duplicates are dropped by event id; out-of-order events can't move a final status backwards.
- You can catch up from GET /api/v1/events after downtime.
Money
- Your balance is funded and a low-balance alert is set.
- A daily reconciliation compares payouts with your records.
- You check recipients before first payouts.
People
- Technical, finance and security contacts are set in the Console.
- Accounts that can manage keys use two-factor sign-in.
- Someone owns watching the Console's Logs and Usage.
Sandbox scenarios to run
| Scenario | How |
|---|---|
| Success | Pay +254700000001. |
| Recipient fails | Pay +254700000002. |
| Held for review | Pay +254700000003. |
| Reversal after success | Pay +254700000004. |
| Network timeout | Pay amount 13300; wait about a minute. |
| Retry is safe | Send the same request twice with the same Idempotency-Key; you get one payout and Idempotent-Replayed: true. |
| Changed retry is refused | Same key, different amount: IDEMPOTENCY_KEY_REUSED. |
| Not enough money | Pay more than your sandbox balance: INSUFFICIENT_BALANCE. |
| Over the limit | Pay more than KES 150,000 in one payout: LIMIT_PER_TX_EXCEEDED. |
| Webhook down | Make your endpoint return 500, then 200; watch the retries in the Console. |