An idempotent payment API is one that, given the same idempotency key, returns the same outcome regardless of how many times the request is replayed. In production, retries are not optional — they are the default behavior of every well-behaved client.
The mechanism is straightforward in principle: each write is keyed by an idempotency token, the ledger records the first successful commit under that key, and subsequent requests with the same key short-circuit to the cached result. The discipline is in the edges.
We've found three rules to be load-bearing. First, the key must cover the entire intent of the call — not just the amount, but the full state machine. Second, the cache must persist long enough to cover realistic retry windows, which means days, not seconds. Third, reconciliation must be a first-class concern, not a once-a-month script.
When all three are in place, you stop thinking of retries as a problem and start thinking of them as a guarantee — the system is convergent, and a retry is just a no-op.