Found this when support kept forwarding the same complaint: "my card was declined, I tried again, now it says duplicate order."
Our checkout created one order, then sent the order id to the gateway as the merchant reference. Customer pays, issuer returns a soft decline (05 or 51). Customer fixes the card and hits Pay again. Same order, same reference, second attempt.
The gateway treated the reference as unique per transaction. The retry came back as a duplicate-reference error before it ever reached the issuer. So a recoverable decline became a dead end. About a third of those customers never came back.
We had also half-solved it the wrong way. In one path we generated a fresh reference on every click, which fixed the error but broke the other direction. Double-clicks and network retries of the same attempt produced two real charges.
The fix was to separate two ids we had collapsed into one:
- order_id: stable, one per cart
- attempt_id: new per user-initiated payment, but reused for any network-level retry of that same attempt
The gateway reference is built from attempt_id. Idempotency lives at the attempt level. Reconciliation groups attempts by order.
How do you model order vs attempt in your own systems? Do you keep them in separate tables, or a single payments table with a parent id?
Payneteasy handles this kind of payment flow for merchants and PSPs — see how it works.
Top comments (1)
Separating order from attempt is the right split. The part I would push on is where the gateway reference sits relative to the mandate, because the split holds on cards for a reason that does not travel.
On cards you got away with building the reference from attempt_id because the issuer has no memory of the order. Each attempt is a fresh authorisation against an instrument that is already on file, so a second attempt is cheap and the only thing you are protecting against is your own double-send.
Open banking breaks that. A second user-initiated attempt is not a new reference against the same instrument. It is a new consent, authorised by the customer inside their bank app, which creates a new payment resource at the bank. The idempotency key covers your retry of one attempt and nothing beyond it. Two attempts that both reach the bank are two valid payments, correctly made, and the bank is right to settle both. So attempt-level idempotency does not save you there. The only thing that does is refusing to start attempt two while attempt one is still live, and the statuses do not tell you when live ends, because Pending and AcceptedSettlementInProcess are both legitimate resting places with no promise about when they move.
To your question: parent id on one table, and put the rule on the table rather than in the service. One live attempt per order as a partial unique index, so the second click fails at the database instead of in whichever code path happens to be handling it that week. Two services will eventually disagree about what live means, and the one that is wrong will be the one in the payment path.
The third of customers who never came back is the number worth repeating to anyone who files this under correctness.