TukuPay Docs

Libraries

Client libraries

Signing, retries, idempotency and webhook checks, done for you.

LanguageInstallPackage
Node.js 18+ (TypeScript types)npm install @tukupay/sdk@tukupay/sdk
Python 3.9+pip install tukupaytukupay
PHP 8.0+composer require tukupay/sdktukupay/sdk
Any (curl and openssl)curl/tukupay.sh in the repository
AI assistantsnpx -y @tukupay/mcp login@tukupay/mcp (see MCP)
Command linenpx @tukupay/cli login@tukupay/cli (see CLI)

Each reads TUKUPAY_KEY_ID, TUKUPAY_KEY_SECRET and (for money out) TUKUPAY_PAYOUT_SECRET from the environment, signs every request, sends an Idempotency-Key made from your external_reference (all of them make the same one), retries only where it is safe, never retries a stop switch, and checks webhooks. Set TUKUPAY_GATEWAY_URL=https://gateway.tukupay.dev/v1 for the public address.

import { TukuPay, TukuPayError, verifyWebhook } from "@tukupay/sdk";

const tukupay = new TukuPay(); // TUKUPAY_KEY_ID, TUKUPAY_KEY_SECRET, TUKUPAY_PAYOUT_SECRET
const { wallets } = await tukupay.balances();

const payment = await tukupay.collect.mpesa({
  wallet_id: wallets[0].wallet_id, phone: "0712345678", amount: "1500", external_reference: "order-1042",
});
const latest = await tukupay.transactions.getByExternalReference("order-1042"); // check every 30 s

try {
  await tukupay.payouts.create({
    source_wallet_id: wallets[0].wallet_id, amount: "2500", external_reference: "supplier-77",
    to: { type: "mobile", phone: "0722000000" },
  }); // 202 awaiting_approval above your limits
} catch (e) {
  if (e instanceof TukuPayError) console.error(e.code, e.message, e.action);
}

// Webhooks: the raw body, as received
const event = verifyWebhook(rawBody, req.headers, process.env.TUKUPAY_WEBHOOK_SECRET);

A tool a person runs (a CLI) can use a session instead of a key: new TukuPay({ sessionToken }) with the token from a browser sign-in. It lasts an hour; e.isSessionExpired tells you to sign in again.

The old @tukupay/sdk 0.x, PyPI tukupay 0.1 and tukupay/tukupay-php called the retired /api/v1/sdk and no longer work. Install 1.0 or newer.