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 3DS, refer to 3DS Explained.

Web SDK 3DS Flows

3DS for Web SDK

This payment flow scenario allows you to perform the 3DS validation and proceed directly to payment.

This is a summary of the steps to perform 3DS 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 3DS 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 3DS validation only without directly proceeding to payment.

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 3DS validation only without continuing to a payment.
   
   The authenticate3d() method returns the 3DS authentication response, which, if successful, can be used to perform a payment.

3DS for Tokenized Cards

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

1. From the server side, send an /openOrder request with its mandatory parameters, and include a userTokenId field. This returns a sessionToken.
2. To perform a 3Ds transaction for a tokenized card, you simply provide the userPaymentOptionId instead of the cardholder details.
   
   The encrypted userPaymentOptionId field represents a customer’s bank account. The most common way of generating a userPaymentOptionId is by sending a createPayment() request, which includes a userTokenId (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: "[email protected]"
       },
       deviceDetails: {
           ipAddress: "<customer's IP address>"
       } }, 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.

3DS MPI-Only REST

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

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

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

This is a summary of the steps:

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

Non-3DS Transaction

Though not recommended, in some cases you may want to avoid 3DS altogether.

Example /payment Request – No threeD Class

{
    "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": "[email protected]"
    },
    "deviceDetails": {
        "ipAddress": "<customer's IP address>"
    }
}

3DS External MPI

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

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

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