Reference
Authentication
Two key types per environment. Test keys run entirely on the sandbox bank rail, nothing moves real money.
Key types
| Prefix | Where it's used | Visibility |
|---|---|---|
| pk_test_… / pk_live_… | Client-side session init only (e.g. starting a checkout from a browser/bot) | Public, safe to embed |
| sk_test_… / sk_live_… | Server-side, every other API call | Secret, never expose client-side |
Making a request
auth-header.sh
Authorization: Bearer sk_test_51NxK…Public-key-only endpoints (like starting a checkout session from an untrusted client) instead accept x-public-key: pk_test_….
Test vs live
Which environment a request runs in is determined entirely by which key you send, there's no separate flag. Test-mode charges always go through the sandbox bank adapter and settle nothing real.
Idempotency
Every money-mutating POST accepts an Idempotency-Key header. Replaying the same key with the same body returns the original result; the same key with a different body is rejected with idempotency_conflict. Use this for safe retries, payments are unforgiving about double-charges.
Secret keys are shown once, on creation or rotation. Store them in a secrets manager, not source control.