Overview

This topic describes the cryptographic hash-based SHA-256 tokens used 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 key 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 key 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 by generating a sessionToken:

• For Web SDK and Simply Connect flows, call an /openOrder API request.
• For Server-to-Server SDK (REST) flows, call a /getSessionToken API request as described below.

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

Sending a /getSessionToken

Send the /getSessionToken request with its mandatory parameters.

When calculating the checksum parameter value:

1. Concatenate the following fields in this order, with no spaces, and no separators between the fields:
   merchantId, merchantSiteId,clientRequestId,timeStamp, merchantSecretKey
2. Calculate the SHA-256 hash of the concatenated fields.

Example /getSessionToken Request

{
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

Example /getSessionToken Response

The response returns a sessionToken, which is used in sending the /payment request.

{
  "sessionToken":"7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0",
  "internalRequestId":188635168,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"479748173730597238",
  "merchantSiteId":"180083",
  "version":"1.0",
  "clientRequestId":"20200510165419"
}

Hashing Calculation (the “checksum” parameter)

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, merchantSecretKey
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 SHA-256 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 = 20200101131211
   • merchantSecretKey = Secret1234
   
   This is the concatenation of the string before hashing:
   238966805752074749319911610EUR20200101131211Secret1234
   
   
   This is the result after performing the SHA-256 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.nuvei.com/automation/checksum_calculator.