Retrying a payout safely
One key, one payout. How to send again without ever paying twice.
Sandbox. The payout operations are in the API's contract and built for the sandbox, where a payout is simulated and never a real transfer. Until Nasfam switches payouts on in an environment, every request there answers 503 payouts_unavailable and nothing is written or held. Live: not yet available.
Availability: Sandbox. Built for the sandbox, on synthetic money. Not live.
A quote and a payout each need an Idempotency-Key. Each key is bound to the first request made with it, so sending the same request again answers with what it made, never a second one.
Requests that take a key
| Request | Key |
|---|---|
POST /payouts/quotes | Required |
POST /payouts | Required |
Make each key before its first attempt, and store it with your own record of the payout, so a retry from anywhere, a restart included, sends the same key. A request without one is refused with idempotency_key_required. See Idempotency for the header itself.
The same key again
- The same key and the same body answers
200withIdempotent-Replayed: trueand exactly the quote or payout the first request made, never its later state. Nothing is priced or sent again. Read a payout's state now with a read. - The same key and another body is refused with
idempotency_key_reused. - The same key while the first is still running is refused with
idempotency_in_progress: send it again shortly. - A
500 internal_erroron a payout is an unknown outcome: send it again with the same key, which never pays twice. - A new attempt after a failure, or after a quote expired, is a new payout: a new quote and a new key. Nothing retries a payout on its own.
Your client_reference is a second guard: it is unique in your workspace for ever, so a second payout under it is refused with duplicate_reference, whatever its key.
Related guides
- Idempotency: the header, its form and replays.
- Send a payout: the request that holds money.
- Payout errors:
idempotency_key_reusedand the rest.
