Finance is one of the clearest places where API design has to assume the network is unreliable. Users retry. Mobile clients reconnect. Gateways time out. Background workers replay messages.
If the server cannot recognize a logically identical request and return the same outcome safely, the system is not defensive enough for money movement.
What an Idempotent Contract Looks Like
A typical API request includes an idempotency key:
POST /payments
Idempotency-Key: 8b7b1b1c-8c3d-4ff0-a87a-5a148f7d4d4e
The server stores the key with the outcome of the first successful processing attempt. If the same request arrives again, it returns the original result instead of creating a second payment.
That is the important architectural point: idempotency is not a retry trick. It is a server-side contract.
In practice, that usually means persisting the key with a uniqueness guarantee and associating it with the normalized request shape plus the prior response payload or outcome record.
Why This Matters More Than Retry Logic
Retries are normal in distributed systems. Duplicate money movement is not.
Without idempotency, retries can create:
- duplicate charges
- duplicate ledger entries
- inconsistent downstream reconciliation
That is why idempotency belongs in the write path before anyone starts celebrating clever retry middleware.
Better Rule
If the operation can move money or create a durable side effect, design the endpoint to recognize duplicate intent. In finance, idempotency is part of correctness, not just resiliency.
Further Reading