Start here
Quickstart (10 minutes)
From nothing to a sandbox M-Pesa payment you can check, in eight steps. No real money moves.
What you need
- A TukuPay account whose identity is verified (for a business: its verification complete). These docs only open for verified accounts, so if you can read this, you have it.
- Node.js 18+, Python 3.9+, or a terminal with
curlandopenssl.
1. Register an app
Open Developers → My apps → Register an app (https://tuku.money/banking-dashboard/developers). Give it a name and one line about what it does. The website, webhook URL and redirect URIs are optional: leave them empty for now.
Because your account is verified, the app is ready for the sandbox at once: no waiting for a review.
You are shown a webhook signing secret (whsec_…) once. Copy it somewhere safe if you will use webhooks later; you can make a new one any time.
2. Make a sandbox key
On the app's page, under Make a key, choose Sandbox and press Make key. You get two values. The secret is shown once:
- Key id:
tkk_test_… - Key secret:
tks_…
3. Put them in your server's environment
Never in code, never in a web page or a phone app, never in Git. Create a .env file next to your server code (and add .env to .gitignore), or use your host's secret settings (Railway, Render, Vercel, AWS):
# .env on your SERVER only (add .env to .gitignore). Placeholders: paste your own values.
TUKUPAY_GATEWAY_URL=https://gateway.tukupay.dev/v1
TUKUPAY_KEY_ID=tkk_test_xxxxxxxxxxxx # sandbox key id (tkk_live_… when you go live)
TUKUPAY_KEY_SECRET=tks_xxxxxxxxxxxxxxxxxxxxxxxx # signs every request
TUKUPAY_PAYOUT_SECRET=tkp_xxxxxxxxxxxxxxxxxxxxx # only if this server sends money out
TUKUPAY_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxx # only if you use webhooksFor this quickstart you only need the first three lines. See Keys and secrets for what each one is for.
4. Install the library
npm install @tukupay/sdk5. Your first call: ping
GET /v1/ping checks your key and signature, and tells you which app, which mode and which account you are using.
// first.mjs (run: node --env-file=.env first.mjs)
import { TukuPay } from "@tukupay/sdk";
const tukupay = new TukuPay(); // reads TUKUPAY_KEY_ID and TUKUPAY_KEY_SECRET
const me = await tukupay.ping();
console.log(me.mode, me.app.name, me.account);
const { wallets } = await tukupay.balances();
console.log(wallets); // note a wallet_id for step 6{
"app": { "id": "4f1c…", "name": "Shop Sync", "first_party": false },
"mode": "sandbox",
"livemode": false,
"key_id": "tkk_test_…",
"account": { "id": "9b2e…", "type": "individual", "kyc_verified": true, "customer": false },
"scopes": ["read", "collect", "wallets", "payouts"],
"server_time": 1762421400
}A 401 here means the key or the signature is wrong: see Authentication. Check that your computer's clock is right (within 5 minutes).
6. Send a sandbox M-Pesa prompt
Ask a phone to pay KES 10 into your wallet. In the sandbox no prompt is really sent and no money moves: TukuPay answers as the payer at once. A phone ending 0000 plays a payer who does not pay.
const payment = await tukupay.collect.mpesa({
wallet_id: 7, // from step 5
phone: "0712345678", // try 0712340000 to see a failure
amount: "10",
external_reference: "order-1", // your own id: unique per payment
});
console.log(payment.reference, payment.status);7. Check the status every 30 seconds
In live, the payer types their M-Pesa PIN on their own phone, which takes a few seconds to a couple of minutes. Ask for the payment by your reference every 30 seconds until it is no longer pending:
import { TukuPay } from "@tukupay/sdk";
const tukupay = new TukuPay();
// Check every 30 seconds; give up after 10 minutes and look again later (or ask the payer).
export async function waitForPayment(externalReference) {
for (let i = 0; i < 20; i++) {
const p = await tukupay.transactions.getByExternalReference(externalReference);
if (p.status !== "pending") return p; // completed, failed, awaiting_approval or reversed
await new Promise((r) => setTimeout(r, 30_000));
}
return null; // still pending: keep the order open and check again later
}completed means the money is in your wallet; failed means it is not (see failure_reason). More in Checking a payment.
8. Optional: webhooks
Instead of asking, TukuPay can tell your server the moment a payment settles. Add a public https webhook URL on the app's page and check each webhook's signature. Checking every 30 seconds is enough for most apps; many use both.
Next
- Going live: switch to real money.
- Embed a paypoint: a payment form on your website with one line of HTML.
- Payouts: send money, within limits.
- MCP: use TukuPay from Claude, Cursor or VS Code.