====== XML Payment Features ======

~~TOC~~

\\
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:

^ **TYPE** ^ **URL** ^
| Request URL | https://testpayments.nuvei.com/merchant/xmlpayment |
| XML XSD descriptor | https://testpayments.nuvei.com/merchant/gateway.xsd |

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 ====


<searchtable>
^ **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 Token. |
| 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 **[[developer:api_specification:special_fields_and_parameters#the_card_types|Special Fields and Parameters - Card Types]]**.\\ This field can also admit the SECURECARD type, when using a Secure Token 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 **[[developer:api_specification:xml_3d_secure|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 **[[developer:api_specification:special_fields_and_parameters#the_signature_field_format|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 **[[developer:api_specification:special_fields_and_parameters|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 **[[merchant:existing_merchant:selfcare_system:settings:enhanced_data_templates|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.	|
| CREDENTIALONFILE	|	N	| Component of the request that can be added in case Credential on File feature is in use for the Terminal processing the Payment. See **ND008 - Credential on File**.	|
| BYPASS_SURCHARGE	|	N	| Send a value of 'true' to identify that surcharge has not been applied to this payment. Only applicable if surcharging is enabled for the terminal. |
</searchtable>
\\

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:

<WRAP center box 100%>
TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET
</WRAP>

\\

**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..
\\

<code html>
<!-- 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>
</code>
\\

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 **[[developer:api_specification:xml_payment_features#edcc_exchange_rate| 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:

<code xml>

<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>
</code>

\\ 

**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

<code xml>
<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>

</code>

<WRAP center box info 100%>
**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.
</WRAP>


**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.

<code xml>
<?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>
</code>
\\

  * **Scenario**: Payment using eDCC, only mandatory fields.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.

<code xml>
<?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>  
</code>
\\


<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\


**ND008 - Credential on File**

This feature is currently available to TSYS Saratoga terminals. The COF tags are required for the following usage:
  *   * Processing transaction in clear card but token vaulted externally (outside Nuvei Gateway).

The fields will have the following behavior: Hidden - the gateway accepts the fields, if sent, and add them to the transaction, but does not show it to the customer.

To provide a transaction with COF, your request needs to add the Credential on File component and its fields, as described below.

(new table below note ND008)

^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
| ORIGINALBRANDTXIDENTIFIER  | N | String, max length is 64, Merchant sends the transaction identifier if received from acquirer. |
| STOREDCREDENTIALTXTYPE | N | Possible values: FIRST_TXN_SUBSEQUENT_MERCHANT_INITIATED_TXN or SUBSEQUENT_CARDHOLDER_INITITATED_TXN |
| STOREDCREDENTIALUSE | N | Possible values: UNSCHEDULED, INSTALLMENT or RECURRING. |

\\
Quick example:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<PAYMENT>
<ORDERID>CSV_99769707</ORDERID>
<TERMINALID>2366006</TERMINALID>
<AMOUNT>6.00</AMOUNT>
<DATETIME>11-09-2019:14:02:49:708</DATETIME>
<CARDNUMBER>4444333322221111</CARDNUMBER>
<CARDTYPE>VISA</CARDTYPE>
<CARDEXPIRY>1224</CARDEXPIRY>
<CARDHOLDERNAME>na</CARDHOLDERNAME>
<HASH>f048c44d0340af522d5796110675fb1a</HASH>
<CURRENCY>USD</CURRENCY>
<TERMINALTYPE>1</TERMINALTYPE>
<TRANSACTIONTYPE>1</TRANSACTIONTYPE>
<AUTOREADY>Y</AUTOREADY>
<CVV>123</CVV>
<ADDRESS1>ads</ADDRESS1>
<ADDRESS2>ads2</ADDRESS2>
<POSTCODE>123</POSTCODE>
<CREDENTIALONFILE>
<ORIGINALBRANDTXIDENTIFIER>1234567890</ORIGINALBRANDTXIDENTIFIER>
<STOREDCREDENTIALTXTYPE>SUBSEQUENT_MERCHANT_INITIATED_TXN</STOREDCREDENTIALTXTYPE>
<STOREDCREDENTIALUSE>UNSCHEDULED</STOREDCREDENTIALUSE>
</CREDENTIALONFILE>
</PAYMENT>
</code>
==== Response Body Fields ====

The response body fields will be:

<searchtable>
^ **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 **[[merchant:existing_merchant:other_information:transaction_responses|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 **[[merchant:existing_merchant:other_information:transaction_responses|Transaction Responses]]**. |
| CVVRESPONSE         | The result of the CVV check. Check **[[merchant:existing_merchant:other_information:transaction_responses|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 - 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 Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Token within a Payment. Take a look at **ND004 - Secure Token Auto Registration**. |
| MERCHANTREF | This field represents the merchant reference that is going to be considered for the token generated for the Secure Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at **ND004 - Secure Token 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. |
| BRANDTXIDENTIFIER | The gateway returns the transaction identifier received from Acquirer to the merchant in the response if Credential on File is used. |
</searchtable>
\\
\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET
</WRAP>

\\

**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:

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

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 **[[developer:api_specification:xml_payment_features#transaction_status_update|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 **[[developer:api_specification:xml_payment_features#transaction_status_update|Transaction Status Update]]**e 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 Token Auto Registration**

This field is returned when a secure token 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 Token, and the request in place sends the details for a Secure Token (no TRACKDATA). If you are curious and want to know more about the settings, visit the **[[developer:important_integration_settings|| 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:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>

\\

==== Examples for the Response ====

  * **Scenario**: Response to the initial simple request.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.

<code xml>
<?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> 
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

===== Offline Payment =====

This feature allows you to perform payments.

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

==== Request Body Fields ====

<searchtable>
^ **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 Token. |
| CARDTYPE			|	Y	| Card Type used for the transaction.\\ For more details on this, visit **[[developer:api_specification:special_fields_and_parameters#the_card_types|Special Fields and Parameters - Card Types]]**.\\ This field can also admit the SECURECARD type, when using a Secure Token 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 **[[developer:api_specification:special_fields_and_parameters#the_signature_field_format|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 **[[developer:api_specification:special_fields_and_parameters|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 **[[merchant:existing_merchant:selfcare_system:settings:enhanced_data_templates|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 |
| CREDENTIALONFILE		|	Y	| Component of the request that can be added in case Credential on File feature is in use for the Terminal processing the Payment. See **ND008 - Credential on File**. |

</searchtable>
\\

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:

<WRAP center box 100%>
TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET
</WRAP>

\\

**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 **[[developer:api_specification:xml_payment_features#edcc_exchange_rate| 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:

<code xml>
<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>
</code>

\\

**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  | 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 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  | 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:

<code xml>
<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>

</code>


<WRAP center box info 100%>
**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.
</WRAP>

\\

**ND008 - Credential on File**

This feature is currently available to TSYS Saratoga terminals. The COF tags are required for the following usage:
  *   * Processing transaction in clear card but token vaulted externally (outside Nuvei Gateway).

The fields will have the following behavior: Hidden - the gateway accepts the fields, if sent, and adds them to the transaction, but does not show it for the customer.

(new table below note ND008)

^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
| ORIGNALBRANDIXIDENTIFIER |	N	| String, max length is 64, Merchant sends the transaction identifier if received from acquirer. |
| STOREDCREDENTIALTXTYPE |	N	| Possible values: FIRST_TXN, SUBSEQUENT_MERCHANT_INITIATED_TXN or SUBSEQUENT_CARDHOLDER_INITIATED_TXN |
| STOREDCREDENTIALUSE |	N	| Possible values: UNSCHEDULED, INSTALLMENT or RECURRING |

\\

==== Response Body Fields ====

The response body fields will be:

<searchtable>
^ **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 **[[merchant:existing_merchant:other_information:transaction_responses|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 Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at **ND004 - Secure Token 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 Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at **ND003 - Secure Token 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. |
| BRANDTXIDENTIFIER | The gateway returns the transaction identifier received from Acquirer to the merchant in the response if Credential on File is used. |
</searchtable>
\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET
</WRAP>

\\

**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 Token Auto Registration**

This field is returned when a secure token 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 Tokens, and the request in place sends the details for a Secure Token(no TRACKDATA). If you are curious and want to know more about the settings, visit the **[[developer:important_integration_settings|| 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:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>

\\

==== Examples for the Response ====

  * **Scenario**: Response to the initial simple request.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.

<code xml>
<?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> 
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

===== Pre-Authorization =====

This feature allows you to perform pre-authorization. 

<WRAP center box important 100%>
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!
</WRAP>

<WRAP center box info 100%>
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.
</WRAP>

  * **Main Request body Tag**: <PREAUTH> 
  * **Main Response body Tag**: <PREAUTHRESPONSE> 
 
\\
 
==== Request Body Fields ====

<searchtable>
^ **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 Token. |
| CARDTYPE	|	Y	| Card Type used for the transaction.\\ For more details on this, visit **[[developer:api_specification:special_fields_and_parameters#the_card_types|Special Fields and Parameters - Card Types]]**.\\ This field can also admit the SECURECARD type, when using a Secure Token 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 Secure Token. 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 **[[developer:api_specification:xml_3d_secure|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 **[[developer:api_specification:special_fields_and_parameters|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. |
| CREDENTIALONFILE |  N  | Component of the request that can be added in case Credential on File feature is in use for the terminal processing the payment. See **ND008 - Credential on File**.|
</searchtable>

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:

<WRAP center box 100%>
TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET
</WRAP>

\\

**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..
\\

<code html>
<!-- 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>
</code>
\\

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 **[[developer:api_specification:xml_payment_features#edcc_exchange_rate| 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:

<code xml>
<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>          
</code>

**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:

<code xml>
<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>         
</code>

<WRAP center box info 100%>
**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.
</WRAP>

**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.

<code xml>
<?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>
</code>
\\

  * **Scenario**: Pre-auth using eDCC, only mandatory fields.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.

<code xml>
<?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> 
</code>

\\
**ND008 - Credential on File**

This feature is current available to TSYS Saratoga terminals. The COF tags are required for the following usage:
  *   * Processing transaction in clear card but token vaulted externally (outside Nuvei Gateway)

The fields will have the following behavior: Hidden - the gateway accepts, if sent, and adds them to the transaction, but does not show it for the customer.

To provide a transaction with COF, your request needs to add the Credentials on File component and its fields, as described below.


<searchtable>
^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
| ORIGINALBRANDTXIDENTIFIER | N | String, max length is 64, Merchant send the transaction if received from acquirer.|
| STOREDCREDENTIALTXTYPE | N | Possible values: FIRST_TXN, SUBSEQUENT_MERCHANT_INITIATED_TXN or SUBSEQUENT_CARDHOLDER_INITIATED_TXN |
| STOREDCREDENTIALUSE | N | Possible values: UNSCHEDULED, INSTALLMENT or RECURRING |
</searchtable>
\\

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>
\\
Quick Example:

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<PAYMENT>
<ORDERID>CSV_99769707</ORDERID>
<TERMINALID>2366006</TERMINALID>
<AMOUNT>6.00</AMOUNT>
<DATETIME>11-09-2019:14:02:49:708</DATETIME>
<CARDNUMBER>4444333322221111</CARDNUMBER>
<CARDTYPE>VISA</CARDTYPE>
<CARDEXPIRY>1224</CARDEXPIRY>
<CARDHOLDERNAME>na</CARDHOLDERNAME>
<HASH>f048c44d0340af522d5796110675fb1a</HASH>
<CURRENCY>USD</CURRENCY>
<TERMINALTYPE>1</TERMINALTYPE>
<TRANSACTIONTYPE>1</TRANSACTIONTYPE>
<AUTOREADY>Y</AUTOREADY>
<CVV>123</CVV>
<ADDRESS1>ads</ADDRESS1>
<ADDRESS2>ads2</ADDRESS2>
<POSTCODE>123</POSTCODE>
<CREDENTIALONFILE>
<ORIGINALBRANDTXIDENTIFIER>1234567890</ORIGINALBRANDTXIDENTIFIER>
<STOREDCREDENTIALTXTYPE>SUBSEQUENT_MERCHANT_INITIATED_TXN</STOREDCREDENTIALTXTYPE>
<STOREDCREDENTIALUSE>UNSCHEDULED</STOREDCREDENTIALUSE>
</CREDENTIALONFILE>
</PAYMENT>
</code>
==== Response Body Fields ====

The response body fields will be:

<searchtable>
^ **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 **[[merchant:existing_merchant:other_information:transaction_responses|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 **[[merchant:existing_merchant:other_information:transaction_responses|Transaction Responses]]**. |
| CVVRESPONSE         | The result of the CVV check. Check **[[merchant:existing_merchant:other_information:transaction_responses|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 Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at **ND004 - Secure Token Auto Registration**. |
| MERCHANTREF | This field represents the merchant reference that is going to be considered for the token generated for the Secure Token. It's going to be returned when the Settings related to this payment enable the automatic generation of Secure Tokens within a Payment. Take a look at **ND004 - Secure Token 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. |
| BRANDTXIDENTIFIER | The gateway returns the transaction identifier received from Acquirer to the merchant in the response if Credential on File is used. |
</searchtable>
\\
\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:BANKRESPONSECODE:SECRET
</WRAP>

**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:

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

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 **[[developer:api_specification:xml_payment_features#transaction_status_update|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 **[[developer:api_specification:xml_payment_features#transaction_status_update|Transaction Status Update]]**e 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 Token Auto Registration**

This field is returned when a secure token 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 Tokens, and the request in place sends the details for a Secure Token(no TRACKDATA). If you are curious and want to know more about the settings, visit the **[[developer:important_integration_settings|| 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:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>

\\

==== Examples for the Response ====

  * **Scenario**: Response to the initial simple request.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.

<code xml>
<?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>  
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

===== 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 ====

<searchtable>
^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
| UNIQUEREF |	Y	| Refers the UNIQUEREF generate for the original pre-authorization. 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 enabled 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. |
</searchtable>


==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:AMOUNT:DATETIME:SECRET
</WRAP>

\\

**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 **[[developer:api_specification:xml_payment_features#edcc_exchange_rate| 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.

<code xml>
<?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>
</code>
\\

  * **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.
  
<code xml>
<?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>
</code>
\\

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

==== Response Body Fields ====

<searchtable>
^ **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 **[[merchant:existing_merchant:other_information:transaction_responses|Transaction Responses]]**. |
| RESPONSETEXT       | The text of the authorization. |
| AVSRESPONSE         | The result of the AVS check. Check **[[merchant:existing_merchant:other_information:transaction_responses|Transaction Responses]]**. |
| CVVRESPONSE         | The result of the CVV check. Check **[[merchant:existing_merchant:other_information:transaction_responses|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. |
</searchtable>
\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|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:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
</WRAP>

**ND002 - Error Handling**

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>

\\

==== Examples for the Response ====

  * **Scenario**: Response to the initial pre-auth completion request.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.

<code xml>
 <?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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

===== 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.

<WRAP center box info 100%>
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.
</WRAP>

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 ====

<searchtable>
^ **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. |
</searchtable>

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALID:CARDBIN:DATETIME:SECRET
</WRAP>

\\

**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.
  
<code xml>
<?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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

==== Response Body Fields ====

<searchtable>
^ **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. |
</searchtable>

\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALCURRENCY:CARDCURRENCY:CONVERSIONRATE[1]:DATETIME:SECRET
</WRAP>

  * **[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:

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

\\

**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.
  
<code xml>
<?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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

===== 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 ====

<searchtable>
^ **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. |
</searchtable>

\\

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following format:

<WRAP center box 100%>
TERMINALID:FXCURRENCY:DATETIME:SECRET
</WRAP>
\\

==== Examples for a Request ====

  * **Scenario**: Simple request.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.

<code xml>
<?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>
</code>
\\

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

==== Response Body Fields ====

The response body fields will be:

<searchtable>
^ **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. |
</searchtable>

\\

==== Notes and Details About the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following format:

<WRAP center box 100%>
TERMINALCURRENCY:FXCURRENCY:CONVERSIONRATE:DATETIME:SECRET
</WRAP>
\\

**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.

<code xml>
<?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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

===== 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 ====
  
<searchtable>
^ **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. |
</searchtable>

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:AMOUNT:DATETIME:SECRET
</WRAP>

\\

**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.
  
<code xml>
<?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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

==== Response Body Fields ====

<searchtable>
^ **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 **[[merchant:existing_merchant:other_information:transaction_responses|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. |
</searchtable>

\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
</WRAP>
\\

**ND002 - Error Handling**

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>

**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.
  
<code xml>
<?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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

===== 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 Token (use the **CARDREFERENCE** tag).

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

\\
==== Request Body Fields ====

<searchtable>
^ **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 Token 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. |
| DECLINEDREFUNDUNIQUEREF	|	N	| In the case where the merchant is performing an Unreferenced Refund and linking it to a Declined Online Refund.This tag must be included when the terminal uses UNIQUEREF. The card specified for this Unreferenced Refund must be different than that of the original Declined Refund.	|
| DECLINEDREFUNDORDERID	|	N	| In the case where the merchant is performing an Unreferenced Refund and linking it to a Declined Online Refund. - This tag must be included when the terminal does NOT use UNIQUEREF. - If this tag is provided when a terminal specifically uses UNIQUEREF, an error will be returned. - The card specified for this Unreferenced Refund must be different than that of the original Declined Refund.	|
| 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. |
</searchtable>

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

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

<WRAP center box 100%>
TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:ORDERID:CARDTYPE:CARDNUMBER:CARDEXPIRY:CARDHOLDERNAME:AMOUNT:DATETIME:SECRET
</WRAP>

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

<WRAP center box 100%>
TERMINALID:ORDERID:CARDTYPE:CARDNUMBER:CARDEXPIRY:CARDHOLDERNAME:CURRENCY:AMOUNT:DATETIME:SECRET
</WRAP>

\\

**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 **[[developer:api_specification:special_fields_and_parameters#the_card_types|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.
  
<code xml>
<?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>
</code>
\\

  * **Scenario**: Request to a valid Secure Token.
  * **Terminal**: 6491002.
  * **Secure Token**: 2967534771694736 (CARDREFERENCE).
  * **Terminal Secret**: x4n35c32RT.
  
<code xml>
<?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>
</code>
\\

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

==== Response Body Fields ====

<searchtable>
^ **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 **[[merchant:existing_merchant:other_information:transaction_responses|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. |
</searchtable>

\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALID+UNIQUEREF+AMOUNT+DATETIME+RESPONSECODE+RESPONSETEXT+secret
</WRAP>

\\

**ND002 - Error Handling**

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>

\\

**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.
  
<code xml>
<?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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

===== 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 ====

<searchtable>
^ **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. |
</searchtable>

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:OPERATOR:FROMSTATUS:TOSTATUS:APPROVALCODE:DATETIME:SECRET
</WRAP>

\\

**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.
  
<code xml>
<?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>
</code>

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>

\\

==== Response Body Fields ====

<searchtable>
^ **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. |
</searchtable>
\\

==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALID:RESPONSECODE:RESPONSETEXT:UNIQUEREF:DATETIME:SECRET
</WRAP>
\\

**ND002 - Error Handling**

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>
\\

==== Examples for the Response ====

  * **Scenario**: Response to a simple request.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.
  
<code xml>
<?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>
</code>  

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>
\\

===== 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  | A unique identifier for the order created by the merchant. \\ Maximum of 24 characters.
| 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:existing_merchant:selfcare_system:settings:enhanced_data_templates|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 **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
<WRAP center box 100%>
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
</WRAP>

**[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  | Subfield of LINE_ITEM. This merchant's identifier for the product, also known as Universal Product code (UPC).
| 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
<WRAP center box info 100%>
**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.
</WRAP>



 


==== Examples for a Request ====

  * **Scenario**: Simple request, minimum data
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT

<code xml>
<?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>
</code>


==== 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 **[[developer:api_specification:special_fields_and_parameters|Special 
Fields and Parameters]]** page, under the **
[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For 
this specific feature, you should use the following formats:

<WRAP center box 100%>
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
</WRAP>

**[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:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>
\\

==== Examples for the Response ====

  * **Scenario**: Response to a simple request.
  * **Terminal**: 6491002.
  * **Terminal Secret**: x4n35c32RT.
  
<code xml>
<?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>
</code>  

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>
\\
===== 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 ====

<searchtable>						
^ 	**FIELD**	^	**REQUIRED**	^	**DESCRIPTION**	^
| TERMINALID	|	Y	| A Terminal ID provided by Nuvei. NB - Please contact Nuvei to be issued with a test terminal ID.	|
| UNIQUEREF 	|	Y/N	| Refers the UNIQUEREF generated for the original transaction response. The field is required when ORDERID is omitted from the request. |
| ORDERID 	|	Y/N	| Required with UNIQUEREF is not populated. A search can be made using the ORDERID of the transaction. This requires the target terminal to have the setting 'Force Unique Order ID' 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.	| 
</searchtable>						
\\

==== Notes and Details About the Request ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:


**When using UNIQUEREF**
<WRAP center box 100%>
TERMINALID:UNIQUEREF:DATETIME:SECRET
</WRAP>
**When using ORDERID**
<WRAP center box 100%>
TERMINALID:ORDERID:DATETIME:SECRET
</WRAP>

\\

**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.
  
<code xml>
<?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>
</code>

<code xml>
<?xml version="1.0" encoding="UTF-8"?>
<GET_TRANSACTION_DETAILS>
    <TERMINALID>6491002</TERMINALID>
    <ORDERID>GCNQAWUUVZ</ORDERID>
    <DATETIME>06-03-2018:17:41:08:273</DATETIME>
    <HASH>73e340cfb2b7424252d1ced917e4f74704aaa66a9600039f4800434cefe87d721c342d2b915c6e2aeea88b34e749ba97665f7d9e50b1144ca0f0745361fc4896</HASH>
</GET_TRANSACTION_DETAILS>
</code>
\\
==== Response Body Fields ====

<searchtable>						
^ 	**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 **[[merchant:existing_merchant:other_information:transaction_responses|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. |
</searchtable>	
\\
==== Notes and Details on the Response ====

**ND001 - Hash Formation**

The general rule to build the HASH field is given on the **[[developer:api_specification:special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:api_specification:special_fields_and_parameters#the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:

<WRAP center box 100%>
TERMINALID:UNIQUEREF:TRANSACTION_STATUS:TRANSACTION_DATE:OPERATOR:TRANSACTION_TYPE:CURRENCY:AUTHORIZEDAMOUNT:BATCH_NUMBER:BULK_NUMBER:PROCESSINGTERMINAL:RESPONSECODE:RESPONSETEXT:APPROVALCODE:CARDCURRENCY:CARDAMOUNT:CONVERSIONRATE:DESCRIPTION:DATETIME:SECRET
</WRAP>

\\

**ND002 - Error Handling**

If there is an error processing the request, the error string is returned in an XML message with the simple tags:
<code xml>
<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>
</code>
\\
==== Examples for the Response ====

  * **Scenario**: Response to a simple request.
  * **Terminal**: 3614008.
  * **Terminal Secret**: x4n35c32RT.
  
<code xml>
<?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>
</code>  

<WRAP center important 100%>
**REMEMBER** to change the Terminal ID and Terminal Secret for valid values. Consult the **[[developer:integration_docs|Integration Docs]]** for examples or contact our support team.
</WRAP>
\\

<WRAP center important 100%>
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.
</WRAP>
\\