Idempotent Payment Deduplication: Handle Retries Without Losing the Original Attempt

Your checkout sends a payment request. The connection times out. The customer presses Pay again.

The useful question is what your system knows about the first instruction. It may be pending, its processor outcome may be unknown, or a terminal response may already be stored. Those states require different actions.

We will build a small reference state machine that makes those actions visible, implement it in Python and TypeScript, and step through a timeout in a guided lab. The model never calls a payment provider. It teaches the contract a real service must preserve around that call.

Give one instruction a stable identity

An idempotency key identifies an instruction within a namespace. In this tutorial the namespace is:

(merchant_id, operation, key)

That is a structured tuple. Concatenating fields with an unescaped separator can make different tuples collide. The implementations use a tuple in Python and a JSON-encoded tuple in TypeScript.

For one merchant's capture request, the payload signature is:

("payment-v1", payment_id, amount_minor, currency)

The first request binds this signature to the scoped key. A retry with the same signature refers to the same instruction. Changing the amount, currency, or payment resource while retaining that identity produces a conflict.

The related foundation tutorial Identifiers, Keys, Joins, and Data Grain explains why identity depends on context. Here, shop-a / capture / K1 and shop-b / capture / K1 are distinct contexts. Capture and refund also have distinct scopes.

The small signature is an explicit teaching choice. A real adapter must include every field capable of changing the operation, such as a destination or fee instruction. Keep integer money in upstream-defined minor units. Our USD example uses 2,500 cents, or USD 25.00; the reducer does not infer scales for other currencies.

Keep uncertainty visible

Look at the timeout branch in this diagram. It preserves the original attempt.

Three stored states are enough for the lesson:

A timeout does not establish a failed payment. A raw server error also cannot establish that by itself. If a processor may have acted, keep the outcome unknown and investigate the original attempt. A completed resolution is a trusted internal observation; it must never be accepted directly from an untrusted checkout client.

Observation time is when your system learns a result. It can be later than the underlying action. This is the same distinction introduced in Timestamps, Time Zones, Calendars, and Observation Time. Our event array is ordered by knowledge time, so a future response cannot repair an earlier decision retrospectively.

Decide at one atomic boundary

The request path is a lookup followed by one controlled transition:

Only creating a reservation permits a processor submission. The reference reducers serialize events as if each transition committed atomically. They are single-process educational code, with no durable storage or distributed lock.

In a real service, concurrent requests need a unique durable reservation rather than separate unlocked reads and inserts. PostgreSQL's unique conflict arbitration is one relevant database primitive. It does not make the database commit and a remote processor call one atomic action. Recovery across that gap still needs a durable workflow, processor-side identity, and reconciliation.

Walk through a synthetic timeout

Every amount, identifier, time, and outcome below is an invented teaching input. Expected decisions are author-derived, with a 100 ms completed-record retention interval. These milliseconds are selected to expose a boundary, not recommend a production duration.

No additional submission permission is emitted between the first reservation and that replay. The client can receive the stored result even though its original network response was lost.

The full 12-event fixture then changes the boundaries: shop-b uses K1 in its own namespace; shop-a uses K2 for the same payment; and shop-a reuses K1 exactly at expiry. Each can create a separate reservation. Four reservations appear across the full trace, with three terminal results. That does not prove four completed charges.

Make retention part of the contract

Our application policy starts retention when a terminal response is stored:

$t_{expiry} = t_{completed} + T.$

Here $T$ is retention in milliseconds. The original result was stored at 4 ms, so the author-derived expiry is 4 + 100 = 104 ms. At 103 ms a matching retry replays. At exactly 104 ms the next request may remove the completed record and reserve a new generation, producing EXPIRED_KEY_EXECUTE.

Pending and unknown records never auto-expire in this model. A recovery process must resolve them; a clock advancing does not establish that no funds moved.

The narrow invariant for one scoped key and retained generation $g$ is:

$\sum_{i\in g} \mathbf{1}(execute_i) \le 1.$

The indicator counts permission to submit. It does not guarantee end-to-end exactly-once settlement, protection after losing the state, or deduplication across different keys. A permanent business constraint may be required when an instruction must never repeat.

Implement a reducer you can inspect

The Python and TypeScript implementations take a batch of events plus retention_ms and return one immutable output snapshot per event. No network or financial account is touched. This excerpt illustrates the request branch; complete runtime validation, resolutions, and stale-token checks are in the downloadable implementations.

if (!row) {
  // Create one reservation at the atomic boundary.
  decision = expired ? "EXPIRED_KEY_EXECUTE" : "EXECUTE";
} else if (row.signature !== signature) {
  decision = "CONFLICT";
} else if (row.state === "pending") {
  decision = "IN_PROGRESS";
} else if (row.state === "unknown") {
  decision = "RECONCILE";
} else {
  decision = "REPLAY";
}

Each output includes execute, an attempt token, current state, expiry, and a nullable cached response. Attempt tokens stop stale workers from replacing a newer local generation. They cannot undo a payment a remote worker already submitted.

The strict JSON schema rejects missing or extra fields, nonpositive or fractional amounts, booleans, nonfinite values, unsafe integers, malformed identifiers, unsupported operations, and reversed observation times. Currency is a three-letter uppercase label, not an assertion of ISO membership. All numeric operations stay within the JavaScript safe-integer range, and expiry addition is checked before processing.

Test meaning across languages

The same fixture file defines 13 valid and 23 invalid batches. Both implementations must match the expected decisions and error codes, and the parity check compares complete output objects. Additional checks cover:

• 500 matching pending retries with exactly one reservation.
• Exact expiry equality, and replay one millisecond before it.
• Pending and unknown states surviving the completed-record retention interval.
• Changed payloads, tenant/operation isolation, and collision-safe scope encoding.
• A stale completion after a newer generation was reserved.
• Immutable terminal outcomes, including declines and determinate error responses.
• Prefix causality: processing the first few events yields the same earlier outputs as the full trace.
• Input isolation and response snapshots that cannot mutate one another.

These checks prove the reference contract under serialized transitions. Database races, storage recovery, webhook authenticity, and real processor integration require additional implementation-specific tests.

Try the guided lab

The embedded Payment retry lab uses the same reference logic and synthetic scenarios. Start with the canonical timeout, then choose the expiry/stale-worker scenario or the failure/unknown scenario. Step through events, move back, play, pause, reset, or change completed-record retention. Notice that changing retention affects completed expiry while unknown attempts still require reconciliation.

The lab begins after the first reservation so the initial state is informative. Its audit table reveals results only through the current observation. Reduced-motion mode advances one step at a time without a playback timer.

The static diagrams and worked table above preserve the lesson without scripts. Open the standalone lab.

Compare actual provider contracts

The model is an application-owned policy. Provider adapters must preserve the actual provider's version and scope:

Sources checked 24 October 2026. No universal processor retention duration is asserted. Historical-example decision: not useful; these synthetic transitions teach the exact boundary without inventing an incident or observed financial loss.

Connect submission safety to accounting

You can now explain which requests may execute, preserve uncertainty after a timeout, replay a terminal response, and test where a key's protection ends. The next proposed tutorial is Double-Entry Posting Engine, followed by Idempotent Journal Posting and Three-Way Payment Reconciliation. Those catalog topics remain unbuilt; this lesson establishes the payment identity they can build on.

See the canonical README and REFERENCES.md in this package for the full schema, evidence roles, and reproducibility commands.