This is an old revision of the document!


XML Payment Features

Table of Contents


In this feature you can find many different subfeatures which are used to create and manage the transactions performed by merchants' terminals. They are useful in a scenario where your application needs full control of the payment process.

The following resources are the same for all the requests and responses you find on this page:

Use the Request URL and the Request Body Fields to perform a request for this feature, then prepare your integration to receive the response, as defined by the Response Body Fields.

Payment

This feature allows you to perform payments.

  • Main Request body Tag: <PAYMENT>
  • Main Response body Tag: <PAYMENTRESPONSE>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
ORDERID Y A unique identifier for the order created by the merchant.
Maximun of 24 characters.
TERMINALID Y A Terminal ID provided by Nuvei.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
DATETIME Y Request date and time. Format: DD-MM-YYY:HH:MM:SS:SSS.
TRACKDATA N Track 2 data.
Should be present for a swiped cardholder present (CHP) transaction. If this is present then TERMINALTYPE should be set to 3 and TRANSACTIONTYPE should be set to 0.
CARDNUMBER N Payment card number.
Required if TRACKDATA is not being sent.
If a SECURECARD is used (in CARDTYPE), this field should inform the CARDREFERENCE of the given Secure Card.
GOOGLEPAYLOAD N When using google pay for payments, instead of the TRACKDATA or CARDNUMBER, you pass this field, with the Google Pay user data, received from your request, converted to Hexadecimal.
APPLEPAYLOAD N When using apple pay for payments, instead of the TRACKDATA or CARDNUMBER, you pass this field, with the Apple Pay user data, received from your request, converted to Hexadecimal.
CARDTYPE Y Card Type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
This field can also admit the SECURECARD type, when using a Secure Card to perform the transaction.
CARDEXPIRY N Expiry date of the card.
A 4 digit expiry field (MMYY), required if TRACKDATA is not being sent.
This field should not be informed if the CARDTYPE is SECURECARD.
CARDHOLDERNAME N The name of the card holder, required if TRACKDATA is not being sent and not using a SecureCard. It should be as displayed on the front of the card.
This field should not be informed if the CARDTYPE is SECURECARD.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.
CURRENCY Y Currency of the transaction.
A 3 character code following the ISO 4217 Currency Code.
FOREIGNCURRENCYINFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
See the next section, ND004 - Using eDCC, for more details on this field.
TERMINALTYPE Y The type of terminal:
1 - MOTO (Mail Order/Telephone Order).
2 - eCommerce.
3 - Cardholder Present.
TRANSACTIONTYPE Y Normally:
0 - Cardholder Present (CHP) transaction.
4 - MOTO (Mail Order/Telephone Order).
7 - eCommerce.

Recurring Payment Flagging:
2 - Specify that this transaction is recurring. This must be accompanied by the RECURRINGTXNREF field or have special permission granted by the Gateway. Not all processors support this transaction type and consultation with the integration team should be carried out prior to configuring recurring payment flagging.

For First Data Latvia terminal MOTO transactions:
4 - Telephone Order.
9 - Mail Order.

If sending XID & CAVV from non Nuvei MPI on an eCommerce transaction use:
0 - not applicable.
1 - Single transaction.
2 - Recurring transaction.
3 - Installment payment.
4 - Unknown classification.
5 - Fully authenticated transaction 3D Secure transaction.
6 - The merchant attempted to authenticate the cardholder, but the cardholder cannot or does not paricipate in 3D Secure.
7 - Transaction when payment data was transmitted using SSL encryption, or Channel Encrypted.
8 - Transaction in the clear, or Non Secure.
AUTOREADY N Y or N. If this is set to Y Nuvei will automatically set the transaction to READY in the batch. If set to N then the transaction will go to a PENDING status. If not present the terminal default will be used.
EMAIL N Cardholder's e-mail address.
If populated, the cardholder will receive an email receipt.
This can be overridden by the Terminal Setup settings “Disable Cardholder Receipt”.
CVV N The security code entered by the card holder.
ISSUENO N The issue no. of the card (Solo).
ADDRESS1 N The first address. Required for AVS.
ADDRESS2 N Second line of address. Required for AVS. Same as ADDRESS1.
POSTCODE N Post code for the address. Required for AVS. Required for MaxMind MinFraud fraud scoring complementary service.
BILLTOFIRSTNAME N First name of the “Bill To” part of a sale.
BILLTOLASTNAME N Last name of the “Bill To” part of a sale.
DESCRIPTION N A description of the transaction.
XID N The XID for a 3D Secure transaction.
CAVV N The CAVV for a 3D Secure transaction.
MPIREF N 3D Secure Nuvei Transaction Reference supplied in Nuvei MPI transactions. Take a look at 3D Secure.
MOBILENUMBER N Used for SMS receipts.
International format, numeric only.
DEVICEID N The unique identifier string for a connecting device.
Mandatory for non-server based devices such as handheld devices/cash register etc.
PHONE N Card Holder Phone Number stored against transaction.
International format, numeric only.
CITY N City of the address. Required for MaxMind MinFraud fraud scoring complementary service.
REGION N Region of the address. Required for MaxMind MinFraud fraud scoring complementary service.
COUNTRY N Country code for the address. Following the ISO 3166-1-alpha-2 Country Code. Required for MaxMind MinFraud fraud scoring complementary service.
IPADDRESS N Recommended inclusion. Useful for tracking customers. Functionality will expand in the future. Required for MaxMind MinFraud fraud scoring.
SIGNATURE N Optional field if processing Cardholder Present (CHP) transactions using the TRACKDATA field. For format, visit Special Fields and Parameters.
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. To understand more, visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See ND005 - Level II Data Validation.
LEVEL_3_DATA N Component of the request that can be added in case the Level III Data feature is in use for the Terminal processing the Payment. See ND006 - Level 3 Data Validation.
ENHANCED_DATA_TEMPLATE N Enhanced Data template name to be used when creating the transaction. It fills up any not provided transaction's enhanced data fields.
Note that if you use a template, but inform the data during the request, the gateway is just going to use the template to fill the gaps of whatever you didn't inform in your original request. Also, if you inform at least one item in LEVEL_3_DATA component, no item from the template is going to be applied.
This field should only be used if you desire to use one of your Enhanced Data Templates (see Enhanced Data Templates for more details).
This field is only available for terminals with Transaction Enhanced Data feature enabled.
FRAUDREVIEWSESSIONID N This field should contain the value of THEIR_SESSION_ID parameter that a merchant integration uses to configure its session with Fraud Solution. See the ND003 - Using Fraud Solution, in the next section.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Using Fraud Solution

If a merchant wishes to use Fraud Solution on its website, it must insert the Fraud Solution scripts to its website. These scripts create a profile on Fraud Solution servers and are used to validate the user's device..

<!-- Fraud Solution Profiling Tags -->
<script type="text/javascript" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORD_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"></script>
<noscript>
    <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORG_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"></iframe>
</noscript>


The parameters THEIR_ORG_ID and THEIR_SESSION_ID must be supplied by the merchant.

PARAMETER NAME DESCRIPTION
THEIR_ORG_ID Fraud Solution orgId which is set in their terminal settings on the gateway and/or from their Fraud Solution portal. - Up to 32 Chars.
THEIR_SESSION_ID Session ID used to identify session. This must be generated for every new transaction/sale. Do not use a persistent Session ID. - It can be up to 128 bytes long and must only consist of the following characters - upper and lowercase English letters, digits, underscore or hyphen ([a-z], [A-Z], 0-9, _, -).
PAGEID The pageid is an identifier to be used if you place the tags on multiple pages.


ND004 - Using eDCC

All eDCC enabled XML requests must include the FOREIGNCURRENCYINFORMATION tag and its nested tags.

PARAMETER NAME REQUIRED DESCRIPTION
CARDCURRENCY Y Card's currency code.
CARDAMOUNT Y Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Y Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline transaction if the wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.


ND005 - Level II Data Validation

This field is associated with the Transaction Enhanced Data feature. “Allow Enhancced Data (Level II and Level III)” must be enabled with the “Transaction Data Level” option set as “Level II” on the Processing Terminal “Features” section.

To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER N Text type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale.
TAX_AMOUNT N Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions.
SHIPPING_ADDRESS N A subcomponent with all the data related to the shipping address of a purchase.
FULL_NAME N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS1 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting.
CITY N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
REGION N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
POSTCODE N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
COUNTRY N Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code.


Quick example:

<LEVEL_2_DATA>
    <CUSTOMER_REF_NUMBER>SDGK-JSAAS-0235.00002314</CUSTOMER_REF_NUMBER>
    <TAX_AMOUNT>151.27</TAX_AMOUNT>
    <SHIPPING_ADDRESS>
              <FULL_NAME>JOHN SMITH AND ASSOCIATES<FULL_NAME>
              <ADDRESS1>Unit 001, Street X</ADDRESS1>
              <ADDRESS2>Block "A", Neighborhood "A"</ADDRESS2>
              <CITY>City "Y"</CITY>
              <REGION>Region 1 </REGION>
              <POSTCODE>A00B0001</POSTCODE>
              <COUNTRY>Country "Z"</COUNTRY>
    </SHIPPING_ADDRESS>
</LEVEL_2_DATA>


ND006 - Level 3 Data Validation

This field is associated with the Transaction Enhanced Data feature. “Allow Enhanced Data (Level II and Level III)” must be enabled, with the “Transaction Data Level” option set as “Level III” on the Processing Terminal “Features” section.

To provide a transaction with Level 3, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.

FIELD REQUIRED DESCRIPTION
SUMMARY N Subcomponent of Level 3. Agregates the sum of different values within the transaction.
TOTAL_DISCOUNT_AMOUNT N Subfield of SUMMARY. Represents the freight amount applied to the sale.
Decimal value, allowing max of 13 digits within min value of 0.
TOTAL_DUTY_AMOUNT N Subfield of SUMMARY. Represents duty applied to the sale.
Decimal value, allowing max of 13 digits with min value of 0.
LINE_ITEMS N Subcomponent of Level 3. List of all items in which the sale is broken down.
LINE_ITEM N Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the breaking down of your sale.
COMMODITY_CODE N Subfield of LINE_ITEM. Item's commodity code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend accross diverse product lines. Defined at government or commercail agreements level. Consult your Acquirer for more details.
PRODUCT_CODE N Subfield of LINE_ITEM. This is the merchant's identifier for the product, also known as Universal Product code (UPC).
DESCRIPTION N Subfield of LINE_ITEM. This is the merchant's description for the product.
QUANTITY N Subfield of LINE_ITEM. Quantity of the specific item for the sale.
UNIT_OF_MEASURE N Subfield of LINE_ITEM. Measure unit used for this specific item type to sell it in parts, units or sets.
UNIT_PRICE N Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit, within the sale.
DISCOUNT_RATE N Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes.
TAX_RATE N Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts.
TOTAL_AMOUNT N Subfield of LINE_ITEM. Final item value based on total (quantity x unit price) after discount and tax applied.

Quick Example

<LEVEL_2_DATA>...</LEVEL_2_DATA>
<LEVEL_3_DATA>
     <SUMMARY>
          <TOTAL_DISCOUNT_AMOUNT>61.30</TOTAL_DISCOUNT_AMOUNT>
          <TOTAL_FREIGHT_AMOUNT>3.50</TOTAL_FREIGHT_AMOUNT>
          <TOTAL_DUTY_AMOUNT>11.50</TOTAL_DUTY_AMOUNT>
     </SUMMARY>
     <LINE_ITEMS>
          <!-- As many as necessary -->
          <LINE_ITEM>
               <COMMODITY_CODE>PDX001</COMMODITY_CODE>
               <PRODUCT_CODE>DSV1303.090.00001</PRODUCT_CODE>
               <DESCRIPTION>General services</DESCRIPTION>
               <QUANTITY>10</QUANTITY>
               <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
               <UNIT_PRICE>105.50</UNIT_PRICE>
               <DISCOUNT_RATE>5.00</DISCOUNT_RATE>
               <TAX_RATE>12.50</TAX_RATE>
               <TOTAL_AMOUNT>1127.53</TOTAL_AMOUNT>
          </LINE_ITEM>
          <LINE_ITEM>
               <COMMODITY_CODE>PDX002</COMMODITY_CODE>
               <PRODUCT_CODE>DSV1302.090.00001</PRODUCT_CODE>
               <DESCRIPTION>General services</DESCRIPTION>
               <QUANTITY>2</QUANTITY>
               <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
               <UNIT_PRICE>85.50</UNIT_PRICE>
               <DISCOUNT_RATE>5.00</DISCOUNT_RATE>
               <TAX_RATE>16.00</TAX_RATE>
               <TOTAL_AMOUNT>188.44</TOTAL_AMOUNT>
          </LINE_ITEM>
     </LINE_ITEMS>
</LEVEL_3_DATA>

DON'T FORGET
If you are using LEVEL_3_DATA compononent, also add to your request the LEVEL_2_DATA 2 component to attempt a full qualification for enhanced data.

ND007 - Multi Language Support

In case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.

Examples for a Request

  • Scenario: Simple request, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PAYMENT>
	<ORDERID>115010922465</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10</AMOUNT>
	<CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>0807</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<CURRENCY>EUR</CURRENCY>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
	<DATETIME>12-06-2006:11:47:04:656</DATETIME>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
</PAYMENT>


  • Scenario: Payment using eDCC, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PAYMENT>
	<ORDERID>1150109224656</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10</AMOUNT>
	<DATETIME>12-06-2006:11:47:04:656</DATETIME>
	<CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>0807</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
	<CURRENCY>EUR</CURRENCY>
	<FOREIGNCURRENCYINFORMATION>
		<CARDCURRENCY>GBP</CARDCURRENCY>
		<CARDAMOUNT>6.67</CARDAMOUNT>
		<CONVERSIONRATE>0.667157</CONVERSIONRATE>
	</FOREIGNCURRENCYINFORMATION>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
</PAYMENT>  


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding..
APPROVALCODE A six digit AuthCode.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
BANKRESPONSECODE Only sent on TSYS terminals. The TSYS response code returned in the authorization response.
AUTHORIZEDAMOUNT Only sent for specific acquirers. Partial amount authorized for some transactions.
AVSRESPONSE The result of the AVS check. Check Transaction Responses.
CVVRESPONSE The result of the CVV check. Check Transaction Responses.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
FRAUDREVIEWRESPONSE Component of the response that is going to be added in case the Threat Metrix feature is in use for the Terminal processing the Payment. See ND002 - ThreatMetrix Response for more details.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND003 - Additional Information on Response
CARDREFERENCE This field represents the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
MERCHANTREF This field represents the merchant reference that is going to be considered for the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
DATETIME Response date and time for the transaction, created by the bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.



Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET


ND002 - Fraud Solution Response

In case the request of a transaction required the Fraud Solution verification, and the Terminal allowed, the result is then sent back in the FRAUDREVIEWRESPONSE field with the following subelements:

FIELD NAME DESCRIPTION
FRAUDREVIEWSTATUS Subfield of FRAUDREVIEWRESPONSE. Value can be PASS, REVIEW or REJECT.
FRAUDREVIEWRISKRATING Subfield of FRAUDREVIEWRESPONSE. Value can be HIGH, MEDIUM, LOW, NE UTRAL or TRUST.
FRAUDREVIEWSCORE Subfield of FRAUDREVIEWRESPONSE. Value is a number between -100 (highest risk) and +100 (lowest risk).
FRAUDREVIEWREASONCODE Subfield of FRAUDREVIEWRESPONSE. Value is an empty String, or a list of comma separated reasons of why this transaction is a risk.

The response component FRAUDREVIEWRESPONSE would look like this inside the response body:

<FRAUDREVIEWRESPONSE>
    <FRAUDREVIEWSTATUS>PASS</FRAUDREVIEWSTATUS>
    <FRAUDREVIEWRISKRATING>LOW</FRAUDREVIEWRISKRATING>
    <FRAUDREVIEWSCORE>-10</FRAUDREVIEWSCORE>
    <FRAUDREVIEWREASONCODE>Profiling Blocked,Profiling Incomplete</FRAUDREVIEWREASONCODE>
</FRAUDREVIEWRESPONSE>

If a transaction is returned with “FRAUDREVIEWSTATUS” or “REVIEW”, this transaction can be changed to “APPROVE” or “REJECT”. For that, you have two options: let your users do that on the SelfCare System, using the new report feature or,through integration, they can use the Transaction Status Update feature, present on this page. Attention to those transactions which stay as “REVIEW”: they are not going to be settled until the transaction status is changed to “APPROVE” or “REJECT”. So, take a look at the Transaction Status Updatee or remind your users to review the transactions constantly/regularly.


ND003 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


ND004 - Secure Card Auto Registration

This field is returned when a secure card is created based on the card data passed in the request. This is only going to happen when the settings on Merchant Portfolio and Terminal align to allow the auto creation and storage of Secure Cards, and the request in place sends the details for a Secure Card (no TRACKDATA). If you are curious and want to know more about the settings, visit the | Important Integration Settings page.


ND005 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to the initial simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PAYMENTRESPONSE>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>APPROVAL</RESPONSETEXT>
	<APPROVALCODE>475318</APPROVALCODE>
	<DATETIME>2005-11-14T12:53:18</DATETIME>
	<CVVRESPONSE>M</CVVRESPONSE>
	<HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH>
</PAYMENTRESPONSE> 

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Offline Payment

This feature allows you to perform payments.

  • Main Request body Tag: <OFFLINEPAYMENT>
  • Main Response body Tag: <OFFLINEPAYMENTRESPONSE>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
ORDERID Y A unique identifier for the order created by the merchant.
Maximun of 24 characters.
TERMINALID Y A Terminal ID provided by Nuvei.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
TRACKDATA N Track 2 data.
Should be present for a swiped cardholder present (CHP) transaction. If this is present then TERMINALTYPE should be set to 3 and TRANSACTIONTYPE should be set to 0.
CARDNUMBER N Payment card number.
Required if TRACKDATA is not being sent.
If a SECURECARD is used (in CARDTYPE), this field should inform the CARDREFERENCE of the given Secure Card.
CARDTYPE Y Card Type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
This field can also admit the SECURECARD type, when using a Secure Card to perform the transaction.
CARDEXPIRY N Expiry date of the card.
A 4 digit expiry field (MMYY), required if TRACKDATA is not being sent.
This field should not be informed if the CARDTYPE is SECURECARD.
CARDHOLDERNAME N The name of the card holder, required if TRACKDATA is not being sent and not using a SecureCard. It should be as displayed on the front of the card.
This field should not be informed if the CARDTYPE is SECURECARD.
HASH Y A HASH code formed by part of the request fields. The formation rule is given aat the ND001 - Hash Formation, in the next section.
CURRENCY Y Currency of the transaction.
A 3 character code following the ISO 4217 Currency Code.
FOREIGNCURRENCYINFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
See the next section, ND003 - Using eDCC, for more details on this field.
TERMINALTYPE Y The type of terminal:
1 - MOTO (Mail Order/Telephone Order).
2 - eCommerce.
3 - Cardholder Present.
TRANSACTIONTYPE Y Normally:
0 - Cardholder Present (CHP) transaction.
4 - MOTO (Mail Order/Telephone Order).
7 - eCommerce.

Recurring Payment Flagging:
2 - Specify that this transaction is recurring. This must be accompanied by the RECURRINGTXNREF field or have special permission granted by the Gateway. Not all processors support this transaction type and consultation with the integration team should be carried out prior to configuring recurring payment flagging.

For First Data Latvia terminal MOTO transactions:
4 - Telephone Order.
9 - Mail Order.

If sending XID & CAVV from non Nuvei MPI on an eCommerce transaction use:
0 - not applicable.
1 - Single transaction.
2 - Recurring transaction.
3 - Installment payment.
4 - Unknown classification.
5 - Fully authenticated transaction 3D Secure transaction.
6 - The merchant attempted to authenticate the cardholder, but the cardholder cannot or does not paricipate in 3D Secure.
7 - Transaction when payment data was transmitted using SSL encryption, or Channel Encrypted.
8 - Transaction in the clear, or Non Secure.
AUTOREADY N Y or N. If this is set to Y Nuvei will automatically set the transaction to READY in the batch. If set to N then the transaction will go to a PENDING status. If not present the terminal default will be used.
EMAIL N Cardholder's e-mail address.
If populated, the cardholder will receive an email receipt.
This can be overridden by the Terminal Setup settings “Disable Cardholder Receipt”.
ADDRESS1 N The first address. Required for AVS.
ADDRESS2 N Second line of address. Required for AVS. Same as ADDRESS1.
POSTCODE N Post code for the address. Required for AVS. Required for MaxMind MinFraud fraud scoring complementary service.
BILLTOFIRSTNAME N First name of the “Bill To” part of a sale
BILLTOLASTNAME N Last name of the “Bill To” part of a sale
DESCRIPTION N A description of the transaction.
MOBILENUMBER N Used for SMS receipts.
International format, numeric only.
DEVICEID N The unique identifier string for a connecting device.
Mandatory for non-server based devices such as handheld devices/cash register etc.
PHONE N Card Holder Phone Number stored against transaction.
International format, numeric only.
CITY N City of the address. Required for MaxMind MinFraud fraud scoring complementary service.
REGION N Region of the address. Required for MaxMind MinFraud fraud scoring complementary service.
COUNTRY N Country code for the address. Following the ISO 3166-1-alpha-2 Country Code. Required for MaxMind MinFraud fraud scoring complementary service.
IPADDRESS N Recommended inclusion. Useful for tracking customers. Functionality will expand in the future. Required for MaxMind MinFraud fraud scoring.
SIGNATURE N Optional field if processing Cardholder Present (CHP) transactions using the TRACKDATA field. For format, visit Special Fields and Parameters.
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See ND004 - Level II Data Validation.
LEVEL_3_DATA N Component of the request can be added in case the Level 3 Data feature is in use for the Terminal processing the Payment. See ND005 - Level 3 Data Validation.
ENHANCED_DATA_TEMPLATE N Enhanced Data template name to be used when creating the transaction. It fills up any not provided transaction's enhanced data fields.
Note that if you use a template, but inform the data during the request, the gateway is just going to use the template to fill the gaps of whatever you didn't inform in your original request. Also, if you inform at least one item in LEVEL_3_DATA component, no item from the template is going to be applied.
This field should only be used if you desire to use one of your Enhanced Data Templates (see Enhanced Data Templates for more details.)
This field is only available for terminals with Transaction Enhanced Data feature enabled.
APPROVALCODE Y Approval code provided by the Acquirer for the specific transaction


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Using eDCC

All eDCC enabled XML requests must include the FOREIGNCURRENCYINFORMATION tag and its nested tags.

PARAMETER NAME REQUIRED DESCRIPTION
CARDCURRENCY Y Card's currency code.
CARD AMOUNT Y Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Y Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline transaction if the wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.
ND004 - Level II Data Validation

This field is associated with the Transaction Enhanced Data feature, “Allow Enhanced Data (Level II and Level III)” must be enabled with the “Transaction Data Level” option set as “Level II” on the Processing Terminal “Features” section.

This field is associated with the feature “Level II Data”, and to be used it is necessary to set the “Allow Level II Data” option on the Processing Terminal “Features” section.

To provide a transaction with Level 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER N Text type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale.
TAX_AMOUNT N Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions.
SHIPPING_ADDRESS N A subcomponent with all data related to the shipping address of a purchase.
FULL_NAME N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS1 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting.
CITY N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
REGION N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
POSTCODE N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
COUNTRY N Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code.

Quick example:

<LEVEL_2_DATA>
     <CUSTOMER_REF_NUMBER>SDGK-JSAAS-0235.00002314</CUSTOMER_REF_NUMBER>
     <TAX_AMOUNT>151.27</TAX_AMOUNT>
     <SHIPPING_ADDRESS>
          <FULL_NAME>JOHN SMITH AND ASSOCIATES</FULL_NAME>
          <ADDRESS1>UNIT 001, Street X</ADDRESS1>
          <ADDRESS2>Block "A", Neighborhood "A"</ADDRESS2>
          <CITY>City "Y"</CITY>
          <REGION>Region 1</REGION>
          <POSTCODE>A00B0001</POSTCODE>
          <COUNTRY>Country "Z"</COUNTRY>
     </SHIPPING_ADDRESS>
</LEVEL_2_DATA>


ND005 - Level 3 Data Validation This field is associated with the Transaction Enhanced Data feauture.“Allow Enhanced Data (Level II and Level III)” must be enabled with the “Transaction Data Level” option set as “Level III” on the Processing Terminal “Features” section.

To provide a transaction with LEVEL 3, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.

FIELD REQUIRED DESCRIPTION
SUMMARY N Subcomponent of Level 3. Aggregates the sums of different values within the transaction.
TOTAL_DISCOUNT_AMOUNT N Subfield of SUMMARY. Represents the total value assigned as discount to the sale. That considers the resulting sum from all items' discounts rates (unit price x quantity x discount rate) and any other additional discount applied after that.
Decimal value, allowing max of 13 digits with min value of 0.
TOTAL_FREIGHT_AMOUNT N Subfield of SUMMARY. Represents the freight amount applied to the sale.
Decimal value, allowing max of 13 digits with min value of 0.
TOTAL_DUTY_AMOUNT N Subfield of SUMMARY. Represents duty amount applied to the sale.
Decimal value, allowing max of 13 digits with min value of 0.
LINE_ITEMS N
LINE_ITEM N Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the break down of your sale.
COMMODITY_CODE N Subfield of LINE_ITEM. Item's commodity code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. Defined at government or commercial agreement level. Consult your Acquirer for more details.
PRODUCT_CODE N Subfield of LINE_ITEM. This is the merchant's identifier for the product, also known as Universal Product code (UPC).
DESCRIPTION N Subfield of LINE_ITEM. This is the merchant's description of the product.
QUANTITY N
UNIT_OF_MEASURE N Subfield of LINE_ITEM. Measure unit used for this specific item type to sell it in parts, units or sets.
UNIT_PRICE N Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit within the sale.
DISCOUNT_RATE N Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes.
TAX_RATE N Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts.
TOTAL_AMOUNT N Subfield of LINE_ITEM. Final item value based on total (quantity x unit price), after discount and tax applied.

Quick example:

<LEVEL_2_DATA>...</LEVEL_2_DATA>
<LEVEL_3_DATA>
     <SUMMARY>
          <TOTAL_DISCOUNT_AMOUNT>61.30</TOTAL_DISCOUNT_AMOUNT>
          <TOTAL_FREIGHT_AMOUNT>3.50</TOTAL_FREIGHT_AMOUNT>
          <TOTAL_DUTY_AMOUNT>11.50</TOTAL_DUTY_AMOUNT>
     </SUMMARY>
     <LINE_ITEMS>
          <! -- As many as necessary -->
          <LINE_ITEM>
               <COMMODITY_CODE>PDX001</COMMODITY_CODE>
               <PRODUCT_CODE>DSV1303.090.00001</PRODUCT_CODE>
               <DESCRIPTION>General services</DESCRIPTION>
               <QUANTITY>10</QUANTITY>
               <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
               <UNIT_PRICE>105.50</UNIT_PRICE>
               <DISCOUNT_RATE>5.00</DISCOUNT_RATE>
               <TAX_RATE>12.50</TAX_RATE>
               <TOTAL_AMOUNT>1127.53</TOTAL_AMOUNT>
          </LINE_ITEM>
          <LINE_ITEM>
               <COMMODITYCODE>PDX002</COMMODITY_CODE>
               <PRODUCT_CODE>DSV1302.090.00001</PRODUCT_CODE>
               <DESCRIPTION>General services</DESCRIPTION>
               <QUANTITY>2</QUANTITY>
               <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
               <UNIT_PRICE>85.50</UNIT_PRICE>
               <DISCOUNT_RATE>5.00</DISCOUNT_RATE>
               <TAX_RATE>16.00</TAX_RATE>
               <TOTAL_AMOUNT>188.44</TOTAL_AMOUNT>
          </LINE_ITEM>
     </LINE_ITEMS>
</LEVEL_3_DATA>

DON'T FORGET If you are using LEVEL_3_DATA component, also add yo your request the LEVEL_2_DATA 2 component to attempt a full qualification for enhanced data.


Examples for a Request

  • Scenario: Simple request, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<OFFLINEPAYMENT>
	<ORDERID>115010922465</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10</AMOUNT>
	<CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>0807</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<CURRENCY>EUR</CURRENCY>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<APPROVALCODE>DSIC234Fsdsfc35</APPROVALCODE>
	<DATETIME>12-06-2006:11:47:04:656</DATETIME>
	<HASH>33e51227ab83222cea0cc1f03532149319dae3ab8839ad278a82b16d0d15d49bec9e90df00b6504564e3075cb3d984e21471469315526f376a256c557b175a07</HASH>
</PAYMENT>


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding..
APPROVALCODE A six digit AuthCode.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
BANKRESPONSECODE Only sent on TSYS terminals. The TSYS response code returned in the authorization response.
MASKEDCARDNUMBER Customer's card obfuscated card number.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
CARDREFERENCE This field represents the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND002 - Additional Information on Response
MERCHANTREF This field represents the merchant reference that is going to be considered for the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND003 - Secure Card Auto Registration.
DATETIME Response date and time for the transaction, created by the bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET


ND002 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


ND003 - Secure Card Auto Registration

This field is returned when a secure card is created based on the card data passed in the request. This is only going to happen when the settings on Merchant Portfolio and Terminal align to allow the auto creation and storage of Secure Cards, and the request in place sends the details for a Secure Card (no TRACKDATA). If you are curious and want to know more about the settings, visit the | Important Integration Settings page.


ND004 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to the initial simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<OFFLINEPAYMENTRESPONSE>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>APPROVAL</RESPONSETEXT>
	<MASKEDCARDNUMBER>4111******111111</MASKEDCARDNUMBER>
	<APPROVALCODE>475318</APPROVALCODE>
	<DATETIME>2005-11-14T12:53:18</DATETIME>
	<CVVRESPONSE>M</CVVRESPONSE>
	<HASH>3a540c54da7a6697cc61d3111a7024b8b8ae9a3d862b859c41a252b188d5d73ecfebc429ca809f60130c5e37b47b0d4494ebfb5f34c244f78c62a7d7a5896dd2</HASH>
</OFFLINEPAYMENTRESPONSE> 

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Pre-Authorization

This feature allows you to perform pre-authorization.

Pre-authorization transactions are supported only by certain Acquirers. 3D Secure pre-auth transactions are not supported due to scheme restrictions.

Check the details with our support team!

Remember that this type of transaction needs to be complemented by the Pre-Authorization Completion! That can be done also by another request (following section) or directly at the SelfCare System.

  • Main Request body Tag: <PREAUTH>
  • Main Response body Tag: <PREAUTHRESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
ORDERID Y A unique identifier for the order created by the merchant.
Maximun of 24 characters.
TERMINALID Y A Terminal ID provided by Nuvei.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
CARDNUMBER N Payment card number.
Required if TRACKDATA is not being sent.
If a SECURECARD is used (in CARDTYPE), this field should inform the CARDREFERENCE of the given Secure Card.
CARDTYPE Y Card Type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
This field can also admit the SECURECARD type, when using a Secure Card to perform the transaction.
CARDEXPIRY N Expiry date of the card.
A 4 digit expiry field (MMYY), required if TRACKDATA is not being sent.
This field should not be informed if the CARDTYPE is SECURECARD.
CARDHOLDERNAME N The name of the card holder, required if TRACKDATA is not being sent and not using a SecureCard. It should be as displayed on the front of the card.
This field should not be informed if the CARDTYPE is SECURECARD.
CURRENCY Y Currency of the transaction.
A 3 character code following the ISO 4217 Currency Code.
FOREIGNCURRENCYINFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
See the next section, ND004 - Using eDCC, for more details on this field.
TERMINALTYPE Y The type of terminal:
1 - MOTO (Mail Order/Telephone Order).
2 - eCommerce.
TRANSACTIONTYPE Y Normally:
4 - MOTO (Mail Order/Telephone Order).
7 - eCommerce.

Recurring Payment Flagging:
2 - Specify that this transaction is recurring. This must be accompanied by the RECURRINGTXNREF field or have special permission granted by the Gateway. Not all processors support this transaction type and consultation with the integration team should be carried out prior to configuring recurring payment flagging.

For First Data Latvia terminal MOTO transactions:
4 - Telephone Order.
9 - Mail Order.

If sending XID & CAVV from non Nuvei MPI on an eCommerce transaction use:
0 - not applicable.
1 - Single transaction.
2 - Recurring transaction.
3 - Installment payment.
4 - Unknown classification.
5 - Fully authenticated transaction 3D Secure transaction.
6 - The merchant attempted to authenticate the cardholder, but the cardholder cannot or does not paricipate in 3D Secure.
7 - Transaction when payment data was transmitted using SSL encryption, or Channel Encrypted.
8 - Transaction in the clear, or Non Secure.
EMAIL N Cardholders e-mail address.
If populated, the cardholder will receive an email receipt.
This can be overridden by the Terminal Setup settings “Disable Cardholder Receipt”.
CVV N The security code entered by the card holder.
ISSUENO N The issue no. of the card (Solo).
ADDRESS1 N The first address. Required for AVS.
ADDRESS2 N Second line of address. Required for AVS. Same as ADDRESS1.
POSTCODE N Post code for the address. Required for AVS. Required for MaxMind MinFraud fraud scoring complementary service.
DESCRIPTION N A description of the transaction.
XID N The XID for a 3D Secure transaction.
CAVV N The CAVV for a 3D Secure transaction.
MPIREF N 3D Secure Nuvei Transaction Reference supplied in Nuvei MPI transactions. Take a look at 3D Secure.
CITY N City of the address. Required for MaxMind MinFraud fraud scoring complementary service.
REGION N Region of the address. Required for MaxMind MinFraud fraud scoring complementary service.
COUNTRY N Country code for the address. Following the ISO 3166-1-alpha-2 Country Code . Required for MaxMind MinFraud fraud scoring complementary service.
IPADDRESS N Recommended inclusion. Useful for tracking customers. Functionality will expand in the future. Required for MaxMind MinFraud fraud scoring.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See ND005 - Level II Data Validation.
FRAUDREVIEWSESSIONID N This field should contain the value of THEIR_SESSION_ID parameter that a merchant integration uses to configure its session with ThreatMetrix. See the ND003 - Using ThreatMetrix, in the next section.
CUSTOMFIELD'N' N Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
RECURRINGTXNREF N Should be set to the value of a UNIQREREF returned in a Payment response for a matching card. TRANSACTIONTYPE should be set to '2'.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Using Fraud Solution

If a merchant wishes to use Fraud Solution on its website, it must insert the Fraud Solution scripts to its website. These scripts create a profile on Fraud Solution servers and are used to validate the user's device..

<!-- Fraud Solution Profiling Tags -->
<script type="text/javascript" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORD_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"></script>
<noscript>
    <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/fp/tags.js?org_id=THEIR_ORG_ID&session_id=THEIR_SESSION_ID&pageid=PAGEID"></iframe>
</noscript>


The parameters THEIR_ORG_ID and THEIR_SESSION_ID must be supplied by the merchant.

PARAMETER NAME DESCRIPTION
THEIR_ORG_ID Fraud Solution orgId which is set in their terminal settings on the gateway and/or from their Fraud Solution portal. - Up to 32 Chars.
THEIR_SESSION_ID Session ID used to identify session. This must be generated for every new transaction/sale. Do not use a persistent Session ID. - It can be up to 128 bytes long and must only consist of the following characters - upper and lowercase English letters, digits, underscore or hyphen ([a-z], [A-Z], 0-9, _, -).
PAGEID The pageid is an identifier to be used if you place the tags on multiple pages.


ND004 - Using eDCC

All eDCC enabled XML requests must include the FOREIGNCURRENCYINFORMATION tag and its nested tags.

PARAMETER NAME REQUIRED DESCRIPTION
CARDCURRENCY Y Card's currency code.
CARDAMOUNT Y Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Y Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline the transaction if wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.


ND005 - Level II Data Validation

This field is associated with the feature “Level II Data”, and to be used it is necessary to set the “Allow Level II Data” option on a/the Processing Terminal “Features” section.

To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER N Text type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale.
TAX_AMOUNT N Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions.
SHIPPING_ADDRESS N A subcomponent with all the data related to the shipping address of the purchase.
FULL_NAME N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS1 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting.
CITY N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
REGION N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
POSTCODE N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
COUNTRY N Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code.


Quick Example:

<LEVEL_2_DATA>
      <CUSTOMER_REF_NUMBER>SDGK-JSAAS-O235.00002314</CUSTOMER_REF_NUMBER>
      <TAX_AMOUNT>151.27</TAX_AMOUNT>
      <SHIPPING_ADDRESS>
                <FULL_NAME>JOHN SMITH AND ASSOCIATEDS</FULLNAME>
                <ADDRESS1>Unit 001, Street X</ADDRESS1>
                <ADDRESS2>Block "A", Neighborhood "A"</ADDRESS2>
                <CITY>City "Y"</CITY>
                <REGION>Region 1<REGION>
                <POSTCODE>A00B0001</POSTCODE>
                <COUNTRY>Country "Z"</COUNTRY>
      </SHIPPING_ADDRESS>
</LEVEL_2_DATA>          

ND006 - Level 3 Data Validation

This field is associated with the Transaction Enhanced Data feauture, and to be used it is necessary to have the “Allow Enhanced Data (Level II and Level III)” enabled with the “Transaction Data Level” option set as “Level III” on the Processing Terminal “Features” section.

To provide a transaction with LEVEL 3, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.

FIELD REQUIRED DESCRIPTION
SUMMARY N Subcomponent of Level 3. Aggregates the sums of different values within the transaction.
TOTAL_DISCOUNT_AMOUNT N Subfield of SUMMARY. Represents the total value assigned as discount to the sale. That considers the resulting sum from all items' discount rates (unit price x quantity x discount rate) and any other additional discount applied after that.
Decimal value allowing max of 13 digits with min value of 0.
TOTAL_FREIGHT_AMOUNT N Subfield of SUMMARY. Represents the freight amount applied to the sale.
Decimal value, allowing a max of 13 digits with min value of 0.
TOTAL_DUTY_AMOUNT N Subfield of SUMMARY. Represents the duty amount applied to the sale.
Decimal value, allowing max of 13 digits with min value of 0.
LINE_ITEMS N Subcomponent of Level 3. List of all items in which the sale is broken down.
LINE_ITEM N Subfield of LINE ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the break down of your sale.
COMMODITY_CODE N Subfield of LINE_ITEM. Item's commodity code, defined for trade tarrif. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. Defined at government or commercial agreement levels. Consult your Acquirer fir nire details.
PRODUCT_CODE N Subfield of LINE_ITEM. This is the mercahnt's identifier for their product, also known as Universal Product code (UPC).
DESCRIPTION N Subfield of LINE_ITEM. This is the merchant's description of the product.
QUANTITY N Subfield of LINE_ITEM. Quantity of the specific item for sale.
UNIT_OF_MEASURE N Subfield of LINE_ITEM. Measure unit used for this pecific item type to sell it in parts, units or sets.
UNIT_PRICE N Subfield of LINE_ITEM. Unit price applied to this specific type of item and measure unit within the sale.
DISCOUNT_RATE N Subfiend of LINE_ITEM. A % of discount applied to the total (item quantity x unit price) before taxes.
TAX_RATE N Subfield of LINE_ITEM. A % of tax applied to the total (item quantity x unit price) after discounts.
TOTAL_AMOUNT N Subfield of LINE_ITEM. Final item based on total (quantiy x unit price), after discount and tax applied

Quick example:

<LEVEL_2_DATA>...</LEVEL_2_DATA>
<LEVEL_3_DATA>
     <SUMMARY>
          <TOTAL_DISCOUNT_AMOUNT>61.30</TOTAL_DISCOUNT_AMOUNT>
          <TOTAL_FREIGHT_AMOUNT>3.50</TOTAL_FREIGHT_AMOUNT>
          <TOTAL_DUTY_AMOUNT>11.50</TOTAL_DUTY_AMOUNT>
     </SUMMARY>
     <LINE_ITEMS>
          <! -- As many as necessary -->
          <LINE_ITEM>
               <COMMODITY_CODE>PDX001</COMMODITY_CODE>
               <PRODUCT_CODE>DSV1303.090.00001</PRODUCT_CODE>
               <DESCRIPTION>General services</DESCRIPTION>
               <QUANTITY>10</QUANTITY>
               <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
               <DISCOUNT_RATE>5.00</DISCOUNT_RATE>
               <TAX_RATE>12.50</TAX_RATE>
               <TOTAL_AMOUNT>1127.53</TOTAL_AMOUNT>
          </LINE_ITEM>
          <LINE_ITEM>  
               <COMMODITY_CODE>PDX002</COMMODITY_CODE>
               <PRODUCT_CODE>DSV1302.090.00001</PRODUCT_CODE>
               <DESCRIPTION>General services</DESCRIPTION>
               <QUANTITY>2</QUANTITY>
               <UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
               <DISCOUNT_RATE>5.00</DISCOUNT_RATE>
               <TAX_RATE>16.00</TAX_RATE>
               <TOTAL_AMOUNT>188.44</TOTAL_AMOUNT>
          </LINE_ITEM>
     </LINE_ITEMS>
<LEVEL_3_DATA>         

DON'T FORGET If you are using LEVEL_3_DATA component, also add to your request the LEVEL_2_DATA 2 component to attempt a full qualification for enhanced data.

ND007 - Multi Language Support

In case you desire to inform your customer's email and desire to provide his/her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'

Examples for a Request

  • Scenario: Simple request, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTH>
	<ORDERID>100028374319</ORDERID>
	<TERMINALID>6491999</TERMINALID>
	<AMOUNT>15.62</AMOUNT>
	<DATETIME>18-12-2008:09:24:16:105</DATETIME>
	<CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>1109</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<HASH>9c58e8d7ff9eb98db4ece2af75dec6ae</HASH>
	<CURRENCY>EUR</CURRENCY>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
</PREAUTH>


  • Scenario: Pre-auth using eDCC, only mandatory fields.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTH>
	<ORDERID>100028374319</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>15.62</AMOUNT>
	<DATETIME>18-12-2008:09:24:16:105</DATETIME>
        <CARDNUMBER>4111111111111111</CARDNUMBER>
	<CARDTYPE>VISA</CARDTYPE>
	<CARDEXPIRY>1109</CARDEXPIRY>
	<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	<HASH>9c58e8d7ff9eb98db4ece2af75dec6ae</HASH>
	<CURRENCY>EUR</CURRENCY>
	<FOREIGNCURRENCYINFORMATION>
		<CARDCURRENCY>GBP</CARDCURRENCY>
		<CARDAMOUNT>10.42</CARDAMOUNT>
		<CONVERSIONRATE>0.667157</CONVERSIONRATE>
	</FOREIGNCURRENCYINFORMATION>
	<TERMINALTYPE>1</TERMINALTYPE>
	<TRANSACTIONTYPE>7</TRANSACTIONTYPE>
	<CVV>214</CVV>
</PREAUTH> 


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding. Also used for pre-auth completion, in case the unique ref configuration is enabled.
APPROVALCODE A six digit AuthCode.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
BANKRESPONSECODE Only sent on TSYS terminals. The TSYS response code returned in the authorization response.
AVSRESPONSE The result of the AVS check. Check Transaction Responses.
CVVRESPONSE The result of the CVV check. Check Transaction Responses.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
FRAUDREVIEWRESPONSE Component of the response that is going to be added in case the Fraud Solution feature is in use for the Terminal processing the Payment. See ND002 - Fraud Solution Response for more details.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND003 - Additional Information on Response
CARDREFERENCE This field represents the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
MERCHANTREF This field represents the merchant reference that is going to be considered for the token generated for the Secure Card. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Cards within a Payment. Take a look at ND004 - Secure Card Auto Registration.
DATETIME Response date and time for the transaction, created by the bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.



Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET

ND002 - Fraud Solution Response

In case the request of a transaction required the Fraud Solution verification, and the Terminal allowed, the result is then sent back at the FRAUDREVIEWRESPONSE field with the following subelements:

FIELD NAME DESCRIPTION
FRAUDREVIEWSTATUS Subfield of FRAUDREVIEWRESPONSE. Value can be PASS, REVIEW or REJECT.
FRAUDREVIEWRISKRATING Subfield of FRAUDREVIEWRESPONSE. Value can be HIGH, MEDIUM, LOW, NEUTRAL or TRUST.
FRAUDREVIEWSCORE Subfield of FRAUDREVIEWRESPONSE. Value is a number between -100 (highest risk) and +100 (lowest risk).
FRAUDREVIEWREASONCODE Subfield of FRAUDREVIEWRESPONSE. Value is an empty String, or a list of comma separated reasons of why this transaction is a risk.

The response component FRAUDREVIEWRESPONSE would look like this inside the response body:

<FRAUDREVIEWRESPONSE>
    <FRAUDREVIEWSTATUS>PASS</FRAUDREVIEWSTATUS>
    <FRAUDREVIEWRISKRATING>LOW</FRAUDREVIEWRISKRATING>
    <FRAUDREVIEWSCORE>-10</FRAUDREVIEWSCORE>
    <FRAUDREVIEWREASONCODE>Profiling Blocked,Profiling Incomplete</FRAUDREVIEWREASONCODE>
</FRAUDREVIEWRESPONSE>

If a transaction is returned with “FRAUDREVIEWSTATUS” or “REVIEW”, this transaction can be changed to “APPROVE” or “REJECT”. For that, you have two options: let your users do that on the SelfCare System, using the new report feature or,through integration, they can use the Transaction Status Update feature, present on this page. Attention to those transactions which stay as “REVIEW”: they are not going to be settled until the transaction status is changed to “APPROVE” or “REJECT”. So, take a look at the Transaction Status Updatee or remind your users to review the transactions constantly/regularly.


ND003 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


ND004 - Secure Card Auto Registration

This field is returned when a secure card is created based on the card data passed in the request. This is only going to happen when the settings on Merchant Portfolio and Terminal align to allow the auto creation and storage of Secure Cards, and the request in place sends the details for a Secure Card (no TRACKDATA). If you are curious and want to know more about the settings, visit the | Important Integration Settings page.

ND005 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to the initial simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTHRESPONSE>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<APPROVALCODE>475318</APPROVALCODE>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>APPROVAL</RESPONSETEXT>
	<PROCESSINGTERMINAL>6491002</PROCESSINGTERMINAL>
	<DATETIME>2008-12-18T09:24:17</DATETIME>
	<HASH>afe4c8b57f3ea0dfee7c8f75fae7e90d</HASH>
</PREAUTHRESPONSE>  

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Pre-Auth Completion

This feature allows you to perform a completion of a pre-authorization.

  • Main Request body Tag: <PREAUTHCOMPLETION>
  • Main Response body Tag: <PREAUTHCOMPLETIONRESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
UNIQUEREF Y Refers the UNIQUEREF generate for the original pre-autorization. In case the unique ref configuration is enabled, it's mandatory, otherwise, the system is going to accept the original ORDERID used for the pre-authorization.
TERMINALID Y A Terminal ID provided by Nuvei.
AMOUNT Y The amount of the transaction.
A 2 digit decimal or an Integer value for JPY amounts.
FOREIGNCURRENCYINFORMATION N Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
See the next section, ND003 - Using eDCC, for more details on this field.
DESCRIPTION N A description of the transaction.
CVV N The security code entered by the card holder. It should be available when CVV is enabvled for the terminal and completing out of the 15% margin transaction.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Using eDCC

All eDCC enabled XML requests must include the FOREIGNCURRENCYINFORMATION tag and its nested tags.

PARAMETER NAME REQUIRED DESCRIPTION
CARDCURRENCY Y Card's currency code.
CARDAMOUNT Y Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Y Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline transaction if wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.

Examples for a Request

  • Scenario: Simple request to complete a pre-auth, only mandatory fields.
  • Terminal: 6491002.
  • Unique Ref of the original pre-authorization: JJCVGCTOV3.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTHCOMPLETION>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>12.31</AMOUNT>
	<DATETIME>19-12-2008:14:47:51:307</DATETIME>
	<CVV>785</CVV>
	<HASH>ff2e84856d7debbf07d3dfeffad5898c</HASH>
</PREAUTHCOMPLETION>


  • Scenario: Pre-auth completion using eDCC, only mandatory fields.
  • Terminal: 6491002.
  • Unique Ref of the original pre-authorization: JJCVGCTOV3.
  • Terminal Secret: x4n35c32RT.
  • Important: The foreign currency information in the completion request is useful when completing an “out of 15% tolerance” transaction, because the original pre-auth transaction will be reversed and a new PAYMENT transaction will be authorized instead, and the foreign currency details provided will be used for the new transaction. The original pre-auth exchange rate is used when an eDCC transaction within the 15% tolerance is completed.
<?xml version="1.0" encoding="UTF-8"?>
<PREAUTHCOMPLETION>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<TERMINALID>1001</TERMINALID>
	<AMOUNT>22.38</AMOUNT>
	<FOREIGNCURRENCYINFORMATION>
		<CARDCURRENCY>GBP</CARDCURRENCY>
		<CARDAMOUNT>14.93</CARDAMOUNT>
		<CONVERSIONRATE>0.667157</CONVERSIONRATE>
	</FOREIGNCURRENCYINFORMATION>
	<DATETIME>19-12-2008:14:47:51:307</DATETIME>
	<CVV>785</CVV>
	<HASH>ff2e84856d7debbf07d3dfeffad5898c</HASH>
</PREAUTHCOMPLETION>


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking and remote XML refunding. Also used for pre-auth completion, in case the unique ref configuration is enabled.
APPROVALCODE A six digit AuthCode.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
AVSRESPONSE The result of the AVS check. Check Transaction Responses.
CVVRESPONSE The result of the CVV check. Check Transaction Responses.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with processing terminal ID that the system selected to process the transaction.
DATETIME Response date and time for the transaction, created by the bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Single Currency Terminal, the string to generate the HASH field is going to be formed using:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET

When using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to the initial pre-auth completion request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
 <?xml version="1.0" encoding="UTF-8"?>
<PREAUTHCOMPLETIONRESPONSE>
    <UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
    <RESPONSECODE>A</RESPONSECODE>
    <RESPONSETEXT>APPROVAL</RESPONSETEXT>
    <APPROVALCODE>515658</APPROVALCODE>
    <DATETIME>2008-12-18T14:47:51</DATETIME>
    <HASH>93527dbb00534a4b33546161aefe5222</HASH>
</PREAUTHCOMPLETIONRESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


eDCC Exchange Rate

Direct XML transactions (Payment, Pre-Auth and Pre-Auth Completion) can be DCC (Dynamic Currency Conversion) enabled. This is useful when card and terminal currencies are different. Our Payment Gateway supports Currency Conversion Rate requests. Merchant applications can request Conversion Rate for the card then the cardholder has to decide if he/she would like to use the eDCC service after which the appropriate request to the TPS will be sent. All eDCC enabled XML transaction requests should include the additional FOREIGNCURRENCYINFORMATION tag with all required nested tags.

DCC transactions are allowed for the eDCC-enabled terminals only. DCC support for the terminal can be enabled or disabled by our support team only, and it's not available on multi-currency Terminals.

This feature allows you to obtain eDCC exchange rates for specific terminals, depending on the Terminal's settings.

  • Main Request body Tag: <GETCARDCURRENCYRATE>
  • Main Response body Tag: <CARDCURRENCYRATERESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Nuvei. NB - Please contact Nuvei to be issued with a test terminal ID.
CARDBIN Y BIN. The first 6 digits from the Card Number.
BASEAMOUNT N Transaction amount in the base currency. If sent Nuvei will return the correctly formatted and calculated FOREIGNAMOUNT.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:CARDBIN:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


Examples for a Request

  • Scenario: Simple request.
  • Terminal: 1001.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<GETCARDCURRENCYRATE>
	<TERMINALID>1001</TERMINALID>
	<CARDBIN>411111</CARDBIN>
	<DATETIME>27-06-2007:16:50:02:123</DATETIME>
	<HASH>15f6c0f0b51faff9cbb77220ab8ddfce</HASH>
</GETCARDCURRENCYRATE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
TERMINALCURRENCY Terminal's currency code. ISO 4217 Currency Code.
CARDCURRENCY Card's currency code. ISO 4217 Currency Code.
CONVERSIONRATE Conversion rate. See note 2 below.
EXCHANGERATESOURCENAME Source of rates. Display on decision page.
MARGINPERCENTAGE Margin percentage applied.
COMMISSIONPERCENTAGE Commission percentage applied.
FOREIGNAMOUNT Converted amount.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALCURRENCY:CARDCURRENCY:CONVERSIONRATE[1]:DATETIME:SECRET

  • [1] - CONVERSIONRATE: In this string CONVERSIONRATE must be a decimal value with 6 decimal places separated by dot character (‘.’), example: ‘0.123000’.


ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


ND003 - Response Codes - Errors

Error Code Description
101 Terminal not found.
102 BIN not found.
103 Currencies are not the same.
104 eDCC is not allowed for the terminal.
105 Invalid card currency/Unknown currency.
106 Conversion rate not found.
107 Invalid Request format.
108 Invalid hash in the request.
109 Other error.
110 Internal error.
111 Unsupported card currency.


Examples for the Response

  • Scenario: Response to the simple request.
  • Terminal: 1001.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<CARDCURRENCYRATERESPONSE>
	<TERMINALCURRENCY>EUR</TERMINALCURRENCY>
	<CARDCURRENCY>GBP</CARDCURRENCY>
	<CONVERSIONRATE>0.667157</CONVERSIONRATE>
	<EXCHANGERATESOURCENAME>Imaginary Bank</EXCHANGERATESOURCENAME>
	<MARGINPERCENTAGE>1.50</MARGINPERCENTAGE>
	<COMMISSIONPERCENTAGE>1.00</COMMISSIONPERCENTAGE>
	<FOREIGNAMOUNT>15.98</FOREIGNAMOUNT>
	<DATETIME>27-06-2007:16:50:02:999</DATETIME>
	<HASH>a12a10322f5af4a8a419f7dc1c6dd39f</HASH>
</CARDCURRENCYRATERESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Multi Currency Exchange Rate

Some Acquiring Banks support Multi-currency Terminals. They allow Merchants processing transactions in one of a number of pre-defined currencies for a Terminal. This option allows Merchants to retrieve rates daily when using MCP Terminals, making possible to verify the accurate pricing of the currencies they desire to process transactions on.

This option is only available for TSYS Saratoga terminals, but if have any questions, Nuvei will inform you if your Terminal ID supports multi-currency. Contact our integration team if you have any questions relating to multi-currency terminals.

  • Main Request body Tag: <GETFXCURRENCYRATE>
  • Main Response body Tag: <FXCURRENCYRATERESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by Nuvei. NB - Please contact Nuvei to be issued with a test terminal ID.
FXCURRENCY Y Configured currency (at terminal level) to which you desire to know the current conversion rate.
BASEAMOUNT N Transaction amount in the base currency of your terminal (not related to the FXCURRENCY). If sent, Nuvei will return the correctly formatted and calculated FOREIGNAMOUNT, and only for informational purpose, the terminal base currency.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALID:FXCURRENCY:DATETIME:SECRET


Examples for a Request

  • Scenario: Simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<GETFXCURRENCYRATE>
	<TERMINALID>6491002</TERMINALID>
	<FXCURRENCY>EUR</FXCURRENCY>
	<BASEAMOUNT>12</BASEAMOUNT>
	<DATETIME>12-01-2018:11:47:04:656</DATETIME>
	<HASH>f7690c9ceaab0708415d370c8e28998cd29634985ef0cb036f969186a2c97a7934b8277c7153277180acfb61e78c1f37d70bf53d066362d9ebed8d1fca584575</HASH>
</GETFXCURRENCYRATE>


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

The response body fields will be:

Filter:

FIELD DESCRIPTION
TERMINALCURRENCY Base currency for the terminal.
FXCURRENCY Currency used to recover the conversion rate in relation to the terminal base currency.
CONVERSIONRATE Recovered relation between the (Response) Terminal Currency and the (Requested) Conversion currency.
FOREIGNAMOUNT Multiplication of the (Requested) Base Amount and the (Response) Conversion Rate recovered.
DATETIME Response date and time for the response.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following format:

TERMINALCURRENCY:FXCURRENCY:CONVERSIONRATE:DATETIME:SECRET


ND002 - Converting the Base Amount and Retrieving the

If the BASEAMOUNT is not informed on request, the FOREIGNAMOUNT is not generated, but the CONVERTIONRATE and the TERMINALCURRENCY are.


Examples for the Response

  • Scenario: Response to the initial simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<FXCURRENCYRATERESPONSE>
	<TERMINALCURRENCY>USD</TERMINALCURRENCY>
	<FXCURRENCY>EUR</FXCURRENCY>
	<CONVERSIONRATE>0.889639</CONVERSIONRATE>
	<FOREIGNAMOUNT>10.68</FOREIGNAMOUNT>
	<DATETIME>20-09-2018:07:23:56:416</DATETIME>
	<HASH>ec14da3eddccf97279a32a3e90bff487facaa19c22fc88c6ebd48a2c1cd29473c3c05044732784c295fd8ae49db8f2281bf8d16accbdab880ae94b2232fa259e</HASH>
</FXCURRENCYRATERESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Standard Refund

Standard refunds can be performed on any authorized transactions in the Nuvei system, either in the Open Batch or Closed Batch. By default you can refund any amount up to 100% of the original transaction value. If multiple partial refunds are performed then the sum total of them cannot exceed 100% either. This is to prevent fraud. This 100% value is configurable at a Terminal level and if you wish to alter it please contact ecomsupport@merchant-support.com with a reason why you need it altered.

  • Main Request body Tag: <REFUND>
  • Main Response body Tag: <REFUNDRESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
UNIQUEREF Y Refers the UNIQUEREF generate for the original payment response. In case the unique ref configuration is enabled, it's mandatory, otherwise, the system is going to accept the original ORDERID used for the pre-authorization. Either UNIQUEREF or ORDERID should be used, but never both.
TERMINALID Y A Terminal ID provided by Nuvei.
AMOUNT Y The amount of the transaction. A 2 digit decimal or an integer value for JPY amounts.
OPERATOR Y An identifier for who executed this transaction.
REASON Y The reason for the refund.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Multi Language Support

In Case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.


Examples for a Request

  • Scenario: Simple request, only mandatory data.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<REFUND>
	<UNIQUEREF>Q8F40S2V</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10.00</AMOUNT>
	<DATETIME>20-06-2006:12:28:02:171</DATETIME>
	<HASH>cfa094f53a508d2031c7895f9f766cbb</HASH>
	<OPERATOR>Test Operator</OPERATOR>
	<REASON>Faulty Goods</REASON>
</REFUND>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking this transaction.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
TERMINALID A Terminal ID provided by Nuvei.
AMOUNT The amount of the transaction. A 2 digit decimal or an integer value for JPY amounts.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND003 - Additional Information on Response
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET


ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


Examples for the Response

  • Scenario: .
  • Terminal: .
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<REFUNDRESPONSE>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>SUCCESS</RESPONSETEXT>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10.00</AMOUNT>
	<DATETIME>20-06-2006:12:28:03:875</DATETIME>
	<HASH>6a06aa6f14fe539f4dedd305465811ab</HASH>
</REFUNDRESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Unreferenced Refund

Unreferenced refunds are refunds that do not require a payment transaction to be referenced. They are only available on certain accounts by request to ecomsupport@merchant-support.com and must also be approved by your Acquiring (merchant) bank. As an Unreferenced Refund does not refer to a payment transaction, it's necessary to inform the card on which the refund is going to. In this case, you have two possibilities: inform the card details (use the CARDDETAILS tag) or a valid Secure Card (use the CARDREFERENCE tag).

  • Main Request body Tag: <UNREFERENCEDREFUND>
  • Main Response body Tag: <UNREFERENCEDREFUNDRESPONSE>


Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
ORDERID Y A unique identifier for the order created by the merchant. Maximum of 24 characters.
CURRENCY N Currency of the transaction.
A 3 character code following the ISO 4217 Currency Code.
TERMINALID Y A Terminal ID provided by Worldnet. NB - Please contact Worldnet to be issued with a test terminal ID.
CARDREFERENCE N Secure Card reference generated and returned by the Payment Gateway when created. Either CARDREFERENCE or CARDETAILS should be used on request, never both.
CARDDETAILS N Details of the card to which the refund is going to be done to. Take a look at ND003 - Card Details to see this tag's subelements. Either CARDREFERENCE or CARDETAILS should be used on request, never both.
AMOUNT Y The amount of the transaction. A 2 digit decimal or an Integer value for JPY amounts.
AUTOREADY N Y or N. If this is set to Y, Nuvei will automatically set the transaction to READY in the batch. If set to N then the transaction will go to a PENDING status. If not present, the terminal default will be used.
EMAIL N An email address to send a confirmation email to. Normally this is cardholder email address.
OPERATOR Y An identifier for who executed this transaction.
DESCRIPTION N The description for the refund.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

When using a Secure Card (CARDREFERENCE) and a Single Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

When using a Secure Card (CARDREFERENCE) and a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET

When NOT using a Secure Card and using a Single Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CARDTYPE:CARDNUMBER:CARDEXPIRY:CARDHOLDERNAME:AMOUNT:DATETIME:SECRET

When NOT using a Secure Card and using a Multi Currency Terminal, the string to generate the HASH field is going to formed using:

TERMINALID:ORDERID:CARDTYPE:CARDNUMBER:CARDEXPIRY:CARDHOLDERNAME:CURRENCY:AMOUNT:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Card Details

The CARDDETAILS tag has nested elements to represent the card information, as it follows:

FIELD REQUIRED DESCRIPTION
CARDNUMBER N Payment card number.
CARDTYPE Y Card Type used for the transaction.
For more details on this, visit Special Fields and Parameters - Card Types.
CARDEXPIRY N Expiry date of the card.
A 4 digit expiry field (MMYY).
CARDHOLDERNAME N The name of the card holder.


ND004 - Multi Language Support

In Case you desire to inform your customer's email and desire to provide his/ her receipt in another language, you can use the Accept-Language parameter of the request to set language the customer should receive the receipt in. If the language informed is not supported, the Payment Gateway will use its default language (EN). Possible values are 'fr-FR' or even 'fr,en-US;q=0.9,en;q=0.8,ru;q=0.7,de;q=0.6,ru-RU;q=0.5,de-DE;q=0.4'.


Examples for a Request

  • Scenario: Request to a specific card.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<UNREFERENCEDREFUND>
	<ORDERID>115073134</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<CARDDETAILS>
		<CARDTYPE>VISA</CARDTYPE>
		<CARDNUMBER>4111111111111111</CARDNUMBER>
		<CARDEXPIRY>0807</CARDEXPIRY>
		<CARDHOLDERNAME>Joe Bloggs</CARDHOLDERNAME>
	</CARDDETAILS>
	<AMOUNT>10.00</AMOUNT>
	<EMAIL>cardholder_email@worldnettps.com</EMAIL>
	<DATETIME>20-06-2006:12:28:02:171</DATETIME>
	<HASH>cfa094f53a508d2031c7895f9f766cbb</HASH>
	<OPERATOR>Test Operator</OPERATOR>
</UNREFERENCEDREFUND>


  • Scenario: Request to a valid Secure Card.
  • Terminal: 6491002.
  • Secure Card: 2967534771694736 (CARDREFERENCE).
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<UNREFERENCEDREFUND>
	<ORDERID>115073134</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<CARDREFERENCE>2967534771694736</CARDREFERENCE>
	<AMOUNT>10.00</AMOUNT>
	<EMAIL>cardholder_email@worldnettps.com</EMAIL>
	<DATETIME>20-06-2006:12:28:02:171</DATETIME>
	<HASH>cfa094f53a508d2031c7895f9f766cbb</HASH>
	<OPERATOR>Test Operator</OPERATOR>
</UNREFERENCEDREFUND>


REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
UNIQUEREF Generated reference that should be stored for tracking this transaction.
RESPONSECODE A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT The text of the authorization.
PROCESSINGTERMINAL If the transaction was performed on a “routing terminal” then this is populated with the processing terminal ID that the system selected to process the transaction.
ADDITIONAL_FIELD This field is used to send back data of interest of the merchant received by the gateway during the transaction. See ND003 - Additional Information on Response
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+secret


ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


ND003 - Additional Information on Response

This data is going to be sent back only when the Terminal executing the transaction is configured to do so. This configuration can be activated on the Terminal settings by enabling the “Integration” option “Enable original response in XML”. Currently two possible fields can be returned: ACQUIRER_RESPONSE_CODE and ACQUIRER_RESPONSE_TEXT, containing the original code and text from the acquirer's response to the authorization transaction.


Examples for the Response

  • Scenario: Response to a simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<UNREFERENCEDREFUNDRESPONSE>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>SUCCESS</RESPONSETEXT>
	<UNIQUEREF>G53D0M1S4</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>10.00</AMOUNT>
	<DATETIME>20-06-2006:12:28:03:875</DATETIME>
	<HASH>6a06aa6f14fe539f4dedd305465811ab</HASH>
</UNREFERENCEDREFUNDRESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Transaction Status Update

Transaction updates allow you to update the status of a transaction in the Open Batch. You need to know the existing status of the transactions in order to update it.

  • Main Request body Tag: <TRANSACTIONUPDATE>
  • Main Response body Tag: <TRANSACTION UPDATERRESPONSE>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
UNIQUEREF Y The unique reference for the transaction being updated.
OPERATOR Y An identifier for who executed this update.
FROMSTATUS Y The current status of the transaction. Limited by ND003 - Status Changing Constraints.
TOSTATUS Y The status the transaction is going to assume. Limited by ND003 - Status Changing Constraints.
AUTHCODE N The approval code of the referral. Only required if changing a REFERRAL to PENDING or READY.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:OPERATOR:FROMSTATUS:TOSTATUS:APPROVALCODE:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


ND003 - Status Changing Constraints

Transactions' statuses can be updated as long as the change respect the following constraints:

FROMSTATUS > TOSTATUS READY PENDING DECLINED
READY NO YES NO
PENDING YES NO NO
REFERRAL YES YES NO
REVIEW YES YES YES


Examples for a Request

  • Scenario: Simple request, minimum data.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<TRANSACTIONUPDATE>
	<UNIQUEREF>Q8F40S2V</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<OPERATOR>Test Operator</OPERATOR>
	<FROMSTATUS>PENDING</FROMSTATUS>
	<TOSTATUS>READY</TOSTATUS>
	<DATETIME>20-06-2006:12:28:02:171</DATETIME>
	<HASH>cfa094f53a508d2031c7895f9f766cbb</HASH>
</TRANSACTIONUPDATE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Response Body Fields

Filter:

FIELD DESCRIPTION
RESPONSECODE Updated transaction response code.
RESPONSETEXT Updated transaction response text.
UNIQUEREF The unique reference for the transaction being updated.
TERMINALID A Terminal ID provided by Worldnet. NB - Please contact Worldnet to be issued with a test terminal ID.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:RESPONSECODE:RESPONSETEXT:UNIQUEREF:DATETIME:SECRET


ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to a simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<TRANSACTIONUPDATERESPONSE>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>SUCCESS</RESPONSETEXT>
	<UNIQUEREF>JJCVGCTOV3</UNIQUEREF>
	<TERMINALID>6491002</TERMINALID>
	<DATETIME>20-06-2006:12:28:03:875</DATETIME>
	<HASH>6a06aa6f14fe539f4dedd305465811ab</HASH>
</TRANSACTIONUPDATERESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Transaction Enhanced Data Update

This update feature allows you to add enhanced data to transactions already processed, before they are settled. you need to know the existing transaction before sending your request.

  • Main Request Body Tag: <UPDATE_TRANSACTION_ENHANCED_DATA>
  • Main Response Body Tag: <UPDATE_TRANSACTION_DATA_RESPONSE>

Request Body Fields

FIELD REQUIRED DESCRIPTION
ORDERID Y
UNIQUEREF Y Refers the UNIQUEREF generate for the original payment response.
OPERATOR Y An identifier for who executed this transaction.
LEVEL_2_DATA N Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See ND003 - Level 2 Data Validation.
LEVEL_3_DATA N Component of the request that can be added in case the Level III Data feature is in use for the Terminal processing the Payment. See ND004 - Level 3 Data Validation.
ENHANCED_DATA_TEMPLATE N Enhanced Data template name to be used when creating the transaction. It fills up any not provided transaction's enhanced data field.
Note that if you use a template, but inform the data during the request, the gateway is just going to use the template to fill the gaps of whatever you didn't inform in your original request. Also, if you inform at least one item in LEVEL_3_DATA component, no item from template is going to be applied.
This field should only be used if you desire to use one of your Enhanced Data Templates (see Merchant Enhanced Data Templates for more details).
This field is only available for terminals with Transaction Enhanced Data feature enabled.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:OPERATOR:CUSTOMERREF:TAXAMOUNT:FULLNAME:ADDRESS1:ADDRESS2:CITY:REGION:POSTCODE:COUNTRY:TOTALDISCOUNTAMOUNT:TOTALFREIGHTAMOUNT:TOTALDUTYAMOUNT:COMMODITYCODE[1]:PRODUCTCODE[1]:DESCRIPTION[1]:QUANTITY[1]:UNITOFMEASURE[1]:UNITPRICE[1]:DISCOUNTRATE[1]:TAXRATE[1]:ENHANCEDDATATEMPLATE:DATETIME:SECRET

[1] For each LINEITEM added, it's necessary to add all of its details, then add the details of the next item until the last one.

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

ND003 - Level 2 Data Validation

This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the “Allow Enhanced Data (Level II and Level III)” enabled with the “Transaction Data Level” option set as “Level II” on the Processing Terminal “Features” section.

To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields as described below.

FIELD REQUIRED DESCRIPTION
CUSTOMER_REF_NUMBER N Text type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale.
TAX_AMOUNT N Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions.
SHIPPING_ADDRESS N A subcomponent with all the data related to the shipping address of a purchase.
FULL_NAME N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS1 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters.
ADDRESS2 N Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting.
CITY N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
REGION N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters.
POSTCODE N Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters.
COUNTRY N Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 COuntry Code.

ND004 - Level 3 Data Validation

This field is associated with the Transaction Enhanced Data feautre, and to be used it is necessary to have the “Allow Enhanced Data (Level II and Level III)” enabled with the “Transaction Data Level” option set as “Level III” on the Processing Terminal “Features” section.

To provide a transaction with LEVEL 3, your request needs to add the LEVEL_2_DATA (descriped before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.

FIELD REQUIRED DESCRIPTION
SUMMARY N Subcomponent of Level 3. Aggregates the sum of different values within the transaction.
TOTAL_DISCOUNT_AMOUNT N Subfield of SUMMARY. Represents the total value assigned as discount to the sale. That considers the resulting sum from all items' discount rates (unit price x quantity x discount rate) and any other additional discount applied after that.
Decimal value, allowing max of 13 digits with min value of 0.
TOTAL_FREIGHT_AMOUNT N Subfield of SUMMARY. Represents the freight amount applied to the sale.
Decimal value, allowing max of 13 digits with min value of 0.
TOTAL_DUTY_AMOUNT N Subfield of SUMMARY. Represents the duty amount applied to the sale.
Decimal value, allowing max of 13 digits with min value of 0.
LINE_ITEMS N Subcomponent of Level 3. List of all items in which the sale is broken down.
LINE_ITEM N Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the breakdown of your sale.
COMMODITY_CODE N Subfield of LINE_ITEM. Item's commodity code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. Defined at government or commercial agreements leve. Consult your Acquirer for more details.
PRODUCT_CODE N
DESCRIPTION N Subfield of LINE_ITEM. This merchant's description of the product.
QUANTITY N Subfield of LINE_ITEM. Quantity of the specific item for the sale.
UNIT_OF_MEASURE N Subfield of LINE_ITEM. Measure unit used for this specific item to sell it in parts, units or sets.
UNIT_PRICE N Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit, within the sale.
DISCOUNT RATE N Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes.
TAX_RATE N Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts.
TOTAL_AMOUNT N Subfield of LINE_ITEM. Final item value based on total (quantity x unit price) after discount and tax applied.

Information box

DON'T FORGET
If you are using LEVEL_3_DATA component, also add to your request the LEVEL_2_DATA 2 component to attempt a full qualification for enhanced data.

Examples for a Request

  • Scenario: Simple request, minimum data
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT
<?xml version="1.0" encoding="UTF-8"?>
<UPDATE_TRANSACTION_ENHANCED_DATA>
    <TERMINALID>6491002</TERMINALID>
    <UNIQUEREF>DSF96457</UNIQUEREF>
    <OPERATOR>John Smith</OPERATOR>
    <LEVEL_2_DATA>
        <CUSTOMER_REF_NUMBER>SDGK-JSAAS-0235.00002314</CUSTOMER_REF_NUMBER>
	<TAX_AMOUNT>151.27</TAX_AMOUNT>
	<SHIPPING_ADDRESS>
	    <FULL_NAME>JOHN SMITH AND ASSOCIATES</FULL_NAME>
	    <ADDRESS1>Unit 001, Street X</ADDRESS1>
	    <ADDRESS2>Block "A", Neighborhood "A"</ADDRESS2>
	    <CITY>City "Y"</CITY>
	    <REGION>Region 1</REGION>
	    <POSTCODE>A00B0001</POSTCODE>
	    <COUNTRY>Country "Z"</COUNTRY>
	</SHIPPING_ADDRESS>
    </LEVEL_2_DATA>
    <LEVEL_3_DATA>
	<SUMMARY>
	    <TOTAL_DISCOUNT_AMOUNT>61.30</TOTAL_DISCOUNT_AMOUNT>
	    <TOTAL_FREIGHT_AMOUNT>3.50</TOTAL_FREIGHT_AMOUNT>
	    <TOTAL_DUTY_AMOUNT>11.50</TOTAL_DUTY_AMOUNT>
	</SUMMARY>
	<LINE_ITEMS> 
	    <!-- As many as necessary -->
	    <LINE_ITEM>
	        <COMMODITY_CODE>PDX001</COMMODITY_CODE>
		<PRODUCT_CODE>DSV1303.090.00001</PRODUCT_CODE>
		<DESCRIPTION>General services</DESCRIPTION>
		<QUANTITY>10</QUANTITY>
		<UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
		<UNIT_PRICE>105.50</UNIT_PRICE>
		<DISCOUNT_RATE>5.00</DISCOUNT_RATE>
		<TAX_RATE>12.50</TAX_RATE>
		<TOTAL_AMOUNT>1127.53</TOTAL_AMOUNT>
	    </LINE_ITEM>
	    <LINE_ITEM>
		<COMMODITY_CODE>PDX002</COMMODITY_CODE>
		<PRODUCT_CODE>DSV1302.090.00001</PRODUCT_CODE>
		<DESCRIPTION>General services</DESCRIPTION>
		<QUANTITY>2</QUANTITY>
		<UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
		<UNIT_PRICE>85.50</UNIT_PRICE>
		<DISCOUNT_RATE>5.00</DISCOUNT_RATE>
		<TAX_RATE>16.00</TAX_RATE>
		<TOTAL_AMOUNT>188.44</TOTAL_AMOUNT>
	    </LINE_ITEM>
	</LINE_ITEMS>
    </LEVEL_3_DATA>
    <DATETIME>12-06-2006:11:47:04:656</DATETIME>
    <HASH>3a540c54da7a6697cc61d3111a7024b8b8ae9a3d862b859c41a252b188d5d73ecfebc429ca809f60130c5e37b47b0d4494ebfb5f34c244f78c62a7d7a5896dd2</HASH>
</UPDATE_TRANSACTION_ENHANCED_DATA>

Response Body Fields

FIELD DESCRIPTION
ORDERID Same as sent on request.
UNIQUEREF Same as sent on request.
LEVEL_2_DATA Same fields as request - returns what is currently saved on transaction.
LEVEL_3_DATA Same fields as request - returns what is currently saved on transaction.
DATETIME Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001-Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:CUSTOMERREF:TAXAMOUNT:FULLNAME:ADDRESS1:ADDRESS2:CITY:REGION:POSTCODE:COUNTRY:TOTALDISCOUNTAMOUNT:TOTALFREIGHTAMOUNT:TOTALDUTYAMOUNT:COMMODITYCODE[1]:PRODUCTCODE[1]:DESCRIPTION[1]:QUANTITY[1]:UNITOFMEASURE[1]:UNITPRICE[1]:DISCOUNTRATE[1]:TAXRATE[1]:TOTALAMOUNT[1]:DATETIME:SECRET

[1] For each LINEITEM added, it's necessary to add all of its details, then add the details of the next item until the last one.

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to a simple request.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<TRANSACTIONUPDATERESPONSE>
    <TERMINALID>6491002</TERMINALID>
    <UNIQUEREF>DSF96457</UNIQUEREF>
        <LEVEL_2_DATA>
        <CUSTOMER_REF_NUMBER>SDGK-JSAAS-0235.00002314</CUSTOMER_REF_NUMBER>
	<TAX_AMOUNT>151.27</TAX_AMOUNT>
	<SHIPPING_ADDRESS>
	    <FULL_NAME>JOHN SMITH AND ASSOCIATES</FULL_NAME>
	    <ADDRESS1>Unit 001, Street X</ADDRESS1>
	    <ADDRESS2>Block "A", Neighborhood "A"</ADDRESS2>
	    <CITY>City "Y"</CITY>
	    <REGION>Region 1</REGION>
	    <POSTCODE>A00B0001</POSTCODE>
	    <COUNTRY>Country "Z"</COUNTRY>
	</SHIPPING_ADDRESS>
    </LEVEL_2_DATA>
    <LEVEL_3_DATA>
	<SUMMARY>
	    <TOTAL_DISCOUNT_AMOUNT>61.30</TOTAL_DISCOUNT_AMOUNT>
	    <TOTAL_FREIGHT_AMOUNT>3.50</TOTAL_FREIGHT_AMOUNT>
	    <TOTAL_DUTY_AMOUNT>11.50</TOTAL_DUTY_AMOUNT>
	</SUMMARY>
	<LINE_ITEMS> 
	    <!-- As many as necessary -->
	    <LINE_ITEM>
	        <COMMODITY_CODE>PDX001</COMMODITY_CODE>
		<PRODUCT_CODE>DSV1303.090.00001</PRODUCT_CODE>
		<DESCRIPTION>General services</DESCRIPTION>
		<QUANTITY>10</QUANTITY>
		<UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
		<UNIT_PRICE>105.50</UNIT_PRICE>
		<DISCOUNT_RATE>5.00</DISCOUNT_RATE>
		<TAX_RATE>12.50</TAX_RATE>
		<TOTAL_AMOUNT>1127.53</TOTAL_AMOUNT>
	    </LINE_ITEM>
	    <LINE_ITEM>
		<COMMODITY_CODE>PDX002</COMMODITY_CODE>
		<PRODUCT_CODE>DSV1302.090.00001</PRODUCT_CODE>
		<DESCRIPTION>General services</DESCRIPTION>
		<QUANTITY>2</QUANTITY>
		<UNIT_OF_MEASURE>Hour</UNIT_OF_MEASURE>
		<UNIT_PRICE>85.50</UNIT_PRICE>
		<DISCOUNT_RATE>5.00</DISCOUNT_RATE>
		<TAX_RATE>16.00</TAX_RATE>
		<TOTAL_AMOUNT>188.44</TOTAL_AMOUNT>
	    </LINE_ITEM>
	</LINE_ITEMS>
    </LEVEL_3_DATA>
    <DATETIME>12-06-2006:11:47:04:656</DATETIME>
    <HASH>3a540c54da7a6697cc61d3111a7024b8b8ae9a3d862b859c41a252b188d5d73ecfebc429ca809f60130c5e37b47b0d4494ebfb5f34c244f78c62a7d7a5896dd2</HASH>
</TRANSACTIONUPDATERESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Transaction Retrieving

This feature allows you to retrieve a transaction already processed. You need to know the existing transaction before sending your request.

  • Main Request body Tag: <GET_TRANSACTION_DETAILS>
  • Main Response body Tag: <GET_TRANSACTION_DETAILS_RESPONSE>

Request Body Fields

Filter:

FIELD REQUIRED DESCRIPTION
TERMINALID Y A Terminal ID provided by %CompanyName. NB - Please contact %CompanyName to be issued with a test terminal ID.
UNIQUEREF Y Refers the UNIQUEREF generate for the original transaction response.
DATETIME Y Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH Y A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details About the Request

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:DATETIME:SECRET


ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.


Examples for a Request

  • Scenario: Simple request, minimum data.
  • Terminal: 6491002.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8"?>
<GET_TRANSACTION_DETAILS>
    <TERMINALID>6491002</TERMINALID>
    <UNIQUEREF>GCNQAWUUVZ</UNIQUEREF>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>73e340cfb2b7424252d1ced917e4f74704aaa66a9600039f4800434cefe87d721c342d2b915c6e2aeea88b34e749ba97665f7d9e50b1144ca0f0745361fc4896</HASH>
</GET_TRANSACTION_DETAILS>


Response Body Fields

Filter:

FIELD DESCRIPTION
TERMINALID Terminal to which the transaction was submitted.
UNIQUEREF Transaction's unique referenced. Same as provided at the request.
TRANSACTION_STATUS Current status of the transaction.
TRANSACTION_DATE Date time of the transaction's processing.
OPERATOR An identifier for who executed this transaction.
TRANSACTION_TYPE Indicates if the transaction is a SALE, a REFUND, a PREAUTH or a pre-auth COMPLETION.
CURRENCY Transaction's currency.
AUTHORIZEDAMOUNT Amount authorized for the transaction.
ADDITIONAL_DETAILS Additional details on the transaction, like the result information, custom fields, batch, among other.
BATCH_NUMBER Subfield of ADDITIONAL_DETAILS. Indicates the batch number of the transaction, if not in open batch anymore.
BULK_NUMBER Subfield of ADDITIONAL_DETAILS. Indicates the number of the bulk in which the transaction was send (only if the transaction was part of a bulk).
PROCESSINGTERMINAL Subfield of ADDITIONAL_DETAILS. Indicates the number of the processing terminal of this transaction. Might differ from the TERMINALID if the transaction was submitted to a routing terminal (once the transaction is routed, it goes to a processing terminal).
RESPONSECODE Subfield of ADDITIONAL_DETAILS. A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively).
E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay).
D: (DECLINED).
R: (REFERRED, also considered as PICKUP).
C: (PICKUP, also known as Referral A or Referral B).
For more details, visit at Transaction Responses.
RESPONSETEXT Subfield of ADDITIONAL_DETAILS. The text of the authorization.
APPROVALCODE Subfield of ADDITIONAL_DETAILS. A six digit AuthCode.
FOREIGNCURRENCYINFORMATION Subfield of ADDITIONAL_DETAILS. Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions.
CARDCURRENCY Subfield of FOREIGNCURRENCYINFORMATION. Cardholder card's currency code.
CARDAMOUNT Subfield of FOREIGNCURRENCYINFORMATION. Amount which is supposed to be charged in the home currency.
CONVERSIONRATE Subfield of FOREIGNCURRENCYINFORMATION. Value of the Conversion Rate on original request.
DESCRIPTION Subfield of ADDITIONAL_DETAILS.
TRANSACTION_CUSTOM_FIELDS Subfield of ADDITIONAL_DETAILS. List of TRANSACTION_CUSTOM_FIELD used with the transaction.
NAME Subfield of each TRANSACTION_CUSTOM_FIELD. Name of the custom field used.
VALUE Subfield of each TRANSACTION_CUSTOM_FIELD. Value provided for the custom field used.
DATETIME Response date and time for the transaction, created by the bank. Format: YYYY-MM-DDTHH:MM:SS. Note that this is intentionally in a different format to the request timestamp to highlight the fact that it is a different time.
HASH A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.


Notes and Details on the Response

ND001 - Hash Formation

The general rule to build the HASH field is given on the Special Fields and Parameters page, under the Special Fields and Parameters section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:ORDERID:TRANSACTION_STATUS:TRANSACTION_DATE:OPERATOR:TRANSACTION_TYPE:CURRENCY:AUTHORIZEDAMOUNT:BATCH_NUMBER:BULK_NUMBER:PROCESSINGTERMINAL:RESPONSECODE:RESPONSETEXT:APPROVALCODE:CARDCURRENCY:CARDAMOUNT:CONVERSIONRATE:DESCRIPTION:DATETIME:SECRET


ND002 - Error Handling

If there is an error processing the request, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>


Examples for the Response

  • Scenario: Response to a simple request.
  • Terminal: 3614008.
  • Terminal Secret: x4n35c32RT.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<GET_TRANSACTION_DETAILS_RESPONSE>
    <TERMINALID>3614008</TERMINALID>
    <UNIQUEREF>E4RGZYVCME</UNIQUEREF>
    <TRANSACTION_STATUS>REVIEW</TRANSACTION_STATUS>
    <TRANSACTION_DATE>26-04-2019:17:19:18:000</TRANSACTION_DATE>
    <OPERATOR>CardHolder Payment</OPERATOR>
    <TRANSACTION_TYPE>SALE</TRANSACTION_TYPE>
    <CURRENCY>USD</CURRENCY>
    <AUTHORIZEDAMOUNT>52.03</AUTHORIZEDAMOUNT>
    <ADDITIONAL_DETAILS>
        <RESPONSECODE>A</RESPONSECODE>
        <RESPONSETEXT>APPROVAL</RESPONSETEXT>
        <APPROVALCODE>VVVVWM</APPROVALCODE>
        <TRANSACTION_CUSTOM_FIELDS>
            <TRANSACTION_CUSTOM_FIELD>
                <NAME>Promocode</NAME>
                <VALUE>sevr9w409vw4v59w45v</VALUE>
            </TRANSACTION_CUSTOM_FIELD>
        </TRANSACTION_CUSTOM_FIELDS>
    </ADDITIONAL_DETAILS>
    <DATETIME>30-04-2019:14:34:47:707</DATETIME>
    <HASH>61a587361fa4631a72af9d47395ad0ab81cb6b5928ed8b41ab0860e7cd52c4bc55361f3d3c0b8cf52add999c0c5c07acd6f8f26c0b045d33c0d97489b3f6be9a</HASH>
</GET_TRANSACTION_DETAILS_RESPONSE>

REMEMBER to change the Terminal ID and Terminal Secret for valid values. Consult the Integration Docs for examples or contact our support team.


Not all the transaction will return the same fields. Mostly they are similar, but some of them might have less data than what is described by the response field table.


Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International