API reference
API reference
The Merxian API is a JSON API over HTTPS. Use it to create transactions, send buyers to hosted checkout, and read and refund payments.
Base URL
https://api.merxian.comSandbox and live use the same base URL. The API key selects the environment. See Accounts and environments.
Authentication
Send a secret API key as a bearer token in the Authorization header of every request.
Authorization: Bearer $MERXIAN_API_KEYEach endpoint requires one scope, which the key must hold. See Authentication.
Conventions
| Format | JSON request and response bodies, UTF-8. Send Content-Type: application/json with a body. |
| Field names | camelCase, for example externalReference. Enum values are snake_case, for example past_due. |
| Amounts | Integers in the minor unit of the currency. 14280 in EUR is €142.80. See Money. |
| Times | ISO 8601 in UTC on transactions, payments, and refunds. Epoch milliseconds on checkout sessions and payment links. See Times. |
| Retries | Every create and command request requires an Idempotency-Key header. See Idempotency. |
| Lists | Cursor pagination with limit and cursor. See Pagination. |
| Errors | An HTTP status and a stable code. See the error reference. |
| Version | The path carries the version, /v1. See Versioning. |
Resources
Transactions
A transaction is the payable record of a sale. It holds the lines, the buyer, the amounts, and the tax. Every payment collects a transaction.
Payments
A payment is one intent to collect money for a transaction. Its result arrives later, so read it through webhook events.
Refunds
A refund returns all or part of a payment to the payer. You request it; the result arrives later as a webhook event.
Checkout sessions
A checkout session is a hosted page where one buyer pays one transaction. Times on checkout sessions are epoch milliseconds.
Payment links
A payment link is a reusable URL. Each buyer who opens it gets a new checkout session and a new transaction. Times on payment links are epoch milliseconds.
Products, prices, customers, invoices, payouts, and webhook endpoints are managed in the dashboard. The API has no endpoints for them. Invoices and customers send webhook events.
Client libraries
Merxian does not publish client libraries. Call the API with any HTTP client. The examples show cURL and thefetch function of Node.js 18 or later. They are examples, not an SDK.
OpenAPI description
The reference is generated from an OpenAPI 3.1 description of the public API. Download it from /openapi.json to import the API into an HTTP client or to generate types.