Idempotency

Retry safely: the same request never runs twice.

A network error does not tell you whether your request reached Monerails. Retrying a payout blindly could pay twice. To prevent this, send an Idempotency-Key header on every POST:

curl https://api.monerails.com/v1/payouts \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Idempotency-Key: payout-inv-118" \
  -H "Content-Type: application/json" \
  -d '{"amount": 150000, "currency": "XAF", "recipient": {"type": "mobile_money", "name": "Kossi Mensah", "phone": "237660000001", "operator": "MTN"}}'

How it works#

• The first request with a key runs normally. Monerails saves its status code and response for 24 hours.
• A later request with the same key, on the same endpoint, with the same body (byte for byte) returns the saved response, without running again, with the header Idempotent-Replayed: true. 4xx errors are saved and replayed too.
• The same key with a different body, or on another endpoint, fails with 422 idempotency_key_reused.
• If the first request is still running, a second one fails with 409 idempotency_key_in_use. Wait a moment and retry.
• A 5xx error is not saved: retrying with the same key runs the request again. Monerails answers 5xx only when no money was sent. If a problem occurs after the operation was sent to a payment partner or the card issuer, you get 202 with the object (processing or pending) instead, and that 202 is saved: a retry replays it and never sends the money twice.
• A replayed webhook endpoint creation returns the endpoint without its secret, which is only in the original response.

Keys are scoped to your business and mode, up to 255 characters. Use something tied to the operation in your system (payout-inv-118) or a UUID you store with it. GET and DELETE requests do not need a key.

The header is optional for the API, but send it on every POST that moves money (collections, payouts, settlements, card issuing and funding): without it, a retry after a lost response creates a new operation.

If the response never arrived#

Give each operation a unique client_reference (your order or invoice ID) when you create it. If you never received the response, even after the 24 hours of the key:

1. Look the operation up by that reference: GET /v1/payouts?client_reference=inv_118 (or /v1/collections?client_reference=…).
2. If it is listed, follow it with its id and its webhooks. Do not create it again.
3. Create it again only if the list is empty, with the same client_reference.

Monerails does not reject a second operation with the same client_reference: the check before a new submission is yours.

When to retry#