DeepReach
System Design17 interview questions

Designing Idempotent REST APIs for Payment Systems

Idempotency keys, request deduplication with Redis, handling partial failures, and retry-safe API contracts for financial operations.

RESTIdempotencyPaymentsRedis

Designing Idempotent REST APIs for Payment Systems

Why Idempotency Matters in Payments

Network failures cause clients to retry. Without idempotency, retries cause double-charges.

Idempotency Key Pattern

POST /api/v1/payments
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Type: application/json

{
  "from_account": "ACC-123",
  "to_account": "ACC-456",
  "amount": 1000.00,
  "currency": "INR"
}

Implementation with Redis

java
@PostMapping("/payments")
public ResponseEntity<PaymentResponse> createPayment(
    @RequestHeader("Idempotency-Key") String idempotencyKey,
    @RequestBody PaymentRequest request
) {
    String cacheKey = "idempotency:" + idempotencyKey;

    // Check if already processed
    String cached = redis.get(cacheKey);
    if (cached != null) {
        return ResponseEntity.ok(objectMapper.readValue(cached, PaymentResponse.class));
    }

    // Process and store result atomically
    PaymentResponse response = paymentService.process(request);
    redis.setex(cacheKey, 86400, objectMapper.writeValueAsString(response));

    return ResponseEntity.status(201).body(response);
}

Interview Questions

  1. 1.What is the TTL for idempotency keys and why?
  2. 2.How do you handle concurrent requests with the same idempotency key?
  3. 3.What is the difference between idempotency and at-most-once delivery?
  4. 4.How do you make a GET request idempotent?