Safe retries and orderNumber

orderNumber is unique forever#

orderNumber is unique per merchant across their entire operation, forever. It does not reset daily, monthly or seasonally.

If it repeats, the new transaction is rejected with the response "Transacción duplicada" (duplicate transaction). It does not return the original transaction: it returns a rejection.

The timeout problem#

When a payment call dies on a network error or timeout, you do not know whether the transaction was created. And neither intuitive way out works:

On a network timeout there is no safe retry.

What to do instead#

Query the state before deciding:

1. Call POST /api/v1/consult with the original orderNumber.
2. If the transaction exists, use its result. Do not retry.
3. If it does not exist, then you can retry — and you can reuse the same orderNumber, because it was not consumed.

payment → timeout
           │
           └─→ consult(original orderNumber)
                 ├─ exists     → use that result
                 └─ not found  → retry

Design consequences#

• Generate the orderNumber in your system before calling the payment and persist it. If you generate it on the fly, after a timeout you have nothing to query with.
• Never derive the orderNumber from something that can repeat (recycled cart number, truncated timestamp, resettable counter).
• A "Transacción duplicada" does not mean the charge failed: it means that orderNumber was already used. Query before showing the customer an error.