References and Identifiers
Merchant References
By using the Gateway's Nexo API you can define custom transaction references for the following transaction types:
- Payment
- Payment with Gratuity
- Recurring Payment
- Refund
Message elements InitiatorTransactionIdentification (Tx/InitrTxId
) and MerchantReferenceData (Tx/MrchntRefData
) may be optionally used by merchants to pass additional references to the Central Acceptance Platform. The table below shows the usage of these two optional fields within different interfaces in Fiserv.
Reference element | Description | Supported format in Fiserv | NEXO Acquirer field | NEXO Retailer field |
---|---|---|---|---|
Merchant Reference 1 | Reference number provided by merchant that will be passed to acquirer, issuer (if supported by scheme) and printed on cardholder receipt. It could be generated by the Merchant POS or manually entered on the POI. | 15 AN | Tx/InitrTxId | StatementReference |
Merchant Reference 2 | Reference number provided by merchant generated by the Merchant POS or manually entered on the POI. Used by merchants for their own internal purposes. The reference will only be available on Fiserv internal systems. Examples: Internal reservation number, booking number/reference | 30 AN | Tx/MrchntRefData | SaleToAcquirerData |
Identifiers
Transaction identifiers
Order ID
The Gateway assigns an order ID to transactions in the response message element Tx/RcptTxId
. The value must be used in related transactions such as incremental authorisations and completions. The request tag Tx/OrgnlTx/RcptTxId
is not supported in Payment messages.
Transaction ID
This element uniquely identifies a transaction. It must be unique for each message pair (request, response). A technical void (or cancel) can use the same transaction ID.
The transaction ID consists of two sub-fields: TxDtTm
and TxRef
.
The TxDtTm
is used as the transaction time. In an online transaction it must be close to the current time, otherwise it is possible that authorization system won't accept the transaction.
In some casesTxRef
is forwarded to the downstreaming system. To avoid problems the following rules should be met:
TxRef
should be a numeric counter with values in [000000, 999999].
If transaction n follows transaction n-1, then TxRef
in n must be greater than the one in n-1.
If transaction n-1 has a TxRef
> 900000, It is possible to use a value less then 100000 for transaction n. This is to allow a restart of the counter, when all values are used.
We don't recommend to increment the counter by 1, but by a higher number (e.g.: 10). The reason for this is the following: It is possible to configure an automattic cut-over in the Gateway for a terminal (or store). In this case the Gateway must send a message to the next system. This message requires also a TxRef
(or more exact a trace number which is derived from TxRef
). The Gateway will use the last value of TxRef
+ 1. If you will send the same TxRef
again, the respective payment request fails (this may depend on the authorisation system used by the Gateway)
If the gateway has used a different System Trace Audit Number (STAN) in the authorization message, then it will indicate this by sending
TxRspn/AuthstnRslt/TMSTrggr
="DIRECT:STAN=..." in AcceptorAuthorisationResponse.To reference the current transaction, the terminal still has to send the TxRef used in the request. It must not used the changed value returned in 'STAN'.
For more details please see 'AcceptorAuthorisationResponseV06' in https://docs.fiserv.dev/public/docs/message-layout
Store, merchant and terminal identifiers
Every request message sent by the POI must include two merchant identifiers: Store ID and Merchant ID. The Store ID is an identifier of the "shop" entity, while the Merchant ID is the Acquirer card brand specific merchant identifier that will be sent in authorization and clearing messages. You will need to include the Store ID in element Envt/POI/GrpId
and the Merchant ID in element Envt/Mrchnt/Id/Id
.
Every terminal gets assigned an Acquirer identifier (referred to as Acquirer terminal ID or Acquirer TID) and a Fiserv identifier (referred to as External TID). This section describes the relation between the two and the way they are reflected in the nexo Acquirer protocol. The term "Acquirer" is used throughout the document with a wider meaning than the industry standard meaning of "Acquiring Bank/Processor". It could also refer to different payment providers including alternative payment method (APM) providers.
There are 2 basic modes of operation for Fiserv integrated devices:
- Acquirer Processor
- Payment Service Provider (PSP)
When we drive a terminal as an acquirer processor, the External TID will also be used as an Acquirer TID, being sent to card schemes and printed on receipts.
When we drive a terminal as a PSP, it typically routes the traffic to one or more Acquirers (or APMs). The merchant and acquirer will identify a terminal by its Acquirer assigned TID, while the External TID will only be known by our systems and not forwarded to card schemes.
Terminal numbering
- In Germany productive TIDs are centrally assigned by the Deutsche Kreditwirtschaft (DK).
For the integration via the Gateway, TIDs have to be in the range 54xxxxxx and
have to be requested from our German business department. - For other countries the format limitation is less strict. In general a limitation to 8 characters/digit should be sufficient
- TIDs (or TID ranges) are usually provided from your Fiserv contact. But on request, we can also use TIDs defined by other parties (e.g. terminal vendors).
Updated 6 days ago