Skip to content

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

RequestKey
POST /payouts/quotesRequired
POST /payoutsRequired

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 200 with Idempotent-Replayed: true and 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_error on 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.