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.