Authentication
Merchant API keys, test vs live mode, and whoami.
API keys
Authenticate with a Bearer token:
Authorization: Bearer test_...| Prefix | Environment |
|---|---|
test_ | Test (local / testnet chains) |
live_ | Live (mainnets; requires go-live approval) |
Keys are scoped to one environment. A test key cannot create or read live invoices (and reverse). Live keys only work while the merchant is approved (integrationStatus === "live"); suspended merchants cannot use any API key.
API keys can: create/list/get invoices and call whoami.
API keys cannot: configure webhooks, manage other keys, withdraw, or disburse — use the merchant dashboard for those.
Whoami
curl http://api.localhost:4000/v1/whoami \
-H "Authorization: Bearer test_..."Returns merchantId, organizationId, environment, and apiKeyId.
Idempotency
POST /v1/invoices requires an Idempotency-Key header. Replays with the same key and same body return the original invoice. A different body with the same key returns IDEMPOTENCY_CONFLICT — see Errors.
Rate limits
100 requests/minute per API key. Exhaustion returns 429 with code RATE_LIMITED.