Core concepts

A few conventions hold across the whole API. Learn them once and every endpoint behaves predictably.

Resources and objects

Every resource is a JSON object with a stable id and an object field naming its type (charge, customer, invoice, …). Related resources are referenced by flat *_id fields (e.g. customer_id, invoice_id) which you can hydrate on demand — see expand.

Live vs test (livemode)

Test and live data live in separate database schemas. Choose the schema per request with the X-Test-Mode header; every response reports which one it came from via the livemode boolean. See Authentication → Test vs live mode.

Pagination

Every list endpoint returns the same page-based envelope. Page through with page and limit:

{
  "object": "list",
  "data": [ /* … */ ],
  "page": 1,
  "limit": 20,
  "total_items": 128,
  "total_pages": 7
}

total_items is the total number of matching records across all pages, and total_pages is ceil(total_items / limit).

Expanding related objects

Pass ?expand[]=customer&expand[]=invoice on a retrieve or list call to receive the hydrated related object alongside its flat id. The flat *_id field is always present; the expanded object only appears when requested. See the dedicated expand guide.

Idempotency

Mutating operations that must never double-apply (such as transfers) accept an idempotency_key. Replaying the same key returns the original result instead of performing the action twice; a conflicting replay surfaces as E1401 (Idempotency key replay detected). Generate a unique key per logical operation and reuse it on retries.

Asynchronous actions (next_action)

Some payments cannot complete in a single request — a QR code must be scanned, or the buyer must be redirected to authorize. These responses include a next_action array describing what the client should do next (display a QR, open a redirect URL, confirm inline). The final state arrives later via webhooks. Poll or listen for the webhook rather than blocking on the original request.

Multi-tenancy: applications & countries

PaymentGateway is multi-tenant. An account can belong to several applications, and an application can operate in multiple countries. User-token requests select the active application/country on the session; some endpoints also accept an X-Country header (a two-letter code such as TH) to scope the call.

What's next