Skip to content
Xaalis

Idempotency

Networks fail. When a request times out you don’t know whether it reached Xaalis. Idempotency keys make the retry safe: send the same Idempotency-Key header and you get the original object back instead of a second payment or a second payout.

POST /v1/payments
Idempotency-Key: order-1042
  • Required on POST /v1/payouts, refunds, subscription create/cancel/advance and agent-wallet writes (a request without it gets 400); strongly recommended on POST /v1/payments.
  • Keys are scoped to your merchant account; up to you to make them unique — your order or withdrawal id works well.
  • Same key, same request → the original object (even under concurrent retries for payments).
  • Same key, different parameters → 409 idempotency_conflict (a payment’s amount; a payout’s amount, provider or recipient). Nothing is created.
  • Reuse a key only for a retry of the same operation. A new payment needs a new key.

The Node SDK makes you pass the key on every create, so it stays the same across retries and process restarts — use your own order or withdrawal id.

Keys are scoped to your merchant and the mode: the same key used with a test key and with a live key creates two independent objects.