TukuPay Docs

Start here

Keys and secrets

Four values, what each is for, where it goes, and what to do if one leaks.

ValueLooks likeWhat it doesEnvironment variable
Key idtkk_test_… / tkk_live_…Says which key signs the request. Sent on every request (Tuku-Key).TUKUPAY_KEY_ID
Key secrettks_…Signs every request. Never sent.TUKUPAY_KEY_SECRET
Payout secrettkp_…A second signature, needed only to send money out (transfers, payouts).TUKUPAY_PAYOUT_SECRET
Webhook signing secretwhsec_…TukuPay signs webhooks with it; your server checks them.TUKUPAY_WEBHOOK_SECRET

Optional: TUKUPAY_GATEWAY_URL (default https://gateway.tukupay.dev/v1). The libraries read all of these by themselves.

Where they go

# .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
  • On your server only: an environment variable or a secret manager (Railway or Render variables, Vercel environment variables, AWS Secrets Manager, Doppler).
  • Never in a web page, a browser app, a mobile app, a desktop app you hand out, a Git repository, a log, a screenshot or a support chat. Anything shipped to a user's device can be read by that user.
  • Your website and phone app talk to your server; only your server talks to TukuPay. @tukupay/sdk refuses to run in a browser to stop mistakes.
  • Put the payout secret only on the server that pays out. A server that only takes payments does not need it.
  • Use separate keys for separate servers, so you can revoke one without stopping the others (up to 10 active keys per app).

Making them

ValueWhere in TukuPayShownNeeds your PIN
Sandbox keyDevelopers → My apps → your app → Make a key → SandboxOnceNo
Live keyThe same, choose Live (after you go live)OnceYes
Payout secretYour app → Payouts → Make payout secretOnceYes
Webhook signing secretWhen you register the app; later: your app → Webhooks → Signing secret → Replace signing secretOnceYes (to replace)

TukuPay keeps every secret encrypted and never shows it again. Lost one? Make a new one.

Rotating (changing) them

  • Key: Rotate on the key. You get a new key; the old one keeps working for 24 hours so you can deploy the new one without downtime. Then it stops.
  • Payout secret: making a new one stops the old one at once. Update your server straight after.
  • Webhook signing secret: replace it (with your PIN). For 24 hours each webhook is signed with both the new secret and the old one (Tuku-Signature-Previous), so put the new one on your server within the day (see Webhooks).

If a secret leaks

  1. Stop the app on its page (one tap). Every call is refused at once (403 app_stopped); nothing is paid.
  2. Revoke the leaked key (Keys → Revoke). It stops at once, unlike a rotation.
  3. If the payout secret leaked, make a new payout secret (the old one stops at once) and lower your payout limits.
  4. Make a new key, put it on your server, then restart the app with your PIN.
  5. Look at your statement (only_this_app=true) and Developers → Approvals for anything you did not expect, and tell TukuPay support.

A secret that has been pasted into a chat, an email or a ticket counts as leaked: replace it.

Sessions are not keys

AI assistants and command-line tools that a person runs sign in through the browser instead and get a session (tps_…) that lasts one hour. You never copy it anywhere. See Sessions and API keys.