nexo Sale (Purchase) Message Layouts

This document describes the business-relevant elements used by the Gateway for Sale, also called Purchase, with these nexo Acquirer v6 messages:

AcceptorAuthorisationRequestV06 - caaa.001.001.06, used for an online Sale
AcceptorAuthorisationResponseV06 - caaa.002.001.06, containing the authorisation result
AcceptorCompletionAdviceV06 - caaa.003.001.06, used for an offline Sale advice
AcceptorCompletionAdviceResponseV06 - caaa.004.001.06, acknowledging the advice

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	Sale selection
`AcceptorAuthorisationRequestV06` (`caaa.001.001.06`)	Requests online authorisation and immediate financial capture for a Purchase.	Use `Hdr/MsgFctn=FAUQ`, `Tx/TxCaptr=true`, and `Tx/TxTp=CRDP`.
`AcceptorAuthorisationResponseV06` (`caaa.002.001.06`)	Returns the approved, partially approved, or declined result.	The response to `FAUQ` uses `Hdr/MsgFctn=FAUP`.
`AcceptorCompletionAdviceV06` (`caaa.003.001.06`)	Reports a successful offline Purchase.	Use `Hdr/MsgFctn=FCMV`, `Tx/TxCaptr=true`, `Tx/TxTp=CRDP`, and `Tx/TxSucss=true`.
`AcceptorCompletionAdviceResponseV06` (`caaa.004.001.06`)	Acknowledges that the advice was accepted and processed.	The response to `FCMV` uses `Hdr/MsgFctn=FCMK`.

Sale scenario selection

Scenario	Message	Required transaction values	Gateway processing
Online Sale	`caaa.001`	`TxCaptr=true`, `TxTp=CRDP`	Creates an online Sale and returns the authorisation result in `caaa.002`.
Offline Sale advice	`caaa.003`	`TxCaptr=true`, `TxTp=CRDP`, `TxSucss=true`	Records and submits an offline Sale advice.

Common request and advice elements

The following fields are common to the online Sale request and the Sale completion advice. Message-specific transaction 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. See link	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. See link	o	o
`Envt/Card`	Card environment block. It is mandatory in `caaa.001` and optional in `caaa.003`. An offline Sale advice should copy the card information needed to process the transaction.	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.	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.	o	o
`Cntxt/PmtCntxt/CrdhldrPres`	Indicates whether the cardholder was present.	o	o
`Cntxt/PmtCntxt/OnLineCntxt`	Indicates whether the original 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 the current transaction. Include a timezone.	m	m
`Tx/TxId/TxRef`	Terminal-assigned reference of the current transaction. 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 transaction.	o	o
`Tx/TxDtls/Ccy`	Transaction currency.	m	m
`Tx/TxDtls/TtlAmt`	Total Purchase amount.	m	m
`Tx/TxDtls/AmtQlfr`	Amount qualifier for a scenario such as an incremental or decremental amount. Omit for an ordinary Sale.	o	o
`Tx/TxDtls/DtldAmt/AmtGoodsAndSvcs`	Goods-and-services portion of the total amount.	o	o
`Tx/TxDtls/DtldAmt/CshBck`	Cashback amount when cashback is requested and supported.	o	o
`Tx/TxDtls/DtldAmt/Grtty`	Gratuity or tip amount.	o	o
`Tx/TxDtls/AcctTp`	Card account type, when selected.	o	o
`Tx/TxDtls/UattnddLvlCtgy`	Unattended-level category.	o	o
`Tx/TxDtls/SaleItm`	Product or basket items.	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 Sale

AcceptorAuthorisationRequestV06 - caaa.001.001.06

Root path: Document/AccptrAuthstnReq/AuthstnReq

Required Sale values

Tag	Value	Description	Presence
`Hdr/MsgFctn`	`FAUQ`	Financial authorisation request.	m
`Tx/TxCaptr`	`true`	Requests immediate capture.	m
`Tx/TxTp`	`CRDP`	Card payment or Purchase.	m

Additional Authorisation Request elements

Tag	Description	Presence
`Tx/AddtlSvc`	Requests an additional service, for example cashback or another configured payment feature.	o
`Tx/SvcAttr`	Service attribute used for a supported specialised scenario. Omit for an ordinary one-time Sale unless required by that scenario.	o

Cardholder authentication and verification

Online cardholder authentication values belong in the Authorisation Request. A Completion Advice reports verification already performed by the terminal; it does not request a new online PIN or card-security-code check.

Tag	Usage	Authorisation Request	Completion Advice
`Envt/Crdhldr/Authntcn/AuthntcnMtd`	Use `NPIN` for online PIN or `CSCV` for card security code verification.	c	-
`Envt/Crdhldr/Authntcn/CrdhldrOnLinePIN/NcrptdPINBlck`	Encrypted online PIN block.	c	-
`Envt/Crdhldr/Authntcn/CrdhldrOnLinePIN/PINFrmt`	PIN block format.	c	-
`Envt/Crdhldr/Authntcn/PrtctdAuthntcnVal`	Protected card security code. It is consumed only with `AuthntcnMtd=CSCV` and takes precedence over `AuthntcnVal`.	c	-
`Envt/Crdhldr/Authntcn/AuthntcnVal`	Clear card security code value. Use only in an appropriately secured non-production test.	c	-
`Envt/Crdhldr/TxVrfctnRslt`	Verification already performed by the terminal, such as offline PIN.	o	-
`Tx/TxVrfctnRslt`	Verification already performed by the terminal in a Completion Advice.	-	o

Acceptor Completion Advice for a Sale

AcceptorCompletionAdviceV06 - caaa.003.001.06

Root path: Document/AccptrCmpltnAdvc/CmpltnAdvc

Required successful-Sale 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`	`CRDP`	Card payment or Purchase.	m
`Tx/TxSucss`	`true`	Indicates that the terminal-side Purchase succeeded.	m

Additional response information in an advice

Tag	Gateway treatment	Presence
`Tx/AuthstnRslt/RspnToAuthstn/AddtlRspnInf`	Additional response information is retained when supplied.	o

Authorisation Response

AcceptorAuthorisationResponseV06 - caaa.002.001.06

Root path: Document/AccptrAuthstnRspn/AuthstnRspn

The response to a financial authorisation request uses Hdr/MsgFctn=FAUP.

Response tag	Description	Presence
`Tx/TxId/TxDtTm`	Date and time of the request transaction.	m
`Tx/TxId/TxRef`	Transaction reference copied from the request.	m
`Tx/RcptTxId`	Recipient transaction ID assigned by the Gateway when available.	o
`Tx/TxDtls/Ccy`	Currency associated with the processed transaction.	m
`Tx/TxDtls/TtlAmt`	Amount associated with the processed transaction. For a partial approval, use the returned result and amount rather than assuming the full requested amount was approved.	m
`Tx/TxDtls/DtldAmt/...`	Returned goods-and-services, cashback, and gratuity amounts 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.	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 completion advice uses Hdr/MsgFctn=FCMK.

Response tag	Description	Presence
`Tx/TxId/TxDtTm`	Date and time of the advised transaction.	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 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
Unique transaction key	Use a unique `Tx/TxId/TxRef` with the correct terminal ID and 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.