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.
• Free-text request fields (references, descriptions, names, addresses, metadata keys and values, and so on) must not contain <, >, |, `, { or }, or control characters other than tab and line breaks. A value that does is rejected with 400 validation_failed and the message must not contain unsafe characters for that field in errors[]. Quotes, &, ; and non-ASCII letters are fine.

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 completed, 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.

Processing profiles

An account can be split into processing profiles: optional scopes inside it for a brand, a site, a market or a client you service on behalf of. Each profile has a short code you choose when it is set up (lowercase letters, digits and single hyphens, e.g. client-x). Address a payment, a checkout session or a transfer to a profile by passing its code in processing_profile; the code is echoed back on the payment or transfer, on its order and transactions, and on every webhook about it, and every search and export accepts it as a filter. Omit the field to operate at account scope, which is what an account without profiles always does. An unknown or disabled profile fails validation.

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).