Chapter 3 - Notes Before Continuing

3.1 HASH Parameters link

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:


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

5B39821025C33A3C37560196F36AF68668E46E82AFC4017434D72E62DBC4C06781AFC6364E992D5594656FB185C901ECE 65ADF85E8822832B8985F602E533EBA

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.

3.2 Multi-currency Terminal IDs link

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.

3.3 Custom Fields link

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:

  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: '-&*()_+:;@#|.,/

3.3.1 Custom Fields with Subscriptions and Stored Subscriptions link

For a Custom Field to be used with Subscriptions it has to be set up under the terminal AND then added under the relevant Stored Subscription.

3.4 SEC Code Parameter link

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.
  • Prearranged Payment and Deposit (PPD): A pre-authorized consumer payment
  • Cash Concentration and Disbursement (CCD): A pre-authorized corporate payment.

3.5 Hosted Pages link

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.

These pages can also be highly styled so that they look very appealing to the customers. This helps improve conversion rates and improves the customers overall payment experience.

3.5.1 Hosted Page Styling link

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. Basic Mode Styling link

Basic template styling requires no knowledge of HTML or CSS. It can allow a merchant to style the page to an acceptable level. Previews of all hosted pages can be viewed on the right hand side.

All new templates created are basic. It's best to style as close as possible to what you are looking for in this mode before clicking “Advanced Mode” for more options. Advanced Mode Styling link

Advanced  mode  allows  you  to  directly  edit  the CSS  of  the  page  and  also  the  HTML  of  the  Header  and  Footer.  It  is recommended not to use Auto Update in this mode.

Because of the custom CSS that can not be reverted to the same constraints as the Basic Mode, once you have entered Advanced mode you cannot go back to Basic Mode styling.

Need Help?

How can we help you today?  Our team is standing by and just a click away.