• 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

3D-Secure How-To Guide

Contents
  • Overview
    • Best Practice Integrations
  • 3D-Secure Enabled Payment Scenarios
    • 3D-Secure for Web SDK
    • 3D-Secure MPI-Only for Web SDK
    • 3D-Secure for Tokenized Cards
    • Perform a Non-3D-Secure Transaction
    • External MPI (Third-Party 3D-Secure)
    • Server-to-Server Integration
    • 3D-Secure MPI-Only for Server-to-Server

Overview

This guide describes various 3D-Secure payment scenarios.

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

Best Practice Integrations

For most merchants, we recommend letting Nuvei handle the 3D-Secure complexity, by using our Web SDKs:

  • 3D-Secure for Web SDK
  • 3D-Secure MPI-Only for Web SDK

3D-Secure Enabled Payment Scenarios

3D-Secure 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 method to place an order on our server.
  2. Then on the client-side, generate the payment form on your web page.
    Note, you can use our Nuvei Fields feature for PCI descoping.
  3. Call the JavaScript createPayment() method of our Web SDK.
  4. Verify the payment result by calling the /getPaymentStatus method or by receiving a DMN with the transaction response.

    Caution!
    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.)
    Note:
    getPaymentStatus is not intended for repeated status polling during the payment processing. Doing so may result in your IP address being blocked.

3D-Secure MPI-Only for Web SDK

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

MPI stands for Merchant Plugin, which is the 3D-Secure terminology for a third-party 3D-Secure provider.

  1. Server-side: Call the /openOrder API method to place an order on our server.
  2. Call the JavaScript authenticate3d() method of our Web SDK. 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 3D-Secure MPI-Only for Web SDK section.

3D-Secure for Tokenized Cards

Nuvei provides tokenization solutions for cases when you need to run 3D-Secure transactions for tokenized cards.

A tokenized card in Nuvei is represented by the userPaymentOptionId field, which is retrieved from a call to the /payment method. A userPaymentOptionId is always related to a userTokenId, which represents a unique identifier for the user and is mandatory for tokenization.

  1. Server-side: Call the /openOrder API method to place an order on our server. In addition to regular mandatory fields, make sure you also provide the userTokenId field, which is mandatory for this case.
  2. To perform a 3D-Secure transaction for a tokenized card, you simply provide the userPaymentOptionId instead of the cardholder details.
    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@safecharge.com"
        },
        "deviceDetails": {
            "ipAddress": "93.146.254.172"
        } }, function(res) { console.log(res) })

Perform a Non-3D-Secure Transaction

Though not recommended, in some case you may want to avoid 3D-Secure altogether. To avoid 3D-Secure, you must set the paymentOption.card.threeD.dynamic3DMode field to “OFF”.

Example /payment Request – with dynamic3DMode OFF
{
    "sessionToken": "<sessionToken from openOrder>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantId>", 
    "clientRequestId": "20190605094208",
    "timeStamp": "20190228160209",
    "checksum": "eb50508f5cd2e99797a658f686ceb5ea",
    "clientUniqueId": "uniqueIdCC",
    "currency": "EUR",
    "amount": "10",
    "paymentOption": {
        "card": {
            "cardNumber": "5115806139808464",
            "cardHolderName": "test name",
            "expirationMonth": "01",
            "expirationYear": "2020",
            "CVV": "122",
            "threeD": {
                "dynamic3DMode": "OFF"
            }
        }
    },
    "billingAddress": {
        "country": "GB",
        "email": "john.smith@safecharge.com"
    },
    "deviceDetails": {
        "ipAddress": "93.146.254.172"
    }
}

External MPI (Third-Party 3D-Secure)

Nuvei supports processing 3D-Secured transactions using 3D-Secure authentication values received from an external MPI 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 more information, see the External MPI (Third-Party 3D-Secure) section.

Server-to-Server Integration

Nuvei offers a Server-to-Server integrations for accepting payments. Server-to-server integrations are relatively complex. In most cases these integrations are less recommended than our Web SDK and Checkout Page solutions, which are easier to implement. However, there are clear cases where server-to-server is the correct integration to use. For more information, see Server-to-Server Integration.

3D-Secure MPI-Only for Server-to-Server

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

MPI stands for Merchant Plugin, which is the 3D-Secure terminology for a third-party 3D-Secure provider.

Use the 3D-Secure MPI-Only for Server-to-Server integration in the following scenarios:

  • To split a payment flow into separate steps, 3D-Secure authorization and payment processing.
  • Or, 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 3D-Secure MPI-Only for Server-to-Server section.

2021 Nuvei. All rights reserved.