The problem
A client sends a charge request but the response is lost to a timeout. The client cannot tell if the money moved, so it retries. Without protection the customer is charged twice.
The idempotency key
The client attaches a unique idempotency key to the request. The server records the key with the result of the first attempt. When the same key arrives again, the server returns the stored result instead of charging again.
- The key must be stable across retries of the same logical request.
- The server stores the key inside the same transaction that performs the charge.
- A retry that arrives while the first is still in flight should wait or return a conflict, not start a second charge.
Lifecycle of a key
- Keep keys long enough to outlast realistic retry windows.
- Tie each key to a request fingerprint so a reused key with different parameters is rejected as an error.
Key idea
An idempotency key lets a payment endpoint absorb retries safely by recording the first outcome and replaying it for duplicates.