Skip to main content

​
Secret keys

Every request must include your secret key as a Bearer token:
The key prefix selects the environment:
On production, test keys are rejected. On staging, only live-style behaviour is served. Keep your secret keys server-side; never ship them in client apps or commit them to source control.

​
The customer-id header

Many routes act on behalf of a specific merchant customer (a buyer or seller you manage). These require a customer-id header alongside your secret key:
Routes that require customer-id include wallet, confirm-payment, milestone confirm, disputes (per-customer), payments, cards, and the crypto whitelist.
A few merchant-wide routes must not include a customer-id header, namely List all customers’ disputes, Get escrow feeds, and Resolve dispute & disburse. Sending one will scope the request incorrectly.

​
Merchant super-admin routes

Routes under Merchant Customers require the API key to belong to a merchant super-admin account. A regular customer key cannot create or manage other customers.

​
Common auth errors