Authentication

Send your secret key in the X-Suby-Api-Key header on every request.

curl https://api.beta.suby.fi/v3/payments \
  -H "X-Suby-Api-Key: sk_live_your_key_here"

Keys

Generate keys in dashboard settings. A key is shown once · store it in a secret manager, never in client-side code or a repo.

Prefix	Environment	Behaviour
`sk_live_…`	Production	Real processing, real funds.
`sk_sandbox_…`	Sandbox	Fully simulated. No real money.

The environment comes from the prefix · there is no environment header. LIVE and sandbox data are isolated.

Treat sk_live_… like a password. If it leaks, rotate it from the dashboard. Suby will never ask you for it.

Cards · test numbers, e.g. 4242 4242 4242 4242.
Crypto · Base Sepolia only (chainId 84532). Auto-selected if you specify nothing.
Refunds · skip the provider, mark the payment REFUNDED directly.
Saving a card · a setup session with the test card stores a pi_… you can then debit off-session.
Webhooks · fire normally.

401 on a missing or invalid key, 429 when rate-limited (per key · back off and retry).

{ "success": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" } }