Authentication
Server-to-server calls authenticate with a single header. There is no OAuth flow and no bearer token to refresh.
x-api-key: <your key>
content-type: application/jsonWhich endpoints need a key
| Endpoint | Authentication |
|---|---|
POST /api/v1/checkout/initialize | x-api-key, required |
POST /api/v1/checkout/verify | x-api-key, required. The session must also belong to the key’s account. |
POST /api/v1/checkout/submit | None. Knowledge of the unguessable session id is the authorisation. |
How keys are stored
- Only the SHA-256 hash of a key and a short display prefix are kept. The key itself is shown once, when it is minted in the portal.
- Revoking a key sets
revoked_at, and the next request using it gets401 Unauthorized API Key. - A key belongs to one account. Every session, transaction and callback it creates is scoped to that account by Postgres row-level security.
Keep the key on your server.Anything holding this key can open checkout sessions and claim payments for your account. It belongs in an environment variable, never in browser JavaScript, a mobile app bundle or a repository.
Failure responses
| Condition | Status | Body |
|---|---|---|
| No header sent | 401 | { "error": "Missing API Key" } |
| Unknown or revoked key | 401 | { "error": "Unauthorized API Key" } |
| Account not active | 403 | { "error": "Vendor account is not active to process payments" } |
Every other code is listed on the errors page.