Start here
Keys and secrets
Four values, what each is for, where it goes, and what to do if one leaks.
| Value | Looks like | What it does | Environment variable |
|---|---|---|---|
| Key id | tkk_test_… / tkk_live_… | Says which key signs the request. Sent on every request (Tuku-Key). | TUKUPAY_KEY_ID |
| Key secret | tks_… | Signs every request. Never sent. | TUKUPAY_KEY_SECRET |
| Payout secret | tkp_… | A second signature, needed only to send money out (transfers, payouts). | TUKUPAY_PAYOUT_SECRET |
| Webhook signing secret | whsec_… | 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/sdkrefuses 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
| Value | Where in TukuPay | Shown | Needs your PIN |
|---|---|---|---|
| Sandbox key | Developers → My apps → your app → Make a key → Sandbox | Once | No |
| Live key | The same, choose Live (after you go live) | Once | Yes |
| Payout secret | Your app → Payouts → Make payout secret | Once | Yes |
| Webhook signing secret | When you register the app; later: your app → Webhooks → Signing secret → Replace signing secret | Once | Yes (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
- Stop the app on its page (one tap). Every call is refused at once (
403 app_stopped); nothing is paid. - Revoke the leaked key (Keys → Revoke). It stops at once, unlike a rotation.
- If the payout secret leaked, make a new payout secret (the old one stops at once) and lower your payout limits.
- Make a new key, put it on your server, then restart the app with your PIN.
- 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.