====== Special Fields and Parameters ====== ~~TOC~~ \\ During the use of the features, a few fields have special considerations to be aware of. Here we list those fields, which your application should treat correctly to avoid inconsistencies on requests and responses, guaranteeing the right use of our API. ===== Hash Parameter ===== Every request to and response from Nuvei includes an SHA-512 HASH parameter. This is a security element to ensure that none of the sensitive request or response data has been modified by a “//man-in-the-middle//” attack. This is achieved by including all the sensitive fields into a string, which varies per request type, along with the shared secret, configured per terminal. This string is then used as the basis of an SHA-512 HASH. When explaining the data structure for requests and responses, our **API Specification** is going to present for each feature the formation rule of its Request HASH and its Response HASH. Those rules are going to look like this: TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET \\ The "**:**" (colon) used in the example above is the separator used to concatenate the elements in a string and it **ALWAYS NEEDS TO BE ADDED** to define the separation of two elements. It's important to understand that the separator should only be used to separate two elements with values. * element[1]value * element[1]value:element[2]value * element[1]value:element[2]value:element[n]value For example, if a HASH rule formation defines an element which your request doesn't have, you can't use the separator for that element. Consider a HASH for the following data using the structure presented above: * **TERMINALID**: 678002 * **ORDERID**: 300145858 * **AMOUNT**: 325.56 * **DATETIME**: 15-3-2006:10:43:01:673 * **SECRET**: x4n35c32RT > Consider **sha512** your method to apply the SHA-512 encryption, which receives the string formed with the data elements separated by the colon. String hash = sha512("678002:300145858:325.56:15-3-2006:10:43:01:673:x4n35c32RT"); \\ >The final **hash** string variable would have the value of: 5b39821025c33a3c37560196f36af68668e46e82afc4017434d72e62dbc4c06781afc6364e992d5594656fb185c901ece65adf85e8822832b8985f602e533eba \\ Note that the **sha512** method should always use a character encoding of UTF-8, when appropriate, as should all data sent to the payment gateway. Remember to implement the specific hash rule for each request and response you decide to use from our solutions, exactly as they are described in their features. A few of them may seem similar, but they can differ in small details. **HASH ALGORITHM AND TERMINAL INTEGRATION SETTINGS** The algorithm used to generate the HASH changed to **SHA-512**, but for older integrations, the platform still accepts HASH calculated with the **MD5** algorithm. Additionally, there's a configuration which can be used to force the SHA-512 algorithm for a specific terminal in **Integration > Force SHA-512 Hashing Algorithm**. In case you are still using the MD5 algorithm and the SHA-512 is not forced in your terminal, the fields used for the HASH remain the same and no separator (as **:**) is necessary between them. ===== The Card Types ===== The card types that your account supports are determined by your Acquiring Bank and your Merchant Account. The options our payment gateway provide are: * VISA * VISA DEBIT * ELECTRON * MASTERCARD * DEBIT MASTERCARD * MAESTRO * LASER * AMEX * DINERS * JCB * DISCOVER * CUP SECUREPAY All live accounts will be set up with the correct card types enabled as per the documentation that Nuvei receive from your Acquiring Bank. Please send any amendments to your merchant account to our support team so we may keep your account details up to date. For testing purposes we recommend using the test card numbers in our **[[developer:integration_docs:testing-guide#testing_resources|Testing Guide - Test Resources]]** document. ===== The Currencies Supported ===== The following is a list of currency types supported by Nuvei. Other may be added upon request. ^ **CURRENCY** ^ **CURRENCY CODE** ^ **CODE** ^ | EURO | EUR | 978 | | BRITISH POUNDS | GBP | 826 | | UNITED STATES DOLLARS | USD | 840 | | AUSTRALIAN DOLLARS | AUD | 36 | | CANADIAN DOLLARS | CDN | 124 | | SWISS FRANC | CHF | 756 | | DANISH KRONE | DKK | 208 | | HONG KONG DOLLAR | HDK | 344 | | JAPANESE YEN | JPY | 392 | | NORWEGIAN KRONE | NOK | 578 | | NEW ZEALAND DOLLAR | NZD | 554 | | SWEDISH KRONA | SEK | 752 | | SOUTH AFRICAN RAND | ZAR | 710 | | CZECH KORUNA | CZK | 203 | | SINGAPORE DOLLAR | SGD | 702 | | THAI BAHT | THB | 764 | | ICELANDIC KRONA | ISK | 352 | | HUNGARIAN FORINT | HUF | 348 | | ARGENTINE PESO | ARS | 32 | | BAHAMIAN DOLLAR | BSD | 44 | | BAHRAINI DINAR | BHD | 48 | | BARBADOS DOLLAR | BBD | 52 | | BERMUDIAN DOLLAR | BMD | 60 | | CHINESE YUAN | CNY | 156 | | COLOMBIAN PESO | COP | 170 | | INDIAN RUPEE | INR | 365 | | ISRAELI SHEQEL | ILS | 376 | | KENYAN SHILLING | KES | 404 | | SOUTH KOREAN WON | KRW | 410 | | KUWAITI DINAR | KWD | 414 | | LATVIAN LATS | LVL | 428 | | MALAYSIAN RINGGIT | MYR | 458 | | MEXICAN PESO | MXN | 484 | | MOROCCAN DIRHAM | MAD | 504 | | OMANI RIAL | OMR | 512 | | PANAMANIAN BALBOA | PAB | 590 | | QUATARI RIAL | QAR | 634 | | RUSSIAN RUBLE | RUB | 643 | | SAUDI RIYAL | SAR | 682 | | TRINIDAD AND TOBAGO DOLLAR | TTD | 780 | | UAE DIRHAM | AED | 784 | | NEW TAIWAN DOLLAR | TWD | 901 | | VENEZUELAN BOLIVAR | VEF | 937 | | ROMANIAN LEU | RON | 946 | | TURKISH LIRA | TRY | 949 | | UKRAINIAN HRYVNIA | UAH | 980 | | POLISH ZLOTY | PLN | 985 | | BRAZILIAN REAL | BRL | 986 | ===== The Custom Fields ===== The Custom Fields allow you to send data to our systems with transactions in name-value pairs so that it is stored and can be included in reports, receipts and for other uses. There are two different types of custom fields: Explicit and Implicit. * **Explicit Custom Fields**: All the custom fields that are mentioned in this document are explicit custom fields, all custom fields in the XML gateway are also. They must be pre-configured in the SelfCare System (**Settings** -> **Custom Fields**) for the particular Terminal ID that you are sending the transaction through. * **Implicit Custom Fields**: Any other fields that are sent to the Hosted Payment Page are considered to be implicit custom fields. These will be returned in the response to the Receipt Page, but will not be stored, sent to the Background Validation URL or available in any reporting features. Implicit custom fields are not supported by the XML gateway. A Custom Field is set up to be one of three types: * **1**. **Boolean:** Accepted values are “0”, “1”, “true” or “false”. * **2**. **Numeric**: Any numeric only value. * **3**. **String:** Any value containing only alphanumeric characters, spaces or the following characters: '-&*()_+:;@#|.,/ Additionally to that, each Custom Field also defines how it is going to be used: * **1**. **Virtual Terminal**: defines it can be used on virtual terminal. * **2**. **Payment Page**: defines it can be used on payment pages. * **3**. **Bulk Payment**: defines it can be used with bulk payments. * **4**. **Subscription**: defines it can be used with subscriptions. * **5**. **Mandatory**: defines that, wherever is used, is mandatory. * **6**. **Show on Receipt**: defines it should appear on receipts. Each feature is going to give more details about the use of the Custom Fields in their requests and responses, but be aware that the use of a Custom Field is limited by its configuration. The configuration of Custom Fields involve two main steps: one realized at the **Gateway** side and another done at the **Merchant** side. * **1**. **Gateway Side**: The desired Terminal must be enabled with the Custom Fields feature. * **2**. **Merchant Side**: The Merchant needs to configure the Terminal settings on %Selfcare System with the list of Custom Fields which should be available for this Terminal, detailing the interfaces in which they should be used (XML, HPP, other) and the language in which that custom field is available for. In case your application requires to use Custom Fields with Subscriptions, there's still one more configuration step: under the relevant Stored Subscription, the Custom Field needs to be selected. After that, you can use start using the Custom Fields in your integration, but be sure all the Custom Fields you use are still in place and configured as you expect before putting your integration live. To use a custom field with a request, first verify if the request you want to use allows the custom fields. If it allows, all you have to do is to add to the request as many custom field tags as you need, using its original NAME at the NAME tag attribute, inform the value you desire, then send the request. Example: registering a Secure Token with custom fields to inform the client's loyalty system id (custom field ClientLSID) and the current amount of accumulated points (custom field ClientLSCP). ... ... 343f34fsg68laocaw 2650 ... ===== The Dynamic Descriptors ===== Transaction descriptors describe a particular payment transaction in order to help the Card Holder to identify this transaction on his/ her bank statement or online bank interface. It's a good practice which helps Merchants to minimize the risk of chargeback, saving money! Our **Dynamic Descriptor** feature provides this capability to our Merchants. The text that appears on the Card Holders statements will be composed of: * **1**. A **Prefix**, which is a static text value up to 12 characters long that is the same for every transaction followed by; * **2**. The Dynamic Value, which can be, depending on the terminal settings and the transaction's data: sent in by the website with the transaction, as a Custom Field; adopt the default value defined at the terminal's configuration of the Dynamic Descriptor feature, or; the Terminal Name. Not all Acquirer Banks/ Payment Processors allow this feature, so you need to know if your Terminal has the right one configured. \\ This feature works together with the **Custom Field** feature and has basically two main steps: one realized at the **Gateway** side and another done at the **Merchant** side. * **1**. **Gateway Side**: The desired Terminal must be enabled with the Dynamic Descriptor feature and optionally it also can have a Dynamic Descriptor Prefix and a Default Value. * **2**. **Merchant Side**: Optionally, the Merchant can configure the Terminal settings on %Selfcare System pointing out the custom field to be used by each interface (XML, HPP, other) as the value for the Dynamic Descriptor. Once you configured a Terminal with Dynamic Descriptors, different possibilities are going to be available, for example: **Case 01** ^ **PROPERTY** ^ **VALUE** ^ | Terminal Name | "Merchant Example" | | Dynamic Descriptor Prefix | "Order N." | | Dynamic Descriptor Default Value | "Purchase at Merchant Example" | | Interface using the Dynamic Descriptor | Other | | Associated Custom Field to the Dynamic Descriptor | "Order Number" | If a Transaction is sent to the gateway with a custom field order number "1805000453", the Card Holder would see in his/ her bank statement the following additional information for the purchase: "**//Order N * 1234//**". If a Transaction is sent to the gateway with no order number, the Card Holder would see in his/ her bank statement the following additional information for the purchase: "**//Purchase at Merchant Example//**". **Case 02** ^ **PROPERTY** ^ **VALUE** ^ | Terminal Name | "Merchant Example" | | Dynamic Descriptor Prefix | "Order N." | | Dynamic Descriptor Default Value | "" | | Interface using the Dynamic Descriptor | Other | | Associated Custom Field to the Dynamic Descriptor | "Order Number" | If a Transaction is sent to the gateway with a custom field order number "1805000453", the Card Holder would see in his/ her bank statement the following additional information for the purchase: "**//Order N * 1234//**". If a Transaction is sent to the gateway with no order number, the Card Holder would see in his/ her bank statement the following additional information for the purchase: "**//Merchant Example//**". **Case 03** ^ **PROPERTY** ^ **VALUE** ^ | Terminal Name | "Merchant Example" | | Dynamic Descriptor Prefix | "" | | Dynamic Descriptor Default Value | "" | | Interface using the Dynamic Descriptor | Other | | Associated Custom Field to the Dynamic Descriptor | "Order Number" | If a Transaction is sent to the gateway, the Card Holder would see in his/ her bank statement the following additional information for the purchase: "**//Merchant Example//**". ===== The Multi-Currency Terminal IDs ===== Some Acquiring Banks support Multi-currency Terminals. They allow Merchants processing transactions in one of a number of pre-defined currencies for a Terminal. These Terminals have their own terminal ID and may be identified with the letters ‘MC’ after the terminal ID. It's important to understand that, when processing transactions with one of those Terminals using an integration, your solution has to consider that the **Currency Type** must be added to the request HASH calculation and is going to be added to the response HASH calculation. Details on the HASH calculation for requests and responses involving Multi-currency Terminals are provided by each feature when explaining the HASH body field. 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. ===== The Signature Field Format ===== The signature field is used by some of the features' requests, and follows a set of rules to be formed, as such: * **-** The SIGNATURE field is a string of characters. Each set of 4 characters represents a point on a 300 pixel wide x 100 pixel tall canvas. * **-** Each set of 4 characters is comprised of 2 chars to represent the X value (pixel distance right from left side) and 2 chars to represent the Y value (pixel distance from down from top). * **-** Each 2 char value is a base 28 encoded decimal number (similar to hex which is base 16). Possible values for each character are any numerical digit and the letters from “a” to “r” inclusive (“a” = 10, “b”= 11, etc. just like in hex, but up to “r” = 28). For example “**3bac**” can be calculated as: **(3 x 281) + (11 x 280) = 84 + 11 = 95** from the left and **(10 x 281) + (12 x 280) = 280 + 12 = 292** from the top, hence **3bac** is a point at 95x292 pixels from the top left. * **-** To include a space between 2 points (no line drawn on signature canvas) include a 0x0 point (encoded as “0000”) in the string. * **-** Points outside the bounds of the 300x100 pixel canvas will not be rendered, and should not be included. * **-** The SIGNATURE string can be a minimum length of 4 characters (1 point) and a maximum of 1600 characters (400 points). * **-** The recording canvas should always have a 3:1 width to height ratio. * **-** If the canvas that the signature is recorded on is of a larger size, the magnitude of the X and Y values should be scaled down proportionately to a 300x100 boundaries respectively. * **-** Example SIGNATURE string: "4i1m621m00005a125a2e" will draw a 40x40 pixel “plus” symbol in the middle of the canvas. ===== The MaxMind MinFraud Fields ===== This feature is a service to other features in HP and XML integration methods. When used, this service provides a score for the transaction between 0.01 and 100 (riskScore), effectively the percentage chance that it could be fraudulent. Certain fields are required for performing fraud scoring on the transaction using the MaxMind MinFraud service. This service can be enabled in the Terminal Setup section of our SelfCare System. Each feature of each integration method is going to present details on how to use it, if available, and all you have to do is make sure the terminal in use has this feature settings enabled at its Security & Fraud section, and that your integration is providing the data necessary for the verification. Read more about this service is available on the **[[https://www.maxmind.com/en/ccv_overview|MaxMind]]** website. ===== Nuvei Fraud Solution Fields ===== This feature is also an additional service to existing features in HPP and XML integration methods. Fraud Solution provides software as a service (SaaS) technology that profiles online transactions and activities to determine whether they initiate from fraudsters or legitimate customers. The Payment Gateway accepts or rejects transactions based on the Fraud Solution analysis, enhancing the fraud prevention and threat detection for payment transactions on the Nuvei platform. Each feature of each integration method is going to present details on how to use it, if available, and all you have to do is make sure the terminal in use has this feature settings enabled at its Security & Fraud section, and that your integration is providing the data necessary for the verification. **TERMINAL CONFIGURATION**\\ The terminal used to process the transaction must have the Fraud Solution feature enabled and configured if you want it used on the transaction or any transaction processed by that terminal. The terminal returned with **REVIEW**, when using Fraud Solution, needs to be manual reviewed by the Merchants. A new report feature on Selfcare System allows Merchant to manually accept transaction marked as **REVIEW** by Fraud Solution and the XML gateway allows the use of the status update service to change a transaction to **APPROVE** or **REJECT** depending on the merchant's needs. Be aware transaction with REVIEW status are not going to be settled until it is rejected or approved by the merchant. **SAMPLE RESPONSE CODE:** **APPROVED:** * **UNIQUEREF:** JZUBX2INT8 * **RESPONSECODE:** A * **RESPONSETEXT:** APPROVAL * **APPROVALCODE:** UVUVUM * **FRAUDREVIEWRESPONSE:** * **FRAUDREVIEWSTATUS:** PASS * **FRAUDREVIEWRISKRATING:** LOW * **FRAUDREVIEWSCORE:** -20 * **FRAUDREVIEWREASONCODE:** NO DEVICE ID * **DATETIME:** 2019-06-28T18:41:02 * **AVSRESPONSE:** U * **CVVRESPONSE:** M * **HASH:** 135ef96ed3c28ef5f92a0919d9c9e73e6d855a9701ccf37911578f372265407f1a43ae2fc18119884d3ee73483c904a930112875ac90722e1e0347e93b4cf1a5 **REJECT:** * **UNIQUEREF:** BKMDDH6DM0 * **RESPONSECODE:** D * **RESPONSETEXT:** RISK REJECTION * **APPROVALCODE:** UVUVUM * **FRAUDREVIEWRESPONSE:** * **FRAUDREVIEWSTATUS:** REJECT * **FRAUDREVIEWRISKRATING:** LOW * **FRAUDREVIEWSCORE:** -20 * **FRAUDREVIEWREASONCODE:** NO DEVICE ID * **DATETIME:** 2019-06-28T18:50:50 * **AVSRESPONSE:** U * **CVVRESPONSE:** M * **HASH:** df1dccbcb360688c4d56f5197cda8ff1c7f80a0d8bcf12570681064b2d3568deac354f6e46e1c72bb8f6a4aea99bb52dc5dd301522643e24d96d313c2034c420 **REVIEW:** * **UNIQUEREF:** BK8C9KCC03 * **RESPONSECODE:** A * **RESPONSETEXT:** APPROVAL * **APPROVALCODE:** UVUVUM * **FRAUDREVIEWRESPONSE:** * **FRAUDREVIEWSTATUS:** REVIEW * **FRAUDREVIEWRISKRATING:** LOW * **FRAUDREVIEWSCORE:** -20 * **FRAUDREVIEWREASONCODE:** NO DEVICE ID * **DATETIME:** 2019-06-28T18:52:53 * **AVSRESPONSE:** U * **CVVRESPONSE:** M * **HASH:** 446345d95b9f5296ced5367e515260237409c5677531485b1da774ea1713b32df9ae3ab3fbe8ad249302d6453697a38e57b6af62077271040771713e66e05981