Authentication
Merchant API keys, test vs live mode, and whoami.
API keys
Authenticate with a Bearer token:
Authorization: Bearer test_...| Prefix | Environment |
|---|---|
test_ | Test |
live_ | Live (requires go-live approval) |
Keys are scoped to one environment. A test key cannot create or read live invoices (and the reverse). Suspended merchants cannot use API keys.
API keys can: create/get invoices, poll status, 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.