跪拜 Guibai
← All articles
Java · Backend · Interview

Distributed Idempotency for Payments: The Three Pits and the Three-Layer Defense

By 挖掘狂人 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Payment double-charges and confusing failure states produce customer complaints and support load. This layered design gives Western developers a concrete blueprint for making a single logical action happen exactly once across distributed systems.

Summary

Distributed payment idempotency breaks down in three predictable places. The first is check-then-write in application memory, where two concurrent requests both read the order as unpaid and both deduct. The second is separating token consumption from business success, leaving a window for retries to double-charge. The third is relying on Redis as the final judge when its async replication can lose the token in a failover.

The defense stacks three layers. The entry layer uses Redis SET NX with the order number as the key and a Lua script to atomically consume the token. The business layer uses a state machine UPDATE with WHERE status=0; an affected row count of 0 means someone else already handled it, so the duplicate request returns the correct outcome instead of failing. The data layer adds a unique index on the order number in the payment flow table, so a second insert hits a duplicate key and rolls back the transaction.

A more advanced pattern promotes the idempotency record itself to a table with status (processing, success, failure). This enables result replay for duplicate requests and handles the edge case where the gateway succeeded but the local write failed. The outbox pattern keeps notification messages in the same local transaction as the payment state change, so downstream failures don't stall the money path.

Takeaways
— Redis SET NX with the order number as the key, not a random token, ensures one token per order and survives page refreshes.
— Lua scripts make token consumption atomic; separate GET and DEL commands leave a race window.
— In the business layer, an UPDATE with WHERE status=0 and checking affected rows turns duplicate requests into correct result replays rather than errors.
— A unique index on order_no in the payment flow table is the final backstop that works even if application logic fails.
— Spring marks a transaction rollback-only when a DataIntegrityViolationException surfaces; catching it and continuing causes an UnexpectedRollbackException at commit time.
— An idempotent record table with status 0/1/2 allows result replay and handles the case where the gateway succeeded but the local database write failed.
— The outbox pattern writes notification messages in the same local transaction as the payment state change, so downstream failures don't block the main path.
— Redis is an AP system and cannot serve as the final authority for fund safety; the database must make the final decision.
Conclusions

The atomicity requirement between checking and marking is the real crux; every layer is just a different way to close that gap.

Redis's async replication makes it fundamentally unsuitable for final idempotency decisions; it can only be a fast pre-filter.

Defining idempotency as 'duplicate requests get correct results' rather than 'reject duplicates' aligns the error handling with user-facing correctness.

The advanced idempotent-record table treats idempotency as a stateful entity, enabling result replay and integration with outbox, which a simple token cannot do.

Concepts & terms
SET NX
A Redis command that writes a key only if it does not already exist. It is atomic and used here to create a token that only one request can obtain.
Lua script
A script executed atomically by a single Redis thread, often used to combine multiple operations (like GET and DEL) into one step to avoid race conditions.
Idempotency key
A business-level identifier (like an order number) that ensures a repeated operation does not have a repeated effect. It must be stable and tied to the business entity.
Outbox pattern
A design where messages to downstream systems are written to a local table in the same transaction as the business change, then delivered asynchronously, keeping the main transaction free of external dependencies.
UnexpectedRollbackException
A Spring exception thrown when a transaction marked rollback-only by a caught exception is still committed by the outer context, causing a confusing failure.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗