BackendForFintech

Idempotent Transaction Model

Architectural overview

Every mutation at the API boundary must be idempotent. The client sends an idempotency key; the server stores the result of the first request and returns it for subsequent requests with the same key. Downstream operations (ledger, gateway) must use the same key for deduplication.

Tradeoffs

  • Key storage adds latency and storage; TTL and scope (per tenant) limit growth.
  • Deterministic processing can require more careful ordering and idempotent gateway adapters.

Scaling considerations

Store idempotency state in a fast store (e.g. Redis) with fallback to database. Use key prefix by tenant. Replicate or shard by key hash.

Common pitfalls

  • Deriving key from request body so retries reuse the same key incorrectly.
  • Not propagating idempotency to gateway calls, causing duplicate charges on retry.

Implementation notes

http
POST /v1/payments
Idempotency-Key: <uuid>
→ 200 + cached response (or 201 on first request)