Test mode, live mode and API keys
How the two modes keep test data apart, which key to use where, and how to roll or restrict a key.
Two modes, two sets of data
Every business account has a test mode and a live mode. Payments, receipts, deposits, cards and accounts, phones, payment links, customers, webhook endpoints, events and keys all belong to one mode and are never visible from the other. Your team and your plan span both.
| Area | Test mode | Live mode |
|---|---|---|
| Money | Nothing moves; receipts are any image and deposits are simulated | Real transfers to your real card or account |
| Proof of payment | A receipt you upload on a test checkout and approve, POST / or a simulated deposit in the dashboard | Your customers' receipts your team approves, the bank SMS the optional app forwards, or a deposit you record by hand |
| SMS and email notifications | Never sent | Sent as your notification settings say |
| Plan limits on cards and accounts, phones and links | Not counted | Counted |
| Checkout | Shows a "test payment" ribbon | No ribbon |
The mode comes from the key: there is no mode parameter in the API.
Kinds of keys
Create keys under Developers → API keys, in the mode you want them for.
| Prefix | Kind | Use |
|---|---|---|
sk_test_ / sk_live_ | Secret | Your server. Full access to the API of its mode. |
rk_test_ / rk_live_ | Restricted | A server component that needs less: you choose none, read or write per resource. |
pk_test_ / pk_live_ | Publishable | Reserved. Every API endpoint refuses it today with secret_key_required. |
A secret key is shown once, when you create it. Bezanbecard stores only a hash of it, so a lost key cannot be shown again: create a new one.
Authenticating
Send the key as a bearer token:
curl https://a.bezanbecard.com/v1/account \
-H "Authorization: Bearer sk_test_…"HTTP basic authentication with the key as the user name and no password works too (curl -u sk_test_…:). A request without a key is api_key_missing, an unknown key api_key_invalid, a revoked one api_key_revoked.
Restricted keys
A restricted key names its access to each resource: account, payments, receipts, deposits, payment_links, customers, events, webhook_endpoints, cards and devices. write includes read. A request outside the grant is refused with permission_denied. Submitting a receipt needs both payments and receipts set to write, and expand[]=receipts needs receipts read.
The store plugins work this way: connecting a plugin creates a restricted key with payments, payment_links and customers set to write and events set to read, and nothing else.
Rolling a key
Roll a key from its row in Developers → API keys when it may have leaked or someone who knew it left. Rolling issues a new secret and lets the old one keep working for the hours you choose, from 0 (stop now) to 168 (a week), 24 by default, so you can deploy the new key without downtime. After that the old key answers api_key_expired. Revoking stops a key at once.
Versions
The API is versioned by date. Send Bezanbecard-Version: 2026-10-01 to pin a request; without it the key's own version applies. An unknown version is api_version_invalid. The official libraries send the version they were written for.
Rate limits
Each key may send 100 requests a second in live mode and 25 in test mode. Past that the API answers 429 with a Retry-After header (code rate_limit). The official libraries wait and retry for you.
Live payments and account status
Live payments need an active account. An account an operator restricted, or one restricted for an unpaid invoice, cannot create live payments (account_restricted) while everything else keeps working; a suspended account's keys are refused (account_suspended). GET /v1/account shows the status and what the plan includes.