API conventions

Conventions that apply across every endpoint.

JSON & field naming

• All request and response bodies are JSON with snake_case field names (e.g. merchant_reference, created_at).
• Send Content-Type: application/json.
• null and absent fields are equivalent; optional fields may be omitted from responses.

Money & amounts

• Amounts are decimal values in the major unit of the currency (e.g. 42.00 GBP).
• In responses, an amount is a JSON number in plain decimal notation (e.g. 42.00, never scientific notation). Parse it into a decimal type — not a binary float — to preserve precision.
• In requests, you may send an amount as a number or as a string. A string (e.g. "42.00") is recommended, because some JSON libraries silently drop trailing zeros or round when emitting numeric literals. The API accepts both.
• currency is an ISO 4217 three-letter code (e.g. GBP, USD, EUR).

Enum values

Enum-valued fields (such as status, type, and direction) are emitted in lowercase on the wire — e.g. a checkout session status of open or complete, a transaction type of payment. Requests accept enum values case-insensitively, but lowercase is canonical. Treat unknown enum values gracefully (see Versioning).

Dates & times

• Timestamps are ISO 8601 / RFC 3339 with an offset (e.g. 2024-06-22T10:00:00Z).
• Webhook envelope created and signature t values are Unix timestamps in seconds.

Countries & locales

• Country codes are ISO 3166-1 alpha-2 (e.g. GB, US).

Identifiers & references

• Resource IDs are opaque strings with type prefixes (e.g. cs_… checkout session, ord_… order, txn_… transaction). Treat them as opaque — do not parse them.
• merchant_reference is your own identifier for an order. It must be unique per account and doubles as your idempotency key: retrying creation with the same reference will not create a duplicate — you'll get a 409 duplicate_merchant_reference_id. Look the resource up by reference to recover its current state.

Pagination

Search endpoints (POST …/search) accept and return:

Field	In	Notes
page	request	1-based page number (minimum 1).
limit	request	Page size, 1–100.
object	response	Always "list".
data	response	The array of results.
page	response	Current page.
limit	response	Page size used.
total_count	response	Total matching records.
has_more	response	Whether further pages exist.

Results are ordered newest first (by creation time, then ID). Filters supplied in a search body are combined with AND; list-valued filters (e.g. status) match any of the supplied values.

CSV exports

The …/export endpoints stream a CSV file (Content-Type: text/csv) rather than JSON. Unlike JSON responses, CSV export responses are not signed — their integrity relies on TLS. All other responses carry an X-Signature (see Signing).