Start here
Authentication and signing
Every request is signed with your key secret. The secret itself is never sent, and neither is a password or a PIN.
The libraries (Client libraries) do all of this for you. Read on if you write your own client, or if a signature fails.
The idea
For each request you build one string from its parts (the canonical string), compute an HMAC-SHA256 of it with your key secret, and send the result. TukuPay builds the same string and checks it matches. If anyone changes the method, the address, the body, the time or the customer on the way, the check fails.
Headers
| Header | Value |
|---|---|
Tuku-Key | Your key id: tkk_test_… (sandbox) or tkk_live_… (live) |
Tuku-Timestamp | Unix time in seconds, within 300 seconds of TukuPay's clock |
Tuku-Nonce | 16 to 64 of A-Z a-z 0-9 _ -, new for every request. A repeat is refused as replayed |
Tuku-Signature | v2= and the hex HMAC-SHA256 of the canonical string, with your key secret |
Tuku-Payout-Signature | Money out only (/transfers, /payouts): the same canonical string signed with your payout secret |
Idempotency-Key | Money calls (/collect/stk, /transfers, /payouts): 8 to 128 of A-Z a-z 0-9 _ . : - |
Tuku-Customer | Optional: a customer's id, to act on their account (see Customers) |
The canonical string
Eight lines joined with a newline (\n), in this order, with no newline at the end:
v2- the method, upper case (
GET,POST) - the path with its query, exactly as sent (e.g.
/v1/statement?limit=10) - the
Tuku-Timestampvalue - the
Tuku-Noncevalue - the
Tuku-Customervalue, or an empty line - the
Idempotency-Keyvalue, or an empty line - the hex SHA-256 of the raw body bytes (of the empty string when there is no body:
e3b0c442…b855)
Worked example (test vector)
Check your own code against these. The secrets are made-up test values, not real keys.
// 1. A GET with no body
key secret tks_test_secret_value_0123456789
method GET
path /v1/ping
timestamp 1762400000
nonce abcdef0123456789abcdef0123456789
body hash e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 (empty body)
canonical "v2\nGET\n/v1/ping\n1762400000\nabcdef0123456789abcdef0123456789\n\n\ne3b0c442…b855"
Tuku-Signature: v2=0bbc2365d1c7574479e91819dfc2d3c761f1cf3aa23cb0cbd4f179cd1be887bb
// 2. A payout: body, Idempotency-Key and the payout signature
method POST
path /v1/payouts?x=1
timestamp 1762400000
nonce abcdef0123456789abcdef0123456789
idempotency mcp-key-0001
body {"amount":"10.00"}
body hash e9eb495accbce2a0e95bbe079b9f9e42ccae20371c1516e3ed3036d2a787cf53
Tuku-Signature: v2=6fb442599a222e58e90b92bfb9fca5e173c93e5a85daa4ed27d59ab376fe0ad7
payout secret tkp_test_payout_value_0123456789
Tuku-Payout-Signature: v2=43d3a48f47042661338887a7e9067e6a75ba56e1f2407c372fd7c690f8664060Code
// tuku.js: one signed request to the TukuPay gateway (Node 18+, no packages)
import crypto from "node:crypto";
const BASE = process.env.TUKUPAY_GATEWAY_URL?.replace(/\/v1$/, "") || "https://gateway.tukupay.dev";
const { TUKUPAY_KEY_ID, TUKUPAY_KEY_SECRET, TUKUPAY_PAYOUT_SECRET } = process.env;
export async function tuku(method, pathWithQuery, body, { idempotencyKey = "", payout = false, customerId = "" } = {}) {
const raw = body === undefined ? "" : JSON.stringify(body); // sign exactly these bytes, send exactly these bytes
const ts = String(Math.floor(Date.now() / 1000));
const nonce = crypto.randomBytes(16).toString("hex");
const bodyHash = crypto.createHash("sha256").update(raw).digest("hex");
const canonical = ["v2", method, pathWithQuery, ts, nonce, customerId, idempotencyKey, bodyHash].join("\n");
const sign = (secret) => "v2=" + crypto.createHmac("sha256", secret).update(canonical).digest("hex");
const headers = { "Tuku-Key": TUKUPAY_KEY_ID, "Tuku-Timestamp": ts, "Tuku-Nonce": nonce, "Tuku-Signature": sign(TUKUPAY_KEY_SECRET) };
if (customerId) headers["Tuku-Customer"] = customerId;
if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
if (payout) headers["Tuku-Payout-Signature"] = sign(TUKUPAY_PAYOUT_SECRET);
if (raw) headers["Content-Type"] = "application/json";
const res = await fetch(BASE + pathWithQuery, { method, headers, body: raw || undefined });
const data = await res.json();
if (!res.ok) throw Object.assign(new Error(data.error?.message), { status: res.status, code: data.error?.code, action: data.error?.action });
return { status: res.status, data };
}Serialise the JSON body once, sign that string and send that same string. Re-serialising after signing changes the bytes and the signature fails.
When the signature is refused
| Status | error.code | Why | Fix |
|---|---|---|---|
| 401 | signature_required | A Tuku-* header is missing | Send all four Tuku-* headers |
| 401 | unauthorized | Unknown, revoked or expired key, or a wrong signature (the same answer for both) | Check the key id and secret belong together; print your canonical string and compare with the vector |
| 401 | timestamp_out_of_range | Tuku-Timestamp is more than 300 seconds off | Set your server's clock (NTP); seconds, not milliseconds |
| 401 | nonce_invalid | The nonce is not 16 to 64 allowed characters | Use 16 random bytes as hex |
| 401 | replayed | This nonce was already used with this key | A new nonce for every request, retries too |
| 401 | payout_signature_invalid | Money out without a valid Tuku-Payout-Signature | Sign the same canonical string with the payout secret |
Common mistakes: signing /payouts instead of /v1/payouts; a query in a different order than sent; a trailing newline on the canonical string; signing pretty-printed JSON and sending compact JSON.