Skip to main content
Value-creating or replacing POST/PUT requests accept — and generally require — an Idempotency-Key header. This includes creating customers, payment routes, webhook subscriptions, API keys, Treasury beneficiaries, payouts, withdrawals, quotes, and conversions. It lets you retry after a network error without creating a duplicate.
Direct-route transfers are created automatically when a route is funded. Treasury is an explicit wallet API, so its payouts, stablecoin withdrawals, conversion quotes and quote acceptance are all idempotent writes.

​
How it works

  • Use a unique key per logical operation (a UUID is ideal). Reuse the same key when retrying that same operation.
  • Persist the key before the first network attempt. A browser refresh, MFA step-up, worker restart, or client timeout must not generate a replacement key for the same action.
  • Same key + same parameters → you get back the original, cached response (with an Idempotency-Replayed: true header). The action runs once.
  • Same key + different parameters → the request is rejected with 409 (idempotency_key_conflict), protecting you from accidentally reusing a key for a different operation.
  • Keys are isolated by tenant account and credential context. Do not deliberately reuse one across separate tenant accounts.
Idempotency keys are scoped to supported POST/PUT writes, which require a secret key (sk_). Read requests (GET) are naturally idempotent and do not need a key. The current PATCH and DELETE resources do not use this header: read current state before retrying an unknown response, as explained on each endpoint page.

​
Unknown money outcomes

If a payout, conversion, or withdrawal response is lost, retry the identical request with the same key. Do not create a replacement operation while the original is accepted, submitted, held, or unknown. Fetch the original by its Wayex ID or your externalReference and inspect its reservation state first. See Operations and reconciliation.

​
Webhooks and ordering

Wayex is event-driven: webhooks are the source of truth for asynchronous state. Do not assume webhook ordering — dedupe by the reference on each event and, when in doubt, fetch the current resource state with a GET. See Developers for subscription setup and signature verification.