Idempotency & Exactly-Once Payment Processing
Networks lose responses. Clients retry. Without protection, that retry charges the card twice. An idempotency key and a small lookup table prevent this: the second request finds the work already done and replays the first reply. Same answer, no double charge.
Prerequisites: HTTP retries, database transactions, and unique constraints.
After this: Design an idempotent write path and explain exactly-once effects without overclaiming delivery guarantees.
Suggested first pass: Read sections 1–5, answer each section in your own words, then use the remaining failure modes and exercises as the advanced pass.
Technically reviewed 21 June 2026 · Primary reference: Stripe: Idempotent requests
1. The client generates a unique Idempotency-Key for each action it intends to perform once (for example, one charge).
2. The server stores that key together with the response it returned, in a small lookup table.
3. If the same key arrives again, the server skips the work and returns the stored response.
An unreliable network cannot give a sender perfect knowledge that a response arrived. That makes an end-to-end exactly-once delivery claim unsafe without a clearly bounded transactional system.
Payment APIs instead aim for exactly-once effects: retry delivery at least once, identify repeated attempts with the same key, and make the receiver replay or deduplicate them. State the boundary explicitly—an internal log may offer exactly-once processing while an external payment call still requires idempotency.