API Authentication and the sessionToken

On this page:

API Authentication

Nuvei’s API authentication uses Cryptographic hash-based (SHA-256) tokens.

Nuvei assigns the following unique credentials to all merchants:

  • 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 required to be included in all requests, and expires after 15 minutes.

Begin each flow by sending a request to retrieve a sessionToken:

  • For Web SDK and Checkout SDK flows, send an /openOrder API request.
  • For Server-to-Server SDK flows, send a /getSessionToken API request.

You can use the sessionToken that is returned, in all the subsequent requests in your flow.

Hashing Calculation (the “checksum” field)

Nuvei’s API security is based on Cryptographic hash-based (SHA-256).

The “checksum” (or “hashing”) must be a single string without spaces with the values of the following parameters in the exact order as listed below.

Use exactly the same strings in the checksum as the strings that you send in the request.
Optional fields can be left empty, but then they should also be empty in the request, or not sent in the request at all.

These are the fields to include in the checksum in this order:

  • merchantSecretKey
  • merchantId
  • merchantSiteId
  • amount (of the payment)
  • currency (of the payment)
  • clientRequestId – *This is optional, can be empty
  • timestamp – A timestamp to make the hashing unique for the call
Checksum Example

In this example, we have not included the optional clientRequestId field.

  • merchantSecretKey = Secret1234
  • merchantId = 2389668057520747493
  • merchantSiteId = 199116
  • amount = 10
  • currency = EUR
  • timestamp = 2020-01-01 13:12:11

The concatenation of the string before hashing: Secret1234238966805752074749319911610EUR2020-01-01 13:12:11

The checksum value equals (SHA-256): 9eafac386946d677406916b33e1dfb73570a0c176c91da24e7e8f25061c9ecc5

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.