API keys
Create a key, choose what it can do, and keep it safe.
Every request carries an API key as a bearer token:
Authorization: Bearer tchoko_live_...There is no OAuth flow and no session. The key is the credential.
Create a key
Open Developers
Sign in to your merchant dashboard and go to Developers.
Click New API key
Give it a name you will recognise later — production-backend, payouts-worker,
reporting. You will have several, and the name is how you tell them apart when deciding
which to revoke.
Choose what it can do
Tick one or more permissions. This is the important step — see below.
Copy the key
It is shown once. We store only a hash and cannot show it to you again. If you lose it, revoke it and make another.
Choosing what a key can do
Three permissions. Tick only what that key actually needs.
| Permission | What it allows | Choose it for |
|---|---|---|
| Collect | Charge numbers, create checkouts, read your collections | Anything that takes payments — your checkout, your storefront backend |
| Disburse | Send money from your balance, read your disbursements | A payout worker, a settlement job |
| Read only | Read collections and disbursements. Creates nothing, moves nothing. | Reporting, dashboards, reconciliation scripts |
They are independent, not levels. Collect does not include Disburse. Read only is not a weaker version of the others — it is a separate choice for something that should never create or move anything.
Which combination
Taking payments only
Collect. This is most integrations.
Taking and sending
Two separate keys — Collect on one, Disburse on the other. Not one key with both.
Reporting or analytics
Read only, on its own.
Use a separate key for disbursement. A key that can collect is low risk if it leaks — somebody creates invoices nobody has to pay. A key that can disburse is your balance.
Put them in one key and the credential sitting in your checkout is also the credential that can empty your account.
Disburse may not be available yet
Disbursement is enabled per account. If the permission is greyed out, ask us to turn it on — we would rather refuse the option than issue a key whose stated power does not work.
Changing what a key does
You cannot add a permission to a key that already exists. To change what a key does: create a new key with the permissions you want, deploy it, then revoke the old one.
This is deliberate — a key already deployed in your systems should never quietly gain the ability to move money without the code around it changing.
Using a key
curl https://connect.tchokopay.com/v1/account/providers \
-H "Authorization: Bearer tchoko_live_..."Keep keys server-side. Never in frontend code, a mobile app, or a public repository — anyone holding your key can act as you.
Revoking
Revoke from the dashboard and the key stops working on the very next request. No delay, no grace period.
If your merchant account is suspended, every key on it stops working at the same moment.
Rate limits
Each key starts at 30 requests per minute and 600 per hour. Limits are per key, so two integrations sharing one key share one allowance — give each its own.
If you need more, we raise it per key. Write to tech@tchokopay.com with the throughput you expect. See rate limits.
Errors
| Status | code | Meaning |
|---|---|---|
401 | UNAUTHORIZED | Key missing, malformed, invalid, or revoked. |
403 | FORBIDDEN | Key is valid but lacks the permission for this endpoint, or your account is not approved. |
The message names the missing permission, so you know which key to create.