Technical concepts
Requests and responses
The API takes and returns JSON over HTTPS. This page describes the rules that apply to every endpoint.
Format#
- Send every request over HTTPS to
https://api.merxian.com. - Send request bodies as JSON in UTF-8, with the header
Content-Type: application/json. - Field names are camelCase, for example
externalReference. - Enum values are lower snake_case, for example
past_dueoroff_session. - A single resource is the top-level JSON object. A list is
{"data": [...], "pagination": {...}}. See Pagination and filters.
Webhook payloads use snake_case field names. See Receive events.
Unknown fields#
In a request:
- Payment and refund endpoints refuse a field that they do not know, with
400and the codeinvalidRequest. - Other endpoints ignore a field that they do not know.
Send only the documented fields.
In a response, Merxian can add fields and enum values at any time. Your code must ignore fields that it does not know, and must handle an enum value that it does not know. See Versioning.
Times#
The time format depends on the resource:
| Resource | Format | Example |
|---|---|---|
| Transactions, payments, refunds | ISO 8601 string in UTC | "2026-09-14T09:21:07Z" |
| Checkout sessions, payment links | Integer, milliseconds since the Unix epoch | 1789377667000 |
| Webhook payloads | ISO 8601 string in UTC | "2026-09-14T09:24:53Z" |
Send times in the same format that the resource uses. For example, expiresAt on a checkout session is epoch milliseconds, and fromDate on List transactions is an ISO 8601 instant.
Store times in UTC. Convert to a local time zone only for display.
HTTP status codes#
| Status | Meaning |
|---|---|
200 |
The request succeeded. |
201 |
The resource was created. A replay of the same create with the same Idempotency-Key also returns 201. |
202 |
Merxian accepted the request. The result arrives later. See Asynchronous results. |
400 |
The request is not valid, for example malformed JSON, a missing Idempotency-Key, or a bad query value. |
401 |
The API key is missing or not valid. See Authentication. |
403 |
The key does not hold the required scope, or the account cannot do this. |
404 |
The resource does not exist, belongs to another account, or belongs to the other environment. |
405 |
The path does not support this method. The Allow header lists the methods. |
409 |
The request conflicts with the current state, or the Idempotency-Key was used with a different request. |
413 |
The request body is too large. See Request limits. |
422 |
The request is valid, but Merxian cannot apply it to the current data. |
429 |
Too many requests. See Rate limits. |
500 |
An unexpected error occurred. |
502, 503, 504 |
Merxian could not complete the request now. |
The error reference lists the codes in each error body. Retries says which statuses you can retry.
Request IDs#
Every response carries two headers:
X-Request-Ididentifies the request.X-Correlation-Ididentifies the chain of work that the request started.
Log both headers with the method, the path, and the status of each call. Give the X-Request-Id to Merxian when you ask about a request.
Some 429 responses are sent before Merxian sets these headers, and then have neither header.