The double charge risk
Networks fail. A client sends a charge, the response is lost, and the client retries. Without protection the customer is charged twice. Idempotency makes a repeated request produce the same single effect as the first.
Idempotency keys
The client attaches a unique idempotency key to the request. The server records the key with the result. If the same key arrives again, the server returns the stored result instead of executing the payment again.
Storing the outcome
The key, the request fingerprint, and the response are stored together. A retry with a matching key and body replays the saved response. A mismatched body for the same key is rejected as a conflict.
Practical notes
- Persist the key before calling the payment processor to close the race.
- Give keys a sensible expiry so storage does not grow forever.
- Reject a reused key with a different body as a conflict.
Key idea
An idempotency key lets a retried payment return the original result instead of charging again.