• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
  • Payment Overview
    • Introduction
  • Accept Payment
    • Checkout Page
      • Quick Start for Checkout
      • Input Parameters
      • Output Parameters
    • Web SDK
      • Quick Start for Web SDK
      • Nuvei Fields
      • Nuvei Fields Stylizing
      • APMs for Web SDK
      • Web SDK Additional Functions
      • Web SDK FAQs
    • Checkout SDK
      • Checkout SDK Payment Form - UI Styling
    • Server-to-Server
    • Plugins
    • Mobile SDKs
      • Android Mobile SDK
      • iOS Mobile SDK
    • Payment Scenarios
    • Flow Diagrams
  • Features
    • API Authentication and the Session Token
    • PCI and Tokenization
    • 3D-Secure
    • Card-on-File
    • Merchant-Initiated Transactions (MIT)
    • Alternative Payment Methods (APMs)
    • Refund
    • Void
    • Auth, PreAuth, Sale and Settle
    • Direct Merchant Notifications (DMNs)
    • Subscription (Rebilling)
    • Zero-Authorization
    • Partial Approval
    • Marketplaces
  • Guides
    • Plugins
      • Magento 1
      • Magento 2
      • WooCommerce
      • PrestaShop
      • Open Cart
      • Shopify (via AsiaBill)
      • Mirakl
    • Choosing an Integration Method
    • Testing Cards, APIs and APMs
      • Testing Cards
      • Testing APMs
      • Testing APIs with Postman
      • Web SDK Scenarios
    • Response Handling and Errors
      • Error Handling
      • Error Codes
    • Country and Currency Codes
    • Direct Merchant Notifications (DMNs)
    • 3D-Secure
      • 3D-Secure Explained
      • 3D-Secure How-To Guide
      • 3D-Secure MPI-Only for Web SDK
      • 3D-Secure MPI-Only for Server-to-Server
      • 3D-Secure Fingerprinting
      • 3D-Secure Authentication Challenge
      • External MPI (Third-Party 3D-Secure)
      • 3D-Secure Response Values
    • Alternative Payments Guide
      • APM Input Fields
      • APM subMethod Classes
      • APM Supported Countries and Currencies
    • Apple Pay
      • Register in the Apple System
        • Create an Apple ID
        • Enroll in the Apple Developer Program
          • Submit an Enrollment Request
          • Complete the Enrollment Process
          • Activate your Apple Developer Program Account
        • Register a Merchant ID in the Apple System
          • Create a Merchant ID
          • Create a Payment Processing Certificate
          • Create a Merchant Identity Certificate
          • Register and Verify your Domain
      • Apple Pay Integration
        • Nuvei Apple Pay Integration Solutions
          • Nuvei Checkout Page IFrame Solution – Main Solution for Cashier
          • Static Apple Pay Button Solution on Merchant Site
          • Dynamic Apple Pay Button Solution on Merchant Site
        • Apple Pay Integration Testing
    • Payment Facilitators (PayFac)
    • Cashier
      • Cashier Events Guide
    • Withdrawal Guide
    • Risk Guide
    • eKYC Guide
    • Server SDKs
      • Java SDK
      • .NET SDK
      • PHP SDK
      • Node.JS SDK
    • Fast Track Onboarding Developer Guide
    • Currency Conversion Services
      • Multiple Currency Pricing (MCP)
        • Accepting Payment for a Sale using MCP Values
      • Dynamic Currency Conversion (DCC)
        • DCC in Cashier or Checkout Page
        • DCC in REST API Workflows
        • DCC in Web SDK Workflows
  • Additional Links
    • FAQs
    • API Reference
    • Release Notes

API Authentication and the Session Token

Contents
  • API Authentication
  • Session Token
  • Hashing Calculation (the “checksum” field)

API Authentication

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

Nuvei will assign 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.

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’s opening request retrieves a sessionToken which you will use to send 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.

Use exactly the same strings in the checksum as the strings that you send in the request.
Optional fields can be empty, but then they need to be empty in the call as well, or not sent 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

This is an of example checksum fields. Note, in this case 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): 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.

2021 Nuvei. All rights reserved.