Developers

API Authentication and the Session Token

Overview

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

First, as a merchant you will be assigned unique credentials:
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.

Session Token

Each payment request session starts with opening an order session request:

openOrder – Use this method to open a session if you are using the Web SDK.
getSessionToken – Use this method to open a session if you are using the server-to-server SDK.

The session opening request retrieves a sessionToken that you have to send with each call in the session (e.g.  /payment, /getPaymentStatus, etc.).

The session expires after 15 minutes and a new session must be initiated.

Hashing Calculation (the “checksum” field)

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

The “hashing” or the “checksum” as it is sometimes called, must be a single string without spaces with the values of the following parameters in the exact order as listed below.

Fields need to be the exact same strings that are being sent on the request.
Optional fields can be empty, but then they need to be empty on the call as well, or not sent at all.

  • 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
For example:
  • merchantSecretKey = Secret1234
  • merchantId = 2389668057520747493
  • merchantSiteId = 199116
  • amount = 10
  • currency = EUR
  • timestamp = 2020-01-01 13:12:11

* Note: Not using the optional clientRequestId in this call.

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

In this example, the checksum value equals (SHA-256): 1c9becc3578b75b845228a03ec3aa11f6d0e3e680a3f49392fe4d269c74ae020

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.