Conventions

Envelopes, pagination, ids, versioning, and rate limits — the rules that hold across every endpoint.

Response envelopes

Single resources are wrapped in a key named after the resource — { "payout": { … } }, { "recipient": { … } }. Lists always return:

{ "data": [ … ], "hasMore": true, "nextCursor": "pay_ghs_…" }

Pagination

Every list takes limit (1–100, default 20) and cursor. Results are newest first. Pass the previous page’s nextCursor as cursor; it’s null on the last page. Cursors are opaque — don’t build them.

IDs

IDs are prefixed strings that tell you the type at a glance:

Prefix	Resource
pay_	payout (with the currency: pay_ghs_…)
rcp_	recipient
col_	collection
ord_	order
conv_ / qte_	conversion / quote
va_ / addr_	virtual account / crypto address
pl_ / pp_ / cs_	payment link / page / checkout session
whe_ / wev_ / whd_	webhook endpoint / event / delivery
le_	ledger entry
req_	request id (x-request-id header)

Customer-facing ids carry the stack on sandbox: pl_test_…. Balance accounts are <CURRENCY><8 digits>, e.g. GHS12345678.

Versioning

Send chipper-version: 2026-02-20 (the current version). It’s echoed back on every response. Omitting it means “current”. Versions are dates; breaking changes get a new date and the old one keeps working — additive changes (new fields, new endpoints) ship without a version bump.

Rate limits

100 requests per second per API key, sliding window. Over the limit you get 429 rate_limited with details.retryAfter. Back off and retry; for bursts, batch — POST /v1/recipients/bulk and POST /v1/validate/bulk take up to 100 items.

Timestamps

ISO 8601 in UTC: 2026-08-23T20:50:41.000Z.

Headers worth knowing

Header	Direction	Meaning
Authorization: Bearer sk_…	request	your API key
chipper-version	both	API version (see above)
x-request-id	response	quote it to support
webhook-id / webhook-timestamp / webhook-signature	webhook deliveries	Standard Webhooks signing