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.
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:
- 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 achecksum
for the/getSessionToken
API method:
merchantId
,merchantSiteId
,clientRequestId
,timeStamp
,{your secret key}
- 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.
- Include exactly the same fields as in the request.
- Perform a SHA256 hash on the concatenated string.
The resulting value is thechecksum
, which you can now include in the request.Example of Calculating the
checksum
for the/openOrder
API MethodThis is the set of request parameter fields (and field order) required:
merchantId
= 2389668057520747493merchantSiteId
= 199116amount
= 10currency
= EURtimestamp
= 2020-01-01 13:12:11merchantSecretKey
= 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
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.