Start here
Sandbox and going live
Practise in the sandbox with no real money, then go live yourself with your PIN.
| Sandbox (`tkk_test_…`) | Live (`tkk_live_…`) | |
|---|---|---|
| When | As soon as you register the app (verified accounts) | When you go live (below) |
| Reads | Your real account (balances, wallets, statement, links, invoices, paypoints) | Your real account |
| Payment prompts, transfers, payouts | Checked the same way, then simulated and recorded (reference SBX…); webhooks and approvals as in live | Real money |
| New links, invoices, paypoints, wallets | Simulated: { simulated: true, … } | Made on your account |
| SMS and email | Not sent, except to your own phone or email where a test needs a real message | Sent |
| `livemode` | false | true |
Sandbox rules
- No real money moves, ever. Nothing reaches M-Pesa or a bank.
- No messages to strangers. The sandbox never texts or emails a number or address that is not yours, and never spends TukuPay's message credits on them.
- A payment prompt is answered at once. A phone ending
0000does not pay (failed). - A transfer or payout with an amount ending
.13fails. - Anything above your limits goes to
awaiting_approval, and you approve or decline it in TukuPay, exactly as in live. Tuku-Customermay name only your own accounts (yours, your businesses, or ones you are an active team member of):sandbox_customer_not_allowedotherwise.
Going live
You do it yourself; there is no form to wait on. The app's page shows a checklist; when every line is ticked, the account owner chooses Go live and types their PIN. The checklist:
- your account is verified (for a business: fully verified) and in good standing;
- the app is in the sandbox and not stopped;
- it says what it does (its purpose, 20 characters or more) and has a website address;
- it has made at least 20 successful sandbox calls;
- it learns how payments end: it has a webhook URL, or it has looked a payment up (
GET /transactions/{reference}).
Then the app is live and TukuPay's team is told. It starts with starter limits: payout limits of 0 (every payout waits for your PIN until you raise them) and 60 requests a minute for its first 30 days. A business's app is taken live by the business owner only.
- Make a live key (with your PIN) and, if you pay out, a payout secret. Set your payout limits.
- On your server, replace
TUKUPAY_KEY_IDandTUKUPAY_KEY_SECRETwith the live ones. Nothing else in your code changes. - Make one small real payment (KES 10) and check it arrives.
TukuPay can switch self go-live off for everyone or for one developer. Then the page offers Request live access instead, and a TukuPay admin reviews the app (403 self_approval_off from the go-live call). A failed checklist answers 409 go_live_checks_failed listing what is missing.
Checklist before real money
- Secrets only in server environment variables;
.envin.gitignore. - A new
external_referenceandIdempotency-Keyfor each payment; retries reuse them. - You check the status every 30 seconds (or use webhooks, signature checked) before handing over goods.
- Payout limits as low as your business allows; "payees only" on if you pay the same people.
- You know where the stop button is: your app's page → Stop the app.