Authentication

All requests to the Suby.fi v3 API are authenticated with a secret API key sent in the X-Suby-Api-Key header.

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

API keys

Generate keys from your dashboard settings. Each key is shown once at creation — store it securely (a secret manager, never in client-side code or a public repo).

Prefix	Environment	Behaviour
`sk_live_…`	Production	Real card + crypto processing, real funds.
`sk_sandbox_…`	Sandbox	Fully simulated. Test cards, Base Sepolia crypto, no real money.

The environment is inferred from the key prefix — you do not send a separate environment header. LIVE and sandbox data are isolated; a sandbox key never sees LIVE resources and vice-versa.

Sandbox mode

Use a sk_sandbox_… key to build and test end-to-end without moving money:

Card payments use test card numbers (e.g. 4242 4242 4242 4242).
Crypto payments are limited to Base Sepolia (chain ID 84532). If you don’t specify chains/assets, Base Sepolia and its active assets are auto-selected.
Refunds on sandbox card payments skip the provider and mark the payment REFUNDED directly.
Webhooks fire normally, so you can exercise your handlers.

Errors

Authentication failures return 401 with the standard error envelope:

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

Treat your sk_live_… key like a password. If it leaks, revoke and rotate it immediately from the dashboard. Suby will never ask you for your secret key.

Rate limiting

Requests are rate-limited per API key. If you exceed the limit you receive 429 Too Many Requests; back off and retry with exponential delay.

Introduction Quickstart

Get started

Core concepts

API keys

Sandbox mode

Errors

Rate limiting

​API keys

​Sandbox mode

​Errors

​Rate limiting

API keys

Sandbox mode

Errors

Rate limiting