TukuPay Docs

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_…`)
WhenAs soon as you register the app (verified accounts)When you go live (below)
ReadsYour real account (balances, wallets, statement, links, invoices, paypoints)Your real account
Payment prompts, transfers, payoutsChecked the same way, then simulated and recorded (reference SBX…); webhooks and approvals as in liveReal money
New links, invoices, paypoints, walletsSimulated: { simulated: true, … }Made on your account
SMS and emailNot sent, except to your own phone or email where a test needs a real messageSent
`livemode`falsetrue

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 0000 does not pay (failed).
  • A transfer or payout with an amount ending .13 fails.
  • Anything above your limits goes to awaiting_approval, and you approve or decline it in TukuPay, exactly as in live.
  • Tuku-Customer may name only your own accounts (yours, your businesses, or ones you are an active team member of): sandbox_customer_not_allowed otherwise.

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.

  1. Make a live key (with your PIN) and, if you pay out, a payout secret. Set your payout limits.
  2. On your server, replace TUKUPAY_KEY_ID and TUKUPAY_KEY_SECRET with the live ones. Nothing else in your code changes.
  3. 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; .env in .gitignore.
  • A new external_reference and Idempotency-Key for 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.