TukuPay Docs

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 curl and openssl.

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 webhooks

For 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/sdk

5. 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.