Void and refund
Void (reversal)
You can cancel the following transaction types before end of day:
- Sale (purchase)
- Return (linked refund)
- Credit (naked refund)
- Initial preauthorisation
- All transactions realted to a preauthorisation (excluding the preauthorisation completion)
- Preauthorisation completion (post authorisation)
There are 3 options to cancel a transaction via nexo using:
- AcceptorCompletionAdviceV06 - caaa.003.001.06, description limited to cancellation and reversal scenarios
- AcceptorCancellationRequestV06 - caaa.005.001.06
- AcceptorCancellationAdviceV06 - caaa.007.001.06
Independent of the chosen message type, you would also need to consider the common elements of a nexo message,.
Use these tables together with the nexo Acquirer v6 Message Definition Report and the corresponding XSD.
Presence: m = mandatory, c = conditional, o = optional, - = not used by the Gateway for that message.
Message overview
| Message | Purpose | How cancellation behavior is selected |
|---|---|---|
AcceptorCompletionAdviceV06 (caaa.003.001.06) | Reports that completion failed and that the preceding financial operation must be reversed. | The Gateway evaluates TxCaptr, TxTp, TxSucss, and Rvsl. This document does not cover normal completion or post-authorisation. |
AcceptorCancellationRequestV06 (caaa.005.001.06) | Requests cancellation or asks whether a referenced transaction can still be cancelled. | Tx/TxCaptr=true executes the cancellation. Tx/TxCaptr=false performs only an eligibility check. |
AcceptorCancellationAdviceV06 (caaa.007.001.06) | Advises that a completed transaction was cancelled or was not financially transferred or cleared. | The message type itself selects cancellation-advice processing. TxSucss, Rvsl, and FailrRsn describe why the cancellation occurred. |
Common elements
The following fields are common to the three messages. Message-specific transaction fields are documented in the later sections.
| Tag | Description | Completion Advice | Cancellation Request | Cancellation Advice |
|---|---|---|---|---|
Hdr/PrtcolVrsn | Protocol version. Use 6.0. | m | m | m |
Hdr/XchgId | Exchange ID assigned by the terminal for this message. | m | m | m |
Hdr/ReTrnsmssnCntr | Retransmission counter. | o | - | o |
Hdr/CreDtTm | Date and time when the message was created. Include a timezone. | m | m | m |
Hdr/InitgPty/Id | Identifies the sending terminal host or application. | m | m | m |
Hdr/RcptPty/Id | Identifies the configured Gateway recipient. | o | o | o |
Hdr/Tracblt/... | Optional traceability information. | o | o | o |
Envt/Acqrr/Id/Id | Acquirer ID. The Gateway requires the value even where the XSD marks its parent block optional. | m | m | m |
Envt/Acqrr/ParamsVrsn | Version or load timestamp of the parameters used by the terminal. | m | m | m |
Envt/Mrchnt/Id/Id | Merchant ID. The Gateway requires the value even where the XSD marks its parent block optional. | m | m | m |
Envt/Mrchnt/CmonNm | Merchant name supplied by the terminal. | o | o | o |
Envt/Mrchnt/LctnAndCtct/PstlAdr/... | Merchant address. If PstlAdr is present, TwnNm and Ctry are required by the XSD. | o | o | o |
Envt/Mrchnt/LctnAndCtct/AddtlCtctInf | Additional merchant contact, station, or tenant information. | o | o | o |
Envt/POI/Id/Id | Terminal ID. | m | m | m |
Envt/POI/Id/ShrtNm | Gateway terminal ID when it differs from the acquirer terminal ID, for example in a Girocard setup. | o | o | o |
Envt/POI/GrpId | Gateway store or POI group ID. | o | o | o |
Envt/POI/Cpblties | POI capabilities block. The Gateway requires this block. | m | m | m |
Envt/POI/Cpblties/CardRdngCpblties | Card-reading capabilities supported by the POI. | o | o | o |
Envt/POI/Cpblties/CrdhldrVrfctnCpblties | Cardholder-verification capabilities supported by the POI. | o | o | o |
Envt/POI/Cpblties/OnLineCpblties | POI online capability. ONLN means online, OFLN means offline, and an absent or different value permits both. | o | o | o |
Envt/POI/Cpblties/MsgCpblties/Dstn | Message destination. CRDO requests the electronic-receipt indicator. The other destination values do not change cancellation routing. | o | o | o |
Envt/POI/Cpblties/MsgCpblties/AvlblFrmt | Accepted by the XSD but not evaluated for cancellation processing. | - | - | - |
Envt/POI/Cpblties/MsgCpblties/NbOfLines | Accepted by the XSD but not evaluated for cancellation processing. | - | - | - |
Envt/POI/Cpblties/MsgCpblties/LineWidth | Accepted by the XSD but not evaluated for cancellation processing. | - | - | - |
Envt/POI/Cpblties/MsgCpblties/AvlblLang | Accepted by the XSD but not evaluated for cancellation processing. | - | - | - |
Envt/POI/Cmpnt/... | Optional terminal, device, response-capability, or operating-system information. See: link | o | o | o |
Envt/Card | Card environment block. It is optional for Completion Advice and mandatory in the Cancellation Request and Cancellation Advice XSDs. Copying the original card brand and applicable card data is recommended. | o | m | m |
Envt/Card/PrtctdCardData/... | Protected card data. Use this form when card data must be supplied in production. | c | c | c |
Envt/Card/PlainCardData/... | Plain PAN, expiry date, sequence number, or track data. Use only in non-production testing; do not send clear card data in production. | c | c | c |
Envt/Card/IssrBIN | Issuer BIN. | o | o | o |
Envt/Card/CardCtryCd | Card country code. | o | o | o |
Envt/Card/CardCcyCd | Card currency code. | o | o | o |
Envt/Card/CardPdctPrfl | Card product profile used for grouping and reconciliation. | o | o | o |
Envt/Card/CardBrnd | Card brand. Copy the value from the original transaction when available. | o | o | o |
Cntxt/PmtCntxt | Payment context block. The Gateway requires this block. | m | m | m |
Cntxt/PmtCntxt/CardPres | Indicates whether the card was present. | o | o | o |
Cntxt/PmtCntxt/CrdhldrPres | Indicates whether the cardholder was present. | o | o | o |
Cntxt/PmtCntxt/OnLineCntxt | Indicates whether the original processing context was online. | o | - | o |
Cntxt/PmtCntxt/AttndncCntxt | Attendance context. When absent, the Gateway treats the transaction as attended. | o | o | o |
Cntxt/PmtCntxt/TxChanl | Transaction channel. It is considered for Completion Advice but not for the two cancellation messages. | o | - | - |
Cntxt/PmtCntxt/CardDataNtryMd | Card-data entry mode. The Gateway requires this field. | m | m | m |
Cntxt/PmtCntxt/FllbckInd | Fallback indicator: FFLB, SFLB, or NFLB. | o | o | o |
Cntxt/SaleCntxt/SaleId | Sale system or workstation ID. | o | o | o |
Cntxt/SaleCntxt/CshrId | Operator or cashier ID. | o | o | o |
Cntxt/SaleCntxt/InvcNb | Invoice number used for reporting. | o | o | o |
Tx/MrchntCtgyCd | Merchant category code. | m | m | m |
Tx/CardPrgrmmPropsd | Card programme proposed by the terminal. | o | o | o |
Tx/TxId/TxDtTm | Date and time of the current message. Include a timezone. | m | m | m |
Tx/TxId/TxRef | Reference ID of the current message. | m | m | m |
Tx/InitrTxId | Initiator transaction ID used for correlation. | o | o | o |
Tx/RcncltnId | Reconciliation ID associated with the message. | o | o | o |
Tx/TxDtls/Ccy | Transaction currency. It is mandatory in Completion Advice and optional in the cancellation message XSDs. Copy the original currency when known. | m | o | o |
Tx/TxDtls/TtlAmt | Total amount. If the amount is unknown for a cancellation, send 0; the Gateway then uses the referenced transaction amount. | m | m | m |
Tx/TxDtls/ICCRltdData | EMV data, when applicable. | o | o | o |
SctyTrlr/AuthntcdData | Message Authentication Value. Send it when message security or MAC validation is enabled for the connection. | m | m | m |
Acceptor Cancellation Advice
AcceptorCancellationAdviceV06 - caaa.007.001.06
Root path: Document/AccptrCxlAdvc/CxlAdvc
The message type itself selects cancellation-advice processing. The transaction-result fields describe whether the advice represents an explicit cancellation or a failure-driven automatic void.
Cancellation conventions
| Scenario | TxSucss | Rvsl | FailrRsn |
|---|---|---|---|
| Explicit cancellation | true | true | Omit |
| Terminal failure or automatic void | false | true | Supply at least one recognized reason |
Message-specific elements
| Tag | Description | Presence |
|---|---|---|
Hdr/MsgFctn | Identifies an Acceptor Cancellation Advice. Use CCAV. | m |
Tx/SaleRefId | Order ID of the original transaction. Use it when the complete Tx/OrgnlTx key is not supplied. The order must already exist in the Gateway. | c |
Tx/OrgnlTx | Identifies the transaction to cancel. Supply this block unless Tx/SaleRefId identifies the existing Gateway order. The complete original key is the least ambiguous option. | c |
Tx/OrgnlTx/TxId/TxDtTm | Date and time of the original transaction. Mandatory within OrgnlTx. | c |
Tx/OrgnlTx/TxId/TxRef | Reference ID of the original transaction. Mandatory within OrgnlTx. | c |
Tx/OrgnlTx/POIId/Id | Terminal ID of the original transaction. Required when the original terminal differs from the current terminal and recommended for an unambiguous lookup. | c |
Tx/OrgnlTx/POIId/ShrtNm | Original Gateway terminal ID when it differs from the acquirer terminal ID. | o |
Tx/OrgnlTx/RcptTxId | Original recipient transaction ID. A complete OrgnlTx/TxId key takes lookup precedence. | o |
Tx/OrgnlTx/TxTp | Transaction type of the original transaction. Mandatory within OrgnlTx; normally use CRDP for a card payment or RESA for a reservation or pre-authorisation. | c |
Tx/TxSucss | Use true for an explicit cancellation and false for a terminal-failure or automatic-void scenario. | m |
Tx/Rvsl | Reversal indicator. Use true. | m |
Tx/FailrRsn | Required when TxSucss=false; omit for an explicit cancellation. See Failure reasons. | c |
Tx/RcptTxId | This current-message field is not used by the Gateway for Cancellation Advice. Use Tx/OrgnlTx or Tx/SaleRefId to identify the original transaction. | - |
Cancellation Advice response
AcceptorCancellationAdviceResponseV06 (caaa.008.001.06) does not contain Tx/TxDtls. It therefore cannot return the amount actually voided or reversed. A terminal that needs the final cancellation amount must use Acceptor Cancellation Request and process the corresponding caaa.006.001.06 response.
Acceptor Cancellation Request
AcceptorCancellationRequestV06 - caaa.005.001.06
Root path: Document/AccptrCxlReq/CxlReq
Cancellation behavior
Tx/TxCaptr | Result |
|---|---|
true | The Gateway creates and submits the cancellation or void for the referenced transaction. |
false | The Gateway only checks whether the referenced transaction can still be cancelled. No cancellation is submitted. |
Message-specific elements
| Tag | Description | Presence |
|---|---|---|
Hdr/MsgFctn | Identifies an Acceptor Cancellation Request. Use CCAQ. | m |
Tx/TxCaptr | Selects execution or eligibility check. Although optional in the XSD, the Gateway requires the value. | m |
Tx/SaleRefId | Order ID associated with the referenced transaction. | o |
Tx/OrgnlTx | Identifies the transaction to check or cancel. This block is mandatory in caaa.005.001.06. | m |
Tx/OrgnlTx/TxId/TxDtTm | Date and time of the original transaction. If Tx/OrgnlTx/TxId/TxDtTm is unknow, use the same value as Tx/TxId/TxDtTmIf those values are identical, then the Gateway will use one of the following XML tags (depending on presence): Tx/OrgnlTx/RcptTxIdTx/RcptTxIdTx/SaleRefId | m |
Tx/OrgnlTx/TxId/TxRef | Reference ID of the original transaction. If Tx/OrgnlTx/TxId/TxRef is unknow, use the same value as Tx/TxId/TxRefIf those values are identical, then the Gateway will use one of the following XML tags (depending on presence): Tx/OrgnlTx/RcptTxIdTx/RcptTxIdTx/SaleRefId | m |
Tx/OrgnlTx/POIId/Id | Terminal ID of the original transaction. Required when it differs from the current terminal and recommended for an unambiguous lookup. | c |
Tx/OrgnlTx/POIId/ShrtNm | Original Gateway terminal ID when it differs from the acquirer terminal ID. | o |
Tx/OrgnlTx/RcptTxId | Original recipient transaction ID. | o |
Tx/OrgnlTx/TxTp | Transaction type of the original transaction. This value is mandatory within OrgnlTx. | m |
Tx/RcptTxId | Recipient transaction ID associated with the current request. It can carry a Gateway transaction or order identifier, but the complete original key takes precedence. | o |
Tx/TxTp | Not part of the current transaction structure for caaa.005.001.06. The original transaction type belongs in Tx/OrgnlTx/TxTp. | - |
Tx/TxSucss | Not part of the Cancellation Request transaction structure. | - |
Tx/Rvsl | Not part of the Cancellation Request transaction structure. | - |
Tx/FailrRsn | Not part of the Cancellation Request transaction structure. | - |
Cancellation Response and actual amount
AcceptorCancellationResponseV06 - caaa.006.001.06
Root path: Document/AccptrCxlRspn/CxlRspn
The following response rule is planned for release 26.04. It is not yet confirmed as deployed.
After an approved Tx/TxCaptr=true cancellation, the Gateway returns the amount that was actually voided, reversed, or returned in Tx/TxDtls/TtlAmt. The response reports the final approved amount rather than simply echoing the amount submitted in the request.
| Request or processing result | caaa.006 response behavior |
|---|---|
| The request contains the correct non-zero amount | Tx/TxDtls/TtlAmt contains the final approved cancellation amount, which will normally equal the submitted amount. |
The request contains Tx/TxDtls/TtlAmt=0 because the amount is unknown | The Gateway resolves the applicable amount from the referenced transaction and replaces zero with the amount actually cancelled. |
| A full or partial pre-authorisation void changes the effective amount | The response contains the final amount approved by the Gateway after the void amount has been determined. |
| The cancellation is processed as a return | The response contains the amount actually returned. |
Tx/TxCaptr=false requests only an eligibility check | No cancellation is executed; the actual-cancellation-amount rule does not apply. |
| Response tag | Description | Presence |
|---|---|---|
Tx/TxDtls/Ccy | Currency of the final approved cancellation amount. | m |
Tx/TxDtls/TtlAmt | Amount actually voided, reversed, or returned after successful cancellation processing. | m |
Acceptor Completion Advice used for cancellation or reversal
AcceptorCompletionAdviceV06 - caaa.003.001.06
Root path: Document/AccptrCmpltnAdvc/CmpltnAdvc
This section covers only cancellation and reversal. It intentionally excludes successful completion, post-authorisation, and pre-authorisation completion.
Cancellation behavior
| Scenario | TxCaptr | TxTp | TxSucss | Rvsl | FailrRsn | Result |
|---|---|---|---|---|---|---|
| Failed financial completion requiring automatic reversal | true | CRDP or CAFT | false | true | Supply a recognized reason | The Gateway reverses the referenced operation. |
| Failed non-capture completion reported as cancellation advice | false | CRDP or CAFT | false | Does not select this path | Optional | The Gateway processes the message as cancellation advice. |
For an automatic reversal, a recognized FailrRsn preserves the actual failure cause. If it is omitted, the Gateway can use a generic customer-cancellation reason.
Message-specific elements
| Tag | Description | Presence |
|---|---|---|
Hdr/MsgFctn | Use RVRA for reversal advice without financial capture or FRVA for financial reversal advice. The transaction fields, rather than this value alone, determine cancellation behavior. | m |
Tx/TxCaptr | Use true for the failed financial completion that must be reversed. Use false with TxSucss=false for cancellation-advice behavior. Although optional in the XSD, the Gateway requires the value. | m |
Tx/TxTp | Transaction type. For the cancellation scenarios covered here, use CRDP or CAFT as applicable. | m |
Tx/SaleRefId | Existing Gateway order ID that can identify the original transaction. | c |
Tx/OrgnlTx | Explicit original-transaction reference. Supply it unless another supported identifier or the current transaction key intentionally identifies the original transaction. | c |
Tx/OrgnlTx/TxId/TxDtTm | Date and time of the original transaction. Mandatory when OrgnlTx is present. | c |
Tx/OrgnlTx/TxId/TxRef | Reference ID of the original transaction. Mandatory when OrgnlTx is present. | c |
Tx/OrgnlTx/POIId/Id | Terminal ID of the original transaction. Required when it differs from the current terminal and recommended for an unambiguous lookup. | c |
Tx/OrgnlTx/POIId/ShrtNm | Original Gateway terminal ID when it differs from the acquirer terminal ID. | o |
Tx/OrgnlTx/RcptTxId | Original recipient transaction ID. | o |
Tx/OrgnlTx/TxTp | Transaction type of the original transaction. Mandatory when OrgnlTx is present. | c |
Tx/TxSucss | Use false for the cancellation and reversal scenarios covered here. | m |
Tx/Rvsl | Use true for automatic reversal. It does not select the failed non-capture cancellation-advice path. | c |
Tx/FailrRsn | Supply at least one recognized reason for automatic reversal so the Gateway retains the actual cause. See Failure reasons. | c |
Tx/RcptTxId | Gateway transaction or order identifier for the current message. It can be used when no complete original key is supplied. | o |
Original-transaction lookup
All executing cancellation and reversal paths must resolve the original transaction.
| Priority | Information | Usage |
|---|---|---|
| 1 | Minimum:Tx/OrgnlTx/TxId/TxRef& Tx/OrgnlTx/TxId/TxDtTm,and Tx/OrgnlTx/POIId/Id (&Tx/OrgnlTx/POIId/ShrtNm if used in original transaction)and Tx/OrgnlTx/TxTp | This is the preferred and least ambiguous original key. |
| 2 | Tx/OrgnlTx/RcptTxId along with Tx/OrgnlTx/TxId/...or Tx/RcptTxIdor Tx/SaleRefId | These values can identify an existing Gateway transaction or order when no complete original key is supplied. |
| 3 | Current Tx/TxId/TxRef, current Tx/TxId/TxDtTm, and the terminal ID | Completion Advice automatic reversal can use this fallback when the current transaction key intentionally matches the original. |
When both an original key and another identifier are present, the complete original key takes precedence.
Amount and processing behavior
| Situation | Expected behavior |
|---|---|
| Original amount is known | Send the original amount and currency. A non-zero amount should match the referenced transaction. |
| Original amount is unknown | Send Tx/TxDtls/TtlAmt=0. The Gateway treats the amount as unspecified and uses the referenced transaction amount for cancellation. For Acceptor Cancellation Request, the planned caaa.006 response behavior returns the amount actually cancelled. |
| Transaction has already settled | Where the applicable configuration permits it, the Gateway can process the requested cancellation as a return. |
Failure reasons
Failure reasons apply to Completion Advice and Cancellation Advice. Cancellation Request does not contain Tx/FailrRsn.
| Code | Meaning | Gateway treatment |
|---|---|---|
CDCL | Card declined | Preserved as a dedicated cancellation reason |
CUCL | Customer cancelled | Preserved as a dedicated cancellation reason |
MALF | Malfunction | Preserved as a dedicated cancellation reason |
PART | Partially completed | Preserved as a dedicated cancellation reason |
TIMO | Timeout | Preserved as a dedicated cancellation reason |
FDCL | Offline decline | Treated as a technical-error cancellation reason |
NDCL | Online decline | Treated as a technical-error cancellation reason |
SFRD | Suspected fraud | Treated as a technical-error cancellation reason |
LATE | Response too late | Treated as a technical-error cancellation reason |
UCMP | Unable to complete | Treated as a technical-error cancellation reason |
USND | Unable to send | Treated as a technical-error cancellation reason |
SECU | Security error | Treated as a technical-error cancellation reason |
Refund
This document describes the business-relevant elements used by the Gateway for linked and naked refunds with these nexo Acquirer v6 messages:
AcceptorAuthorisationRequestV06-caaa.001.001.06, used for an online refundAcceptorAuthorisationResponseV06-caaa.002.001.06, containing the authorisation resultAcceptorCompletionAdviceV06-caaa.003.001.06, used for a successful offline refund adviceAcceptorCompletionAdviceResponseV06-caaa.004.001.06, acknowledging the advice
In Gateway terminology, a return is a linked refund against an existing Sale and a credit is a naked refund without an original transaction reference.
Use these tables together with the nexo Acquirer v6 Message Definition Report and the corresponding XSD.
Presence: m = mandatory, c = conditional, o = optional, - = not used by the Gateway for that message.
Refund scenario selection
| Scenario | Original reference | Gateway processing |
|---|---|---|
| Linked refund (return) | Supply Tx/OrgnlTx or Tx/SaleRefId so the Gateway can resolve an existing Sale. | Creates a full or partial refund linked to the original Sale. |
| Naked refund (credit) | Omit Tx/OrgnlTx and Tx/SaleRefId. | Creates an independent credit without locating an original Sale. |
Both scenarios use Tx/TxCaptr=true and Tx/TxTp=RFND. The presence of a supported original-transaction or order reference selects a linked refund; the absence of all such references selects a naked refund.
If any original or order reference is supplied, the Gateway treats the message as linked. If the referenced transaction cannot be found, the Gateway rejects the message instead of silently processing it as a naked refund.
Message overview
| Message | Purpose | Refund selection |
|---|---|---|
AcceptorAuthorisationRequestV06 (caaa.001.001.06) | Requests online authorisation and immediate capture of a refund. | Use Hdr/MsgFctn=FAUQ, Tx/TxCaptr=true, and Tx/TxTp=RFND. A reference selects a linked refund. |
AcceptorAuthorisationResponseV06 (caaa.002.001.06) | Returns the approved, partially approved, or declined refund result. | The response to FAUQ uses Hdr/MsgFctn=FAUP. |
AcceptorCompletionAdviceV06 (caaa.003.001.06) | Reports a successful offline refund. | Use Hdr/MsgFctn=FCMV, Tx/TxCaptr=true, Tx/TxTp=RFND, and Tx/TxSucss=true. A reference selects a linked refund advice. |
AcceptorCompletionAdviceResponseV06 (caaa.004.001.06) | Acknowledges that the refund advice was accepted and processed. | The response to FCMV uses Hdr/MsgFctn=FCMK. |
Common request and advice elements
The following fields are common to the online refund request and the successful refund completion advice. Message-specific fields are documented later.
| Tag | Description | Authorisation Request | Completion Advice |
|---|---|---|---|
Hdr/PrtcolVrsn | Protocol version. Use 6.0. | m | m |
Hdr/XchgId | Exchange ID assigned by the terminal for this message. | m | m |
Hdr/ReTrnsmssnCntr | Retransmission counter. It is not part of caaa.001; use it in an advice retry when applicable. | - | o |
Hdr/CreDtTm | Date and time when the message was created. Include a timezone. | m | m |
Hdr/InitgPty/Id | Identifies the sending terminal host or application. | m | m |
Hdr/RcptPty/Id | Identifies the configured Gateway recipient. | o | o |
Hdr/RcptPty/RmotAccs/AccsCd | Remote-access or one-time access code when required by the configured payment flow. | o | o |
Hdr/Tracblt/... | Optional traceability information. | o | o |
Envt/Acqrr/Id/Id | Acquirer ID. The Gateway requires the value even though the XSD marks the acquirer block optional. | m | m |
Envt/Acqrr/ParamsVrsn | Version or load timestamp of the parameters used by the terminal. | m | m |
Envt/Mrchnt/Id/Id | Merchant ID. The Gateway requires the value even though the XSD marks the merchant block optional. | m | m |
Envt/Mrchnt/CmonNm | Merchant name supplied by the terminal. | o | o |
Envt/Mrchnt/LctnCtgy | Merchant-location category. NMDC identifies a nomadic merchant and makes the supplied address the service location. | o | o |
Envt/Mrchnt/LctnAndCtct/PstlAdr/... | Merchant or service-location address. If the postal-address block is present, supply its required XSD fields. | o | o |
Envt/Mrchnt/LctnAndCtct/AddtlCtctInf | Additional merchant contact, station, or tenant information. | o | o |
Envt/POI/Id/Id | Terminal ID. | m | m |
Envt/POI/Id/ShrtNm | Gateway terminal ID when it differs from the acquirer terminal ID. | o | o |
Envt/POI/GrpId | Gateway store or POI group ID. | o | o |
Envt/POI/Cpblties | POI capabilities block. The Gateway requires this block. | m | m |
Envt/POI/Cpblties/CardRdngCpblties | Card-reading capabilities supported by the POI. | o | o |
Envt/POI/Cpblties/CrdhldrVrfctnCpblties | Cardholder-verification capabilities supported by the POI. | o | o |
Envt/POI/Cpblties/OnLineCpblties | POI online capability. ONLN means online, OFLN means offline, and an absent or different value permits both. | o | o |
Envt/POI/Cpblties/MsgCpblties/Dstn | Message destination. CRDO requests the electronic-receipt indicator. | o | o |
Envt/POI/Cmpnt/... | Optional terminal serial number, type, provider, device, response-capability, or operating-system information. | o | o |
Envt/Card | Card environment block. It is mandatory in caaa.001 and optional in caaa.003. A naked refund must contain sufficient card or token data for processing. | m | c |
Envt/Card/PrtctdCardData/... | Protected card data. Use this form when card data must be supplied in production. | c | c |
Envt/Card/PlainCardData/... | PAN, expiry date, sequence number, or track data. Use clear card data only in an appropriately secured non-production test. | c | c |
Envt/Card/PmtAcctRef | Payment account reference or supported hosted-data identifier. | o | o |
Envt/Card/IssrBIN | Issuer BIN. | o | o |
Envt/Card/CardCtryCd | Card country code. | o | o |
Envt/Card/CardCcyCd | Card currency code. | o | o |
Envt/Card/CardPdctPrfl | Card product profile used for grouping and reconciliation. | o | o |
Envt/Card/CardBrnd | Card brand. For a linked refund, copy the original brand when available. | o | o |
Envt/Crdhldr/Nm | Cardholder name. | o | o |
Envt/Crdhldr/BllgAdr/... | Billing address used when address-verification data is applicable. | o | o |
Cntxt/PmtCntxt | Payment context block. The Gateway requires this block. | m | m |
Cntxt/PmtCntxt/CardPres | Indicates whether the card was present for the refund. | o | o |
Cntxt/PmtCntxt/CrdhldrPres | Indicates whether the cardholder was present. | o | o |
Cntxt/PmtCntxt/OnLineCntxt | Indicates whether the processing context was online. It is available only in the Completion Advice structure. | - | o |
Cntxt/PmtCntxt/AttndncCntxt | Attendance context. When absent, the Gateway treats the transaction as attended. | o | o |
Cntxt/PmtCntxt/TxChanl | Transaction channel. | o | o |
Cntxt/PmtCntxt/CardDataNtryMd | Card-data entry mode. The Gateway requires this field. | m | m |
Cntxt/PmtCntxt/FllbckInd | Fallback indicator: FFLB, SFLB, or NFLB. | o | o |
Cntxt/PmtCntxt/SpprtdOptn | Supported payment options understood by the terminal. The Gateway consumes this field from the Authorisation Request but not from Completion Advice. | o | - |
Cntxt/SaleCntxt/SaleId | Sale system or workstation ID used for transaction reporting and downstream feeds. | o | o |
Cntxt/SaleCntxt/CshrId | Operator or cashier ID. | o | o |
Cntxt/SaleCntxt/InvcNb | Invoice number used for reporting. | o | o |
Cntxt/SaleCntxt/SpnsrdMrchnt/... | Sponsored merchant information. | o | o |
Tx/MrchntCtgyCd | Merchant category code. | m | m |
Tx/CardPrgrmmPropsd | Card programme proposed by the terminal. | o | o |
Tx/TxId/TxDtTm | Date and time of this refund transaction. Include a timezone. | m | m |
Tx/TxId/TxRef | Terminal-assigned reference of this refund. It must be unique within the applicable terminal and time scope. | m | m |
Tx/InitrTxId | Initiator transaction ID used for correlation. | o | o |
Tx/RcncltnId | Reconciliation ID associated with the refund. | o | o |
Tx/TxDtls/Ccy | Refund currency. For a linked refund, it must match the original transaction currency. | m | m |
Tx/TxDtls/TtlAmt | Amount to refund. Use the requested partial amount or the full remaining refundable amount. | m | m |
Tx/TxDtls/AmtQlfr | Amount qualifier for a supported specialised scenario. Omit for an ordinary refund. | o | o |
Tx/TxDtls/DtldAmt/AmtGoodsAndSvcs | Goods-and-services portion of the refund amount. | o | o |
Tx/TxDtls/AcctTp | Card account type, when selected. | o | o |
Tx/TxDtls/UattnddLvlCtgy | Unattended-level category. | o | o |
Tx/TxDtls/SaleItm | Returned product or basket items. See Refund item details. | o | o |
Tx/TxDtls/ICCRltdData | EMV data, when applicable. | o | o |
Tx/AddtlTxData | Additional transaction data supported for the applicable payment scenario. | o | o |
SctyTrlr/AuthntcdData | Message Authentication Value. Send it when message security or MAC validation is enabled for the connection. | o | o |
Acceptor Authorisation Request for an online refund
AcceptorAuthorisationRequestV06 - caaa.001.001.06
Root path: Document/AccptrAuthstnReq/AuthstnReq
Required refund values
| Tag | Value | Description | Presence |
|---|---|---|---|
Hdr/MsgFctn | FAUQ | Financial authorisation request. | m |
Tx/TxCaptr | true | Requests immediate capture of the refund. | m |
Tx/TxTp | RFND | Refund. The reference fields determine whether it is linked or naked. | m |
Linked refund reference fields
A linked refund must resolve an existing Gateway transaction. The complete original transaction key is the least ambiguous reference.
| Tag | Description | Presence |
|---|---|---|
Tx/OrgnlTx | Original Sale reference. Supply the block for the preferred original-key or recipient-transaction-ID lookup. | c |
Tx/OrgnlTx/TxId/TxDtTm | Date and time of the original Sale. Mandatory when OrgnlTx is present. | c |
Tx/OrgnlTx/TxId/TxRef | Terminal reference of the original Sale. Mandatory when OrgnlTx is present. | c |
Tx/OrgnlTx/POIId/Id | Terminal ID of the original Sale. Required when it differs from the current terminal and recommended for an unambiguous lookup. | c |
Tx/OrgnlTx/POIId/ShrtNm | Original Gateway terminal ID when it differs from the acquirer terminal ID. | o |
Tx/OrgnlTx/RcptTxId | Recipient transaction ID returned for the original Sale. Depending on the configured response convention, this identifies either the Gateway transaction or its order. | o |
Tx/OrgnlTx/TxTp | Original transaction type. It is mandatory within OrgnlTx; use CRDP when the original transaction was a Sale. | c |
Tx/SaleRefId | Existing Gateway order ID. Use this as an alternative when the complete original key is not supplied. | c |
At least one supported reference route must be usable. Merely supplying a partial or unknown reference does not convert the request into a naked refund.
Original-transaction lookup priority
| Priority | Supplied information | Gateway usage |
|---|---|---|
| 1 | Tx/OrgnlTx/TxId/TxRef, Tx/OrgnlTx/TxId/TxDtTm, and the original POIId/ShrtNm or POIId/Id | Preferred original-key lookup. If the original terminal is omitted, the current Gateway terminal is used. |
| 2 | Tx/OrgnlTx/RcptTxId | Uses the recipient identifier returned for the original Sale. Its interpretation follows the terminal's configured recipient-ID convention. |
| 3 | Tx/SaleRefId | Uses the existing Gateway order ID. |
When a complete original key and another identifier are both present, the complete original key takes precedence.
Naked refund fields
| Requirement | Expected value or behavior |
|---|---|
| Original transaction | Omit Tx/OrgnlTx. |
| Existing order reference | Omit Tx/SaleRefId. |
| Card data | Supply sufficient protected card, hosted-data, token, or other supported payment data to identify the refund destination. There is no original Sale from which it can be resolved. |
| Refund amount and currency | Supply the independent credit amount and its currency in Tx/TxDtls. |
| Current transaction key | Use a new, unique Tx/TxId/TxRef and the current Tx/TxId/TxDtTm. Do not reuse a Sale key. |
Naked refunds are subject to the store, brand, processor, and payment-method configuration that permits independent credits.
Acceptor Completion Advice for a successful refund
AcceptorCompletionAdviceV06 - caaa.003.001.06
Root path: Document/AccptrCmpltnAdvc/CmpltnAdvc
Required successful-refund values
| Tag | Value | Description | Presence |
|---|---|---|---|
Hdr/MsgFctn | FCMV | Financial completion advice. | m |
Tx/TxCaptr | true | Indicates financial capture. Although optional in the XSD, the Gateway requires it. | m |
Tx/TxTp | RFND | Refund. | m |
Tx/TxSucss | true | Indicates that the terminal-side refund succeeded. | m |
Tx/Rvsl | false or omit | Indicates that this is a successful refund, not a reversal of a refund. | o |
The same reference rule applies as for the Authorisation Request:
Tx/OrgnlTxorTx/SaleRefIdselects a linked refund advice.- Omitting all original and order references selects a naked refund advice.
- A supplied reference that cannot be resolved causes rejection; it does not fall back to a naked refund.
Failed or reversed refund advice is a cancellation or reversal scenario and is outside the scope of this document.
Authorisation Response
AcceptorAuthorisationResponseV06 - caaa.002.001.06
Root path: Document/AccptrAuthstnRspn/AuthstnRspn
The response to a financial refund request uses Hdr/MsgFctn=FAUP.
| Response tag | Description | Presence |
|---|---|---|
Tx/TxId/TxDtTm | Date and time of the refund request. | m |
Tx/TxId/TxRef | Transaction reference copied from the request. | m |
Tx/RcptTxId | Recipient transaction ID assigned by the Gateway when available. Retain it for later correlation or cancellation. | o |
Tx/SaleRefId | Sale or order reference associated with the refund. | o |
Tx/TxDtls/Ccy | Currency associated with the processed refund. | m |
Tx/TxDtls/TtlAmt | Amount associated with the processed refund. For a partial approval, use the returned amount rather than assuming the full requested amount was approved. | m |
Tx/TxDtls/DtldAmt/... | Returned detailed amount information when available. | o |
Tx/TxDtls/ICCRltdData | EMV response data that the terminal must pass to the card when applicable. | o |
Tx/IntrchngData | Scheme transaction identifier when returned by the processor. | o |
TxRspn/AuthstnRslt/AuthstnNtty/Tp | Identifies whether the authorisation entity was the card issuer or an intermediary. | o |
TxRspn/AuthstnRslt/RspnToAuthstn/Rspn | APPR = approved, PART = partially approved, DECL = declined. | m |
TxRspn/AuthstnRslt/RspnToAuthstn/RspnRsn | Response reason, limited to the nexo field length. | o |
TxRspn/AuthstnRslt/RspnToAuthstn/AddtlRspnInf | Additional processor or Gateway response information. | o |
TxRspn/AuthstnRslt/AuthstnCd | Authorisation code, padded to the required response length when necessary. | o |
TxRspn/AuthstnRslt/CmpltnReqrd | Indicates whether a later completion message is required. Honor the returned value. | m |
TxRspn/TxVrfctnRslt | AVS, card-security-code, manual-verification, or supported payment-specific verification results. | o |
TxRspn/Actn | Terminal action such as display, print, PIN retry, or fall-forward when required. | o |
Envt/Card/MskdPAN | Masked PAN when available. | o |
Envt/Card/CardBrnd | Resolved card brand when available. | o |
Envt/Card/PmtAcctRef | Payment account reference or supported token identifier when requested and available. | o |
DECL is a business authorisation result. A malformed, unsupported, or invalid nexo message can instead produce an Acceptor Rejection and should not be treated as an issuer decline.
Completion Advice Response
AcceptorCompletionAdviceResponseV06 - caaa.004.001.06
Root path: Document/AccptrCmpltnAdvcRspn/CmpltnAdvcRspn
The response to a financial refund advice uses Hdr/MsgFctn=FCMK.
| Response tag | Description | Presence |
|---|---|---|
Tx/TxId/TxDtTm | Date and time of the advised refund. | m |
Tx/TxId/TxRef | Transaction reference copied from the advice. | m |
Tx/RcptTxId | Recipient transaction ID assigned by the Gateway when available. | o |
Tx/SaleRefId | Sale or order reference associated with the refund advice. | o |
Tx/Rspn | APPR when the advice was accepted and processed normally. This acknowledges the advice; it is not a new issuer authorisation decision. | m |
Envt/Card/MskdPAN | Masked PAN when available. | o |
Envt/Card/CardBrnd | Resolved card brand when available. | o |
Envt/Card/PmtAcctRef | Payment account reference when explicitly requested and available. | o |
TMSTrggr | Terminal-management trigger when the Gateway requires the terminal to contact the TMS. | o |
Operational rules
| Rule | Expected behavior |
|---|---|
| Linked versus naked | Any supplied original or order reference selects linked-refund processing. Omit all such references only when an independent naked refund is intended. |
| Original reference | Prefer the complete original transaction key. When the original terminal differs from the current terminal, include its terminal identifier. |
| Reference failure | An unknown or incomplete linked-refund reference is rejected; the Gateway does not downgrade it to a naked refund. |
| Amount | A linked refund can be full or partial and is checked against the original transaction and its remaining refundable amount. A naked refund uses the independently requested credit amount. |
| Currency | A linked refund must use the original transaction currency. |
| Unique transaction key | Use a new Tx/TxId/TxRef with the current timestamp. Reusing a transaction key can invoke duplicate-message handling. |
| Advice retry | Retransmit the same Completion Advice with an incremented Hdr/ReTrnsmssnCntr; do not create a different business transaction for a transport retry. |
| Response handling | Treat APPR, PART, and DECL as distinct outcomes. For PART, use the returned amount and follow the terminal's partial-approval rules. |
| EMV completion | When Tx/TxDtls/ICCRltdData is returned in caaa.002, pass the required issuer response data to the card. |
| Security | Protect card and authentication data and send SctyTrlr when the connection is configured for message authentication. |
Updated about 6 hours ago
Did this page help you?
