TukuPay Docs

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

HeaderValue
Tuku-KeyYour key id: tkk_test_… (sandbox) or tkk_live_… (live)
Tuku-TimestampUnix time in seconds, within 300 seconds of TukuPay's clock
Tuku-Nonce16 to 64 of A-Z a-z 0-9 _ -, new for every request. A repeat is refused as replayed
Tuku-Signaturev2= and the hex HMAC-SHA256 of the canonical string, with your key secret
Tuku-Payout-SignatureMoney out only (/transfers, /payouts): the same canonical string signed with your payout secret
Idempotency-KeyMoney calls (/collect/stk, /transfers, /payouts): 8 to 128 of A-Z a-z 0-9 _ . : -
Tuku-CustomerOptional: 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:

  1. v2
  2. the method, upper case (GET, POST)
  3. the path with its query, exactly as sent (e.g. /v1/statement?limit=10)
  4. the Tuku-Timestamp value
  5. the Tuku-Nonce value
  6. the Tuku-Customer value, or an empty line
  7. the Idempotency-Key value, or an empty line
  8. 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=43d3a48f47042661338887a7e9067e6a75ba56e1f2407c372fd7c690f8664060

Code

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

Statuserror.codeWhyFix
401signature_requiredA Tuku-* header is missingSend all four Tuku-* headers
401unauthorizedUnknown, 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
401timestamp_out_of_rangeTuku-Timestamp is more than 300 seconds offSet your server's clock (NTP); seconds, not milliseconds
401nonce_invalidThe nonce is not 16 to 64 allowed charactersUse 16 random bytes as hex
401replayedThis nonce was already used with this keyA new nonce for every request, retries too
401payout_signature_invalidMoney out without a valid Tuku-Payout-SignatureSign 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.