Reversal idempotency needs composite identity

What the public implementation shows

The documented P2G contract persists reversal idempotency on originalTxId, endToEndId, and returnId, with reversal listings for reconciliation.

The new return instruction is evaluated against one previously confirmed bill payment. This is the implementation fact behind the note; the architectural reading begins from that visible boundary rather than from an assumed production story.

Operating principleA reversal identity must prove both the new instruction and the payment it is allowed to undo.

The decision behind the mechanism

Composite identity prevents both accidental redelivery and reuse of one return ID against a different original context.

Using only the original transaction blocks legitimate protocol distinctions; using only a return ID cannot prove which payment is being reversed. The mechanism matters because it gives that failure a named boundary, durable evidence, and a controlled response instead of leaving the outcome to timing or operator guesswork.

• Require every original and return identifier in the contract.
• Compare repeated keys against the original payload.
• Reject a changed payload under an existing key.
• Expose reversal records in reconciliation views.

How the control should be operated

Operations should see original payment, return identifiers, reason, financial amount, actor or source, attempts, and current reversal state together.

A repeated reversal request resolves to stored fact rather than another financial action. The reusable lesson is not to copy a class or endpoint in isolation, but to preserve the relationship between identity, state, authority, evidence, and operational ownership.