GitHub ProfileAll Projects
← All Articles

Multi-Region Idempotency for Payment APIs

Designing payment mutation endpoints that remain safe under retries, failover races, and duplicate submit storms across regions.

16 min read
Multi-Region Idempotency for Payment APIs

Payment APIs are where distributed systems bugs become financial bugs. Idempotency design has to be explicit and auditable.

Record Shape

type IdempotencyRow = {
  key: string;
  requestHash: string;
  status: "inflight" | "committed" | "rejected";
  responseJson: string;
};

Failure Handling

  1. Same key + same hash => replay prior response.
  2. Same key + different hash => hard reject.
  3. Inflight collision => client retry with backoff.

Idempotency is a correctness contract, not an optimization layer.

More Articles