Question #35 of 60•Security & Auth•Medium• ~3 min read

How do you implement Idempotency Keys in Payment Gateway Integrations?

Executive Takeaway

Prevent double-charging using unique client-generated Idempotency Keys, Redis distributed locks, and DB transaction states.

Architectural Breakdown & AnalysisFAANG Aligned

Network retries can cause clients to submit payment requests multiple times. Idempotency guarantees that executing an operation multiple times yields the exact same result as executing it once.

Step-by-Step Implementation

  1. Client Generation: Client generates a unique UUID Idempotency-Key header for the transaction request.
  2. Gateway Lock Check: API Gateway attempts to acquire a Redis lock for idempotency_key.
  3. If key exists and status is PROCESSING, return HTTP 409 Conflict or wait.
  4. If key exists and status is COMPLETED, return the cached payment response payload immediately.
  5. Execute & Store: Process payment, record transaction in DB, save response payload in Redis with 24h TTL, and release lock.
NOTE — Stripe API Standard

Stripe handles millions of payment retries safely using client-supplied Idempotency-Key HTTP headers.

Key Architectural Comparison

Idempotency ImplementationStorage TierCollision BehaviorProduction Standard
DB Unique ConstraintPrimary Relational DB (idempotency_key).Returns SQL duplicate key violation (23505).Mission-critical financial ledgers.
Redis Distributed Lock + KeyRedis Cluster (SET key val NX EX 120).Returns HTTP 409 Conflict immediately.High-throughput payment gateways (Stripe).
Previous QuestionHow do Database Connection Pools (HikariCP) prevent thread starvation?Next Question When should you choose Long Polling vs Server-Sent Events (SSE) vs WebSockets?

Continue Learning on Being SDE

Explore deep-dive system architecture modules, low-level object-oriented designs, and interview cheat sheets.