Skip to main content
Payout requests move funds. If a request times out or your connection drops, you can’t tell whether the payout was created. An idempotency key lets you retry safely: Tender processes the request at most once and replays the original response to any retry.

​
Where it is required

The Idempotency-Key header is required on: A request without the header is rejected with 400 before anything is processed. Other endpoints ignore the header.

​
Choosing a key

  • Generate a new, unique key for each payout you intend to make, for example a UUID v4 or your own payout ID.
  • Keys can be up to 200 characters. Leading and trailing whitespace is ignored.
  • Store the key with your payout record before you send the request, so a retry after a crash reuses it.
  • Reuse the key only to retry the same payout with the same request body.
The Idempotency-Key header is separate from x-request-id. Each retry still needs a fresh x-request-id, x-timestamp and signature (see Authentication); only the idempotency key and the body stay the same.

​
How it behaves

Keys are scoped to your merchant account and the endpoint, so the same key used on /payout/fiat and /payout/crypto refers to two different requests. “Same body” means the same fields with the same values, in the same order. Fields the endpoint doesn’t recognise are ignored and don’t affect the comparison. The simplest approach is to serialise the body once and resend exactly those bytes.

​
Errors

  1. Create the key and save it with your payout record.
  2. Send the request.
  3. On a network error, timeout, 429, 500 or 503, retry with the same key and body, using exponential backoff.
  4. On 409 … already being processed, wait a few seconds and retry with the same key.
  5. On any other 4xx, fix the request. If you change the body, use a new key.
  6. Confirm the final state with the payout GET endpoints rather than resending the payout.
Payout routes share a small rate limit, so keep retries spaced out.