What is an idempotency key in payment APIs
An idempotency key is a unique value sent with an API request so that retrying the same request does not create a duplicate operation.
Networks are unreliable. Your server sends a request to create a payout, the connection drops, and you do not know whether the payout was created. If you simply retry, you might pay twice. An idempotency key solves this: you attach a unique value to the request, usually in the Idempotency-Key header, and the API guarantees that repeated requests with the same key return the same result instead of performing the operation again.
The pattern was popularised by payment APIs such as Stripe and is described in an IETF draft for an Idempotency-Key HTTP header. The server stores the key together with the result of the first request. When a retry with the same key arrives, it returns the stored result. If the same key comes with different parameters, a well-designed API rejects it as an error.
Keys must be generated by the client and tied to the business operation, not to the HTTP attempt. A good choice is a UUID created when the operation is initiated and stored with it, or a deterministic value such as “payout-for-order-1234”. The key must stay the same across all retries of that operation, and differ for each new operation.
Typical mistakes: generating a new key for every retry, which defeats the purpose; using the same key for different operations, so the second one is silently ignored; not storing the key and losing it after a crash; and assuming idempotency only for payouts while creating duplicate invoices on retries.
In Moonvex, the Idempotency-Key header is required when creating payments, payouts and subscriptions, so a retried request never creates a duplicate.