Overview

This topic describes the cryptographic hash-based SHA-256 tokens use by Nuvei for API authentication.

Merchant Credentials

Nuvei provides the following encrypted merchant credentials for you to include in API requests which identifies you as the merchant:

• merchantId – Identifies you as the merchant.
  Provided to you by Nuvei. Needs to be sent with each request to our API.
• merchantSiteId – Identifies your site ID.
  Provided to you by Nuvei. Needs to be sent with each request to our API.
• merchantSecretKey – This is the authentication component of the hash.
  Provided to you by Nuvei.
  You must keep the secret in a secure and confidential storage area, not accessible by any third party, protected, preferably in encrypted storage. Under no circumstances should you pass the secret to your frontend.

sessionToken

A sessionToken is an encrypted authentication token which you are required to include in all API calls. The system generates a sessionToken upon request, and the token expires after 15 minutes.

Begin each new session / flow by generating a sessionToken:

• Call an /openOrder API request for Web SDK and Checkout flows.
• Call a /getSessionToken API request for Server-to-Server SDK (REST) flows.

Use the returned sessionToken in all the subsequent requests in the session / flow.

Hashing Calculation (the “checksum” field)

Some Nuvei API methods require you to calculate and include a checksum parameter (sometimes called a “hashing” field) in the request.

Calculating checksum parameters used throughout the Nuvei system follows the same basic procedure, but uses different sets of input values, as specified for each Nuvei API method:

1. Check the Nuvei API Reference Guide for the particular Nuvei API method, to determine the set of request parameter fields (and field order, etc.) required to calculate that particular checksum.
   
   For example, these are the fields required to calculate a checksum for the /getSessionToken API method:
   merchantId, merchantSiteId,clientRequestId,timeStamp, {your secret key}
2. Concatenate the values of the required fields into a string as follows:
   • Include exactly the same fields as in the request.
     (If certain fields are specified in the documentation, but you did not send them or left them empty in the request, then leave them out of the concatenation as well.)
   • Place the fields in exactly the same field order as in the request.
     (The field order is generally the order in which you placed the fields in the request, unless specified differently in the documentation.)
   • Use exactly the same field values as in the request.
   • No spaces and no separators between the fields.
3. Perform a SHA256 hash on the concatenated string.
   The resulting value is the checksum, which you can now include in the request.

   Example of Calculating the checksum for the /openOrder API Method

   This is the set of request parameter fields (and field order) required:

   • merchantId = 2389668057520747493
   • merchantSiteId = 199116
   • amount = 10
   • currency = EUR
   • timestamp = 2020-01-01 13:12:11
   • merchantSecretKey = Secret1234
   
   This is the concatenation of the string before hashing:
   238966805752074749319911610EUR2020-01-01 13:12:11Secret1234
   
   
   This is the result after performing the SHA256 hash on the concatenated string:
   checksum value =
   9eafac386946d677406916b33e1dfb73570a0c176c91da24e7e8f25061c9ecc5
   In the example above, we did not include the optional clientRequestId field.

Nuvei’s Checksum Tool

Nuvei provides a tool for calculating checksums, which is pre-populated with your parameters and their values. You can access it once you are granted access to our sandbox environment at https://sandbox.safecharge.com/automation/checksum_calculator.