Never pay twice: idempotent payouts
A payout request that times out may still have been paid. How idempotency keys, an honest unknown state and reconciliation keep a retry from paying the same person twice.
By Nasfam Business engineering,
On this page
The request that times out
Your system asks a provider to pay a customer. The connection drops before the answer arrives. Did the payout happen?
You cannot know from where you stand. The request may never have reached the provider. It may have reached it and been refused. Or it may have been accepted and paid, with only the answer lost on the way back. All three look identical to you: no answer.
Each wrong guess costs money. Retry as if nothing happened, and you may pay the customer twice. Mark it failed and return the funds to their balance, and you may have given back money that has already left. The safe design starts by refusing to guess.
One key, one payout
HTTP's own specification draws the line. A method is idempotent when repeating a request has the same effect as sending it once, and a client "SHOULD NOT automatically retry a request with a non-idempotent method unless it has some means to know that the request semantics are actually idempotent". A request that creates a payout is not idempotent by nature. An idempotency key is how you give it that means.
- Create the key when you create the payout, before the first attempt. One logical payout, one key, generated once and stored with your own payout record. A random UUID is the usual choice. Never derive it from personal data.
- Send the same key on every retry of that payout. The provider recognises the key and answers with the original result instead of acting again.
- Expect refusals that protect you. The IETF draft for the
Idempotency-Keyheader says a key must not be reused with a different request payload, and that the server should answer422; a retry that arrives while the first request is still being processed should get409. Both mean "do not treat this as a new payout". - Know how long keys are kept. The draft lets a server expire keys, and asks it to publish the policy. One large payments provider documents removing keys after at least 24 hours, after which the same key is treated as a new request. A retry after the window is not protected.
A new key means a new payout. Use one only when you have decided to pay again, and only after the first payout's outcome is known to be a failure.
Three outcomes, not two
Most payout code has two branches: it worked, or it failed. A safe one has three.
- Succeeded. The provider says the payout was made. Consume the reservation and record the provider's reference.
- Failed. The provider says, authoritatively and finally, that no money moved: a validation refusal, an invalid destination, a rejection it documents as terminal. Only now is it safe to release the reservation back to the customer.
- Unknown. Everything else: a timeout, a dropped connection, a
5xx, a response you cannot parse, a status the provider documents as pending. The funds stay reserved, nothing is refunded and nothing is sent again with a new key.
Classify by what your provider documents, not by what seems likely. If its documentation does not say an answer is terminal, it is unknown.
Why a timeout is not a failure
A timeout is a fact about your connection, not about the payout. It measures how long you waited, and says nothing about what the provider did. Treating it as a failure turns "I do not know" into "it did not happen", and that is the exact mistake that pays a customer twice or refunds money that already left.
The same goes for time passing. A payout that has been unknown for an hour is not more likely to have failed than one that has been unknown for a minute. Never release a reservation, issue a refund or send again because a timer expired. Resolve it with evidence.
Reserve before you send
The order of operations is what keeps the balance true while the outcome is open.
- Reserve the amount in a database transaction, together with the payout record and its key, in a state that says it is about to be sent. The customer can no longer spend money that is on its way out.
- Make the external call outside any database transaction or lock. A network call inside a transaction holds locks for as long as the provider takes, and a retried transaction can send the request twice.
- Record the answer with a compare-and-set. Move the payout from its current state to the next only if it is still in the state you read. Two workers that both believe they own the payout cannot both settle it.
- Settle or release exactly once. A reservation is consumed by a success or released by an authoritative failure, never both, and never twice.
Reconcile every unknown
An unknown payout needs an owner whose job is to find out. That is reconciliation: a scheduled process that asks the provider about every open payout and moves it to succeeded or failed on the provider's evidence.
- Look it up by your key or your reference. Most providers let you fetch a payout by the reference you sent. Their webhooks help too, but treat them as a prompt to look it up, as the webhooks guide explains.
- Retry the lookup, never the payment. Asking is always safe; paying again is not.
- Bound the wait, then hand it to a person. A payout that stays unknown past your limit goes to a manual review queue, with the funds still reserved. A person resolves it with the provider and records the decision.
- Reconcile in bulk as well. Compare your records with the provider's statements daily. A payout your system never heard back about shows up there.
Payouts on a blockchain
On a chain, the same rule takes a concrete form. A signed transaction that you broadcast and lost track of may still be confirmed later. Broadcasting that same signed transaction again is harmless: it is one transaction, and the chain accepts it at most once. Building and signing a new transaction for the same payout is a second payment.
On Ethereum and other EVM chains, the nonce is the guard. It is "a sequentially incrementing counter which indicates the transaction number from the account", so two transactions from one account cannot both use the same nonce. Record the nonce and the transaction hash before you broadcast, and resolve an unknown payout by asking the chain about that hash or that nonce.
Solana makes the timing explicit. Its exchange guide says it is critical to wait until a transaction's recent blockhash expires before retrying a withdrawal that does not appear to have been confirmed or finalized, "Otherwise, you risk a double spend." Wait for expiry, check again, and only then decide.
And a payout is not final when it is broadcast. It is final when the chain says so; the finality guide covers what that means on each chain.
Batches: one key per item
Paying many people at once does not change the rules; it multiplies them. Give every item in a batch its own key and its own state, so one invalid destination fails alone and the rest go through. Never retry a whole batch because one item is unknown: retry or reconcile that item.
A checklist
- Every payout has one idempotency key, created before the first attempt and stored with it.
- Retries reuse the key; a new key is used only for a deliberate new payout after a known failure.
- Outcomes are succeeded, failed or unknown, classified by the provider's documentation.
- A timeout, a
5xxor an unreadable answer is unknown, and keeps the funds reserved. - Funds are reserved before the call; the call is made outside any transaction or lock.
- Settlement and release are compare-and-set transitions that happen once.
- Every unknown is reconciled from evidence, and escalated to a person after a bound, never released by a timer.
Sources
Each was read on 12 November 2026. Where a quotation appears in the guide, it is that page's own words.
- RFC 9110, section 9.2.2: idempotent methods. What idempotent means, and when a client may retry automatically.
- IETF draft: the Idempotency-Key HTTP header field (draft 08). Reuse with a different payload (422), a concurrent retry (409), and key expiry. An Internet-Draft, not yet a standard.
- Stripe: idempotent requests. One provider's published practice: keys kept for at least 24 hours, and parameters compared with the original.
- ethereum.org: transactions. The definition of the nonce.
- Solana: exchange integration. Waiting for a blockhash to expire before retrying a withdrawal.
Keep reading
Reliable payment webhooks
Signatures, replay protection, consumers that are safe to call twice, retries and dead letters.
When is a crypto deposit safe to credit?
Confirmations, reorgs, and what each chain's own documentation says to wait for before a deposit is final.
