Libraries
Client libraries
Signing, retries, idempotency and webhook checks, done for you.
| Language | Install | Package |
|---|---|---|
| Node.js 18+ (TypeScript types) | npm install @tukupay/sdk | @tukupay/sdk |
| Python 3.9+ | pip install tukupay | tukupay |
| PHP 8.0+ | composer require tukupay/sdk | tukupay/sdk |
| Any (curl and openssl) | curl/tukupay.sh in the repository | |
| AI assistants | npx -y @tukupay/mcp login | @tukupay/mcp (see MCP) |
| Command line | npx @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.