Idempotency and Retransmission
For the official specification, see section 3.4.2 Acceptor Error Handling of the nexo Card Payments Acquirer Message Usage Guide, version 9.0, which details how the Acceptor should handle each failure scenario. Section references on this page are to that guide.
Only AcceptorCompletionAdvice and AcceptorCancellationAdvice messages can be retransmitted (Card Payments Acquirer Message Usage Guide, section 3.3). The gateway answers a retransmitted advice from the stored response, so a retransmission does not reach the acquirer again while the original is held.
Requests, including AcceptorAuthorisationRequest, cannot be retransmitted and are not idempotent. A request sent again is processed as a new transaction. If a request gets no response, reverse it instead of sending it again.
Retransmitting an advice
To retransmit an advice, send the same message again with:
- the same Hdr/MsgFctn, Hdr/XchgId and message body. The body must not change, as the gateway uses it to match the retransmission to its original;
- a new Hdr/CreDtTm;
- Hdr/ReTrnsmssnCntr increased by 1. The first transmission has no counter, or 0.
An advice with no counter, or 0, is an original and is processed, even if its body matches an earlier advice.
The gateway only matches a retransmission against earlier advices from the same POI, with the same Hdr/MsgFctn, received in the last 48 hours.
How the gateway answers a retransmission
- The original advice has completed: the stored response is returned with HTTP 200 and the same transaction outcome. The acquirer is not contacted again. The response carries the retransmission's ReTrnsmssnCntr, a new CreDtTm and a new security trailer.
- The original advice is still being processed, or reached the acquirer without a response being produced: an AcceptorCompletionAdviceResponse or AcceptorCancellationAdviceResponse with Rspn = SUSP (received but not yet processed) is returned. Retransmit again later with a higher counter.
- The gateway has no earlier advice with that body, for example because the original never arrived: the retransmission is processed as the original (section 3.3.2).
- The counter is above the POI's configured retransmission limit (default 5): AcceptorRejection with RejectReason IMSG (invalid message), HTTP 400.
Retransmissions do not have to arrive in order, and each one is answered.
A retransmission that repeats an earlier counter with a new CreDtTm is answered like any other retransmission. The guide does not define this case; this is the gateway's own behaviour. A retransmission that repeats both the counter and the CreDtTm of one already received is a duplicate message.
If two originals arrive with the same XchgId and the same body, both are processed, but their retransmissions can’t be told apart, so the gateway answers them with the response to the first. Use a new XchgId for each new exchange to avoid this.
Other messages: no retransmission
Messages other than AcceptorCompletionAdvice and AcceptorCancellationAdvice, such as AcceptorAuthorisationRequest, are never treated as retransmissions.
- A ReTrnsmssnCntr on these messages is ignored rather than rejected, as the guide requires for an optional element a message does not expect (section 3.4.1.2). It still counts towards duplicate detection.
- A stored response is never returned for these messages.
If no response to a request is received, do not send it again. Instead, reverse the transaction by sending an AcceptorCompletionAdvice with Tx/Rvsl set to true, as a new exchange with a new XchgId (section 3.4.2.1). If the gateway has no successful authorisation to reverse, it responds approved, as there is nothing to reverse.
Retention
- While an advice is being processed, the gateway holds it for 3 minutes, extended each time a retransmission of it arrives. If processing fails before the acquirer is contacted, the advice is forgotten straight away, and its next retransmission is processed as the original.
- Once a response has been produced, or once the acquirer has been contacted, the advice is held for 48 hours, and its retransmissions are answered from the stored response.
- After 48 hours the advice is forgotten, and a retransmission of it is processed as the original.
Not covered
AcceptorDiagnosticRequest and terminal management messages are not retransmitted