Idempotency Keys — The Unsung Hero of Every Payment System

Think of an idempotency key like a receipt number.

You submit a transaction. Something fails mid-way — a timeout, a network glitch, a server hiccup. You retry. But the system already saw that receipt number. So instead of processing again, it just returns: "Already done."

No double charges. No duplicate transfers. No angry users.

Why this matters

In distributed systems, failures are not exceptional — they're routine. Networks drop packets, servers restart, clients time out and retry. If your payment endpoint processes every request it receives, a single flaky connection can charge a customer twice.

The fix is simple in concept:

1. The client generates a unique key for each logical operation (not each request).
2. The server stores the key with the operation's result.
3. If the same key arrives again, the server returns the stored result instead of re-executing.

Implementation notes

• Store keys with a TTL appropriate for your retry window (24 hours is common).
• The key check and the operation must be atomic — use a unique constraint in your database, not an application-level check.
• Return the original response for repeated keys, including the original status code.

In fintech, retry logic without idempotency isn't safety — it's a liability.