• 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
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel 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
        • Nuvei Services
        • Transaction Types
        • Credits and Payouts
        • Fraud to Sale Programs
        • Compliance Programs
        • 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

    Tokenization-Only Flow

    On this page:
    • Overview
    • 1. Authenticate the Merchant
    • 2. Generate a ccTempToken
    • 3. Payment with a ccTempToken

    Overview

    This topic describes how to implement a tokenization-only flow.

    Who Uses the Tokenization-Only Flow

    The tokenization-only integration is suited to merchants who:

    • Want to be descoped from PCI but still be in control of the complete flow from their server-side.
    • Perform complete 3D-Secure flows both server-side and client-side.
    • Want to be able to choose either 3D-Secure v1 or v2 flows in frictionless or challenge mode.

    Implementing a full 3D-Secure flow requires a high level of understanding of the 3D-Secure process and of the card schemes mandate. Using the tokenization-only request is not recommended, unless you are familiar with these procedures. For a simpler integration experience, consider using the 3DS MPI-Only Web SDK integration.

    1. Authenticate the Merchant

    Generate a sessionToken by posting a /getSessionToken API server-side call, and include the checksum field.

    Calculate the checksum value as follows:

    1. Concatenate the following fields in this order, with no spaces, and no separators between the fields:
      merchantId, merchantSiteId, clientRequestId, timeStamp, {your secret key}
    2. Calculate the SHA256 hash of the concatenated fields.
    Example /getSessionToken Request
    {
        "merchantId":"<your merchantId>",
        "merchantSiteId":"<your merchantSiteId>",
        "clientRequestId": "<unique request ID in merchant system>",
        "timeStamp": "<YYYYMMDDHHmmss>",
        "checksum": "<calculated checksum>"
    }
    Example /getSessionToken Response

    The response returns the sessionToken, which you need for authentication in all subsequent calls in the flow.

    {
        "sessionToken": "7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0",
        "internalRequestId": 188635168,
        "status": "SUCCESS",
        "errCode": 0,
        "reason": "",
        "merchantId": "479748173730597238",
        "merchantSiteId": "180083",
        "version": "1.0",
        "clientRequestId": "20200510165419"
    }

    2. Generate a ccTempToken

    Perform Tokenization-only using the Nuvei Web SDK getToken() method, which tokenizes the card and cvv and returns the ccTempToken.
    You can then use the ccTempToken to process the payment using the /payment API method.

    Example of getToken() Request
    var sfc = SafeCharge({
        env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
        merchantId: '<your merchantId>', // your Merchant ID provided by Nuvei
        merchantSiteId: '<your merchantSiteId>' // your Merchant site ID provided by Nuvei
      });
    
      var ScFields = sfc.fields({
        fonts: [{
            cssUrl: 'https://fonts.googleapis.com/css?family=Source+Code+Pro'
          }, // include your custom fonts
        ],
        locale: 'en' // You can set your users' preferred locale. If not provided, we try to auto-detect.
      });
    
      var style = {
        base: {
          fontFamily: 'Roboto, sans-serif',
          color: "#045d47",
          fontSmoothing: 'antialiased',
          '::placeholder': {
            color: '#ccb654'
          }
        },
        invalid: {
          color: '#e5312b',
          ':focus': {
            color: '#303238'
          }
        },
        empty: {
          color: '#BADA55',
          '::placeholder': {
            color: '#cc3ac2'
          }
        },
        valid: {
          color: '#2b8f22'
        }
      };
    
      var scard = ScFields.create('card', {
        style: style
      });
      scard.attach(document.getElementById('card-field-placeholder'));  
      
      function main() {
        sfc.getToken(scard).then(function(result) {
          if (result.status === 'SUCCESS') {
            console.log(result.paymentOption.ccTempToken) // pass the paymentOption block, as is, to the payment API call
          } else {
            // handle error.
          }
        });
      }

    3. Payment with a ccTempToken

    You can submit a /payment API request (3D-Secure or Non-3D-Secure) using the Nuvei client-side Web SDK using the ccTempToken returned by the getToken() method.

    This example shows a Non-3D-Secure payment.

    Example /payment Request (non-3D)
    {
        "sessionToken":"<sessionToken from getSessionToken>",
        "merchantId":"<your merchantId>",
        "merchantSiteId":"<your merchantSiteId>",
        "clientRequestId":"<unique request ID in merchant system>",
        "amount":"10",
        "currency":"USD",
        "userTokenId":"<unique customer identifier in merchant system>",
        "clientUniqueId":"<unique transaction ID in merchant system>",
        "paymentOption":{
            "card":{
                "ccTempToken":"<as returned by getToken method>",
                "cardHolderName":"CL-BRW1"
            }
        },
        "deviceDetails":{
            "ipAddress":"127.0.0.1"
        },
        "timeStamp":"<YYYYMMDDHHmmss>",
        "checksum":"<calculated checksum>"
    }
    2022 Nuvei. All rights reserved.