• 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

    3DS Implementations

    On this page:
    • Overview
    • Web SDK 3DS Flows
      • 3DS for Web SDK
    • Server-to-Server 3DS Flows
      • 3DS MPI-Only REST
      • Non-3DS Transaction
      • 3DS External MPI

    Overview

    This guide describes the following 3D-Secure (3DS) authentication flow implementations:

    • Web SDK 3DS Flows
      • 3DS for Web SDK
      • 3DS MPI-Only Web SDK
      • 3DS for Tokenized Cards
    • Server-to-Server 3DS Flows
      • 3DS MPI-Only REST
      • Non-3DS Transaction
      • 3DS External MPI

    For a full explanation of 3D-Secure v1 and v2, refer to 3D-Secure Explained.

    Best practice integrations: For most 3D-Secure applications, we recommend using Nuvei Web SDK 3DS flows and letting us handle the 3D-Secure complexity:

    • 3DS for Web SDK
    • 3DS MPI-Only Web SDK

    However, there are clear cases where you may want more control over the 3DS flow even if it involves extra complexity. In that case, see the Server-to-Server 3DS Flows described below.

    Web SDK 3DS Flows

    3DS for Web SDK

    This payment flow scenario allows you to perform the 3D-Secure validation and proceed directly to payment.

    This is a summary the steps to perform 3D-Secure payments using our Web SDK:

    1. On the server-side, call the /openOrder API request with its mandatory parameters to place an order on our server.
    2. Then on the client-side, generate the payment form on your web page.

      You can use our Nuvei Fields feature for PCI descoping.

    3. Call the JavaScript createPayment() Web SDK request with its mandatory parameters.

      For a full example, see the 3D-Secure with createPayment() topic.

    4. Verify the payment result by calling the /getPaymentStatus request with its mandatory parameters, or by receiving a DMN with the transaction response.

      The /getPaymentStatus can only be called while the session in which the payment was performed is still open. Once the session expires, you receive a “session expired” response.

      The /getPaymentStatus method can only be called at the end of payment processing for that payment.
      (You can detect the end of payment processing by monitoring the JavaScript events for the final transaction event.)
      /getPaymentStatus is not intended for repeated status polling during the payment processing. Doing so may result in your IP address being blocked.

      For full details, see the Web SDK Response Verification topic.

    3DS MPI-Only Web SDK

    This payment flow scenario allows you to perform the 3D-Secure validation only without directly proceeding to payment.

    MPI (Merchant Plugin) is the 3D-Secure terminology for a third-party (external) 3D-Secure provider.

    1. Server-side: Call the /openOrder API request with its mandatory parameters to place an order on our server.
    2. Call the JavaScript authenticate3d() Web SDK request with its mandatory parameters. This method performs the 3D-Secure validation only without continuing to payment.
      The authenticate3d() method returns the 3D-Secure authentication response, which, if successful, can be used to perform a payment.

    For full details, see the 3DS MPI-Only Web SDK topic.

    3DS for Tokenized Cards

    Nuvei provides tokenization solutions for cases when you wish to send 3D-Secure transactions using tokenized cards.

    1. From the server-side, send an /openOrder request with its mandatory parameters, and include a userTokenId field. This will return a sessionToken.
    2. To perform a 3D-Secure transaction for a tokenized card, you simply provide the userPaymentOptionId instead of the cardholder details.

      The encrypted userPaymentOptionId field represents a customers bank account. The most common way of generating a userPaymentOptionId is by sending a /payment request which includes a userTokenId (which is a unique identifier of the customer).

      Example createPayment() Request
      sfc.createPayment({
          "sessionToken": "<sessionToken from openOrder>",
          "merchantId": "<your merchantId>", // your Merchant ID provided by Nuvei 
          "merchantSiteId": "<your merchantSiteId>" // your Merchant site ID provided by Nuvei
          "clientUniqueId": "695701003", // optional
          "userTokenId": "487106",
          "paymentOption": {
            "userPaymentOptionId": "53622598"
          },
          "billingAddress": {
              "country": "GB",
              "email": "john.smith@email.com"
          },
          "deviceDetails": {
              "ipAddress": "93.146.254.172"
          } }, function(res) { console.log(res) })

    Server-to-Server 3DS Flows

    Nuvei offers Server-to-Server integrations for accepting payments.
    For full details, see the Server-to-Server Integration topic.

    Server-to-server integrations are relatively complex. In most cases these integrations are less recommended than our Web SDK and Payment Page solutions, which are easier to implement. However, there are clear cases where server-to-server is the correct integration to use.

    3DS MPI-Only REST

    This payment flow scenario allows you to perform the 3D-Secure validation only, without directly proceeding to payment.

    MPI (Merchant Plugin) is the 3D-Secure terminology for a third-party (external) 3D-Secure provider.

    Use the 3DS MPI-Only REST integration in the following scenarios:

    • To split a payment flow into separate steps, 3D-Secure authorization and payment processing.
    • To use Nuvei to process the 3D-Secure authorization and complete the rest of the payment processing with another PSP.

    This is a summary the steps:

    1. Perform a 3D-Secure authorization using an /authorize3d call.
    2. Use a /verify3d call to retrieve the 3D-Secure authentication values (cavv and eci) needed to process the transaction with another PSP.

    For full details, see the 3DS MPI-Only REST topic.

    Non-3DS Transaction

    Though not recommended, in some case you may want to avoid 3D-Secure altogether.

    Example /payment Request – No threeD Block
    {
        "sessionToken": "<sessionToken from openOrder>",
        "merchantId": "<your merchantId>",
        "merchantSiteId": "<your merchantId>", 
        "clientRequestId": "<unique request ID in merchant system>",
        "timeStamp": "<YYYYMMDDHHmmss>",
        "checksum": "<calculated checksum>",
        "clientUniqueId": "<unique transaction ID in merchant system>",
        "currency": "USD",
        "amount": "200",
        "paymentOption": {
            "card": {
                "cardNumber": "5115806139808464",
                "cardHolderName": "John Smith",
                "expirationMonth": "12",
                "expirationYear": "2028",
                "CVV": "217",
            }
        },
        "billingAddress": {
            "country": "US",
            "email": "john.smith@email.com"
        },
        "deviceDetails": {
            "ipAddress": "127.0.0.1"
        }
    }

    3DS External MPI

    Nuvei supports processing 3D-Secure transactions using 3D-Secure authentication values received from an external MPI (3rd-Party) provider.

    This scenario can occur where you use an external 3D-Secure provider to process your 3D-Secure requirements and then use Nuvei to complete the payment processing.

    For full details, see the External MPI (Third-Party 3D-Secure) topic.

    2022 Nuvei. All rights reserved.