Skip to main content
A few conventions apply to every endpoint.

Base URLs

Headers

Always send Content-Type: application/json when you include a body, and read/write JSON.

Idempotency

Value-moving endpoints accept an idempotency key so a retry never double-executes. On CaaS transfers and withdrawals, pass idempotency_key in the body:
On WaaS transfers, idempotency is a header and it is mandatory:
The key must be 16 to 128 characters; a transfer without one is rejected with 400. Replaying the same key returns the original transfer instead of sending a second one, and GET /wallet/{customer_id}/transfers/{key} reads the outcome back — so after a timeout, retry with the same key rather than generating a new one. See WaaS transfers. On other Payments endpoints, send a stable reference on create operations (e.g. checkout) and reconcile against it. Reusing the same reference lets you safely retry.

Amounts

  • Payments checkout amounts are decimal numbers in the stated currency.
  • WaaS transfers take amount as a string plus a unit: "decimal" (whole coins, the default) or "base" (smallest unit, e.g. wei/satoshi).
  • CaaS amounts are decimal strings; stablecoin vs fiat fields are named explicitly (stablecoin_amount, local_fiat_amount).
Always send money amounts as strings where the API asks for a string, to avoid floating-point rounding.

Pagination

List endpoints accept page and limit query parameters:

Timeouts & retries

Retry 429 and 5xx with exponential backoff and jitter. Never retry a non-idempotent write without an idempotency_key or a stable reference. See Errors.