Chapter 3 - Notes Before Continuing

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 modifed by a “ man-in-the-middle” attack. This is achieved by including all the sensitive felds into a string, which varies per request type, along with the shared secret, confgured per terminal. This string is then used as the basis of an SHA-512 HASH.

When explaining the data structure for requests and responses, this document is also going to present for each feature the formation rule of its request and response HASH. Those rules are going to look like this:

TERMINALID:ORDERID:AMOUNT:DATETIME:SECRET

The ":" (colon) symbols used in the example above are the elements' separators and they ALWAYS NEEDS TO BE ADDED to defne the separation of two elements.

It's important to understand that the separator should only be used to separate two elements with values, therefore the following example are correct:
• element[1]value
• element[1]value:element[2]value
• element[1]value:element[2]value:element[n]value

If a HASH formation rule defnes an element which your request doesn't have, you can't use the separator for that element. Consider a HASH for the data below using the structure and rules 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.

Note that the sha512 method should always use a character encoding of UTF-8 where appropriate, as should all data sent to the payment gateway.

Remember to implement the specifc 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 difer in small details.

ACH payments can be processed in USD only. However some Nuvei Terminal IDs are classifed as multi-currency for other tender types. To maintain compatibility with these other tender types some hash calculations for ACH requests & responses vary between single currency and multi-currency terminals.

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 diferent types of custom felds: Explicit and Implicit.

Explicit Custom Fields: All the custom felds that are mentioned in this document are explicit custom felds, all custom felds in the XML gateway are also. They must be pre-confgured in the SelfCare System (Setting ->i Custom Fields) for the particular Terminal ID that you are sending the transaction through.

Implicit Custom Fields: Any other felds that are sent to the Hosted Payment Page are considered to be implicit custom felds. 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 felds are not supported by the XML gateway.

A Custom Field is set up to be one of three types:

Boolean: Accepted values are “0”, “1”, “true” or “false”

Numeric: Any numeric only value

String: Any value containing only alphanumeric characters, spaces or the following characters: '-&*()_+:;@#|.,/

The ACH Authorization Gateway uses the Standard Entry Class (SEC) codes to determine what information is required to be sent in the submission. The National Automated Clearing House Association (NACHA) requires the use of SEC Codes for each transaction settled through the Automated Clearing House (ACH). Each code identifes what type of transaction occurred. A defnition of each of the supported SEC codes used by the Nuvei can be found below.

Internet Initiated Entry (WEB): An internet initiated entry is a method of payment for goods or services made via the internet.

Telephone Initiated Entry (TEL): A telephone initiated entry is a payment for goods or services made with a single entry debit with oral authorization obtained from the consumer via the telephone.

Nuvei provide Hosted Pages for the entry of some sensitive data so that the merchants servers do not have to be exposed to this data. This is advisable to reduce the security overhead of the integrated solution as Nuvei is responsible for maintaining the security and integrity of the data sent to these pages. The payment is then processed by Nuvei and the account holder is redirected to the merchant's receipt page.

The Nuvei hosted pages can be heavily styled and are device aware, responsive and reactive, depending on the amount of efort the developer wants to put in to styling them.

As you can see from the image above it is simple to confgure separate templates to be used for various devices. This is intended as a shortcut; a simple way of “cheating” the customer to think it's a responsive webpage, however a single template can be made totally responsive if desired.

As you can see diferent templated can also be used for Mail Order (TEL) and eCommerce transactions (WEB).

There are three permanent templates and they default to some sample styles. They do not all have to be used.

Images can be included but the image fles must be hosted on the merchants website. The URL of the image will be required in the Payment Page styling.

Note: only users who have “Pay Pages” permissions will have access to this interface. It can be found once logged in by clicking “Settings” and then “Pay Pages” in the menu.