How does an idempotency key work?
The client generates a unique key for an operation, such as one payout, and sends it with the request. The server stores the result against the key. If the same request arrives again, for example after a network timeout, the server returns the stored result instead of executing it again. Stripe’s documentation describes saving the status code and body of the first request made with a key, returning the same response to retries, rejecting a reused key with different parameters, and removing keys after at least 24 hours. An IETF draft describes an Idempotency-Key HTTP header for making non-idempotent methods such as POST fault-tolerant.
Why does an idempotency key matter in payments?
Timeouts are ambiguous. A request that times out may have failed, or may have succeeded with the answer lost on the way back. As an illustrative example: a marketplace’s payout service times out on 0.5% of 40,000 monthly seller payouts and resends them. Without keys, some of those 200 resends pay sellers twice, and a completed transfer is hard to recover. With keys, every resend returns the original result.
What are the limits?
Keys work within one server’s memory of them: they expire, and they do not cross providers. They also cannot fix a design that creates a new key on every retry. Pair them with your own unique reference per operation, status checks before rerouting, and idempotent webhook handling.
Where does Omno use it?
Omno’s guidance is to process webhooks idempotently, keyed on the transaction, so a repeated delivery never credits or debits a balance twice, and to keep a payout open until a final status arrives rather than retrying blindly. A merchant reference on every request links Omno’s transaction ID to the merchant’s ledger.