Technical concepts

Idempotency

An Idempotency-Key makes a request safe to repeat. If you send the same request with the same key again, Merxian returns the first result and does not run the operation twice.

On this page

Which requests need a key
Choose a key
How Merxian uses the key
A safe retry pattern
Current limitations

Which requests need a key#

Every POST and PATCH request must have an Idempotency-Key header. The one exception is Preview a transaction, which stores nothing and needs no key.

GET requests do not change anything, so they need no key.

A create or command request without the header returns 400 with the code ValidationFailed.

Choose a key#

Generate a new UUID v4 for each operation, for example with crypto.randomUUID().
A key has at most 200 characters.
Use one key for one operation. Use the same key for every retry of that operation.
Do not reuse a key for a different operation, even after it succeeded.

Create a transaction with a key

curl -X POST https://api.merxian.com/v1/transactions \
  -H "Authorization: Bearer $MERXIAN_API_KEY" \
  -H "Idempotency-Key: 9b3f6c1e-2a47-4d8b-b5e0-7c1d2e3f4a5b" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "EUR", "lines": [{ "catalogPriceId": "price_4Wm9TqLz2Xb7KdN8r", "quantity": 1 }] }'

How Merxian uses the key#

A key is scoped to your account, the operation, and the key value. Two accounts can use the same key value without effect on each other.

You send	Merxian returns
The same key and the same body again	The first result, with its status. The operation does not run again.
The same key with a different body	`409` with `idempotency_conflict`, `idempotencyConflict`, or `StaleIdempotencyKey`, by endpoint.
The same key while the first payment request still runs	`503` with `providerPending`. Retry later with the same key.

Send retries within 24 hours of the first request. After that, do not rely on a replay.

A safe retry pattern#

Before you call the API, generate the key and store it with your own record, for example with the pending sale.
Call the API with the key.
If the call fails with a network error, a timeout, 429, or a 5xx status, retry with the same key and backoff. See Retries.
If your process stops, read the key from your record and retry with it.
After success, store the Merxian ID with your record.

This pattern prevents a second transaction, payment, or refund when a response is lost.

Current limitations#

Two endpoints do not replay the first result in every case today.

Refunds. A retried Refund a payment request after the first request succeeded can return 422 with refundValidationFailed instead of the first refund. Before you send a new refund with a new key, read the transaction and check refundedAmount, or wait for refund.succeeded or refund.failed.