• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
    • Choosing an Integration Method
  • Accept Payment
    • Payment Page
      • Quick Start
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments
      • Tokenization-Only Flow
      • Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • FAQs
    • Checkout
      • Quick Start
      • UI Customization
      • Payment Customization
      • Advanced Controls
      • Checkout Examples
    • Server-to-Server
    • Payment Scenarios
    • Mobile SDKs (Beta Release)
      • Android Mobile SDK (Beta Release)
      • iOS Mobile SDK (Beta Release)
    • Flow Diagrams
    • Plugins
      • Magento
        • Rebilling with Magento
      • WooCommerce
        • Rebilling with WooCommerce
      • PrestaShop
        • PrestaShop with Web SDK
        • PrestaShop with Checkout
      • OpenCart
      • Shopify (via AsiaBill)
      • Mirakl
      • Salesforce
      • SAP
      • WIX
    • Marketplaces
  • Features
    • Authentication
    • Financial Operations
      • Refund
      • Void
      • Auth and Settle
      • Partial Approval
      • Currency Conversion (DCC and MCP)
      • Payout
    • Card Operations
      • Card-on-File
      • PCI and Tokenization
      • Zero-Authorization
      • Merchant-Initiated Transactions (MIT)
      • Blocking Cards
    • Subscription (Rebilling)
    • 3D-Secure
      • 3D-Secure Explained
      • 3DS Implementations
        • 3DS MPI-Only Web SDK
        • 3DS MPI-Only REST
        • 3DS External MPI
        • 3DS Responses
      • 3DS Functions
        • 3D-Secure Fingerprinting
        • 3D-Secure Authentication Challenge
    • Callbacks (DMNs)
      • Configuring the Events API
  • Guides
    • Testing Cards, APIs and APMs
      • Testing Cards
      • Testing APIs with Postman
      • Testing APMs
    • Response Handling
    • Alternative Payment Guides (APMs)
    • Airline Ticket Guides
      • Airline Addendum
      • External Authorization Addendum
    • Payment Facilitators (PayFac)
    • Cashier
      • Cashier Events Guide
      • Cashier Features
    • Withdrawal Guide
    • Risk Guide
      • Appendix 1: Transaction Types
      • Appendix 2: Credits and Payouts
      • Appendix 3: Fraud to Sale Programs
      • Appendix 4: Compliance Programs
      • Appendix 5: Chargebacks
    • eKYC Guide
    • Server SDKs
      • Java SDK
      • .NET SDK
      • PHP SDK
      • Node.JS SDK
    • Fast Track Onboarding Developer Guide
    • Currency Conversion Guides
      • Multiple Currency Pricing (MCP)
      • Dynamic Currency Conversion (DCC)
        • DCC in Cashier or Payment Page
        • DCC in REST API Workflows
        • DCC in Web SDK Workflows
    • Website Compliance Guides
  • Additional Links
    • FAQs
    • API Reference
    • Release Notes
    • Country and Currency Codes

Authentication

On this page:
  • Overview
  • Merchant Credentials
  • sessionToken
  • Hashing Calculation (the “checksum” field)
  • Nuvei’s Checksum Tool

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.

2022 Nuvei. All rights reserved.