Developers

3D-Secure How-To Guide

Overview

This guide describes how to integrate and work with 3D-Secure in the following payment scenarios:

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

Best Practice Integration

For most merchants, we recommend letting Nuvei handle the 3D-Secure complexity using our Web SDK.

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.

If you wish to only perform the 3D-Secure validation without directly proceeding to payment, refer to 3D-Secure-Only Transaction (MPI) below.

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 of createPayment: 
    sfc.createPayment({
    "sessionToken": '',
    "merchantId": '',
    "merchantSiteId": '',
    "userTokenId": "1234565",
    "clientUniqueId": "695701003", // optional
    "paymentOption": {
      "userPaymentOptionId": "53622598",
    },
    "billingAddress": {
        "country": "GB",
        "email": "john.smith@safecharge.com"
    },
    "deviceDetails": {
        "ipAddress": "93.146.254.172"
    } }, function(res) { console.log(res) })

3D-Secure-Only Transaction (MPI) – Nuvei as the 3D-Secure Provider

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.

The full 3D-Secure-Only Transaction (MPI) payment flow scenario is available for you to test in Postman. The queries simulate the 3D-Secure Authorization and Authentication processing that Nuvei will perform.

If you wish to run these queries in Postman, then import the (click the link) Nuvei Postman collection JSON file into Postman, and follow the instructions in the Testing APIs with Postman section.

Steps

Follow these steps to perform the 3D-Secure validation only, without processing the payment:

  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.
    Example of calling the authenticate3d() method: 
    {
    "sessionToken": result.sessionToken, //received from openOrder API 
    "merchantId": '1475082432483184221', //as assigned by Nuvei
    "merchantSiteId": '184941', //as assigned by Nuvei
    "userTokenId": "230811147",
    "clientUniqueId": "695701003", // optional
    "clientRequestId":"1484759782197",
    "currency":"USD", 
    "amount":"10",
    "paymentOption": {
        "card": {
            "cardNumber": "5111426646345761",
            "cardHolderName": document.getElementById('example1-name').value,
            "expirationMonth": "12",
            "expirationYear": "25",
            "CVV": "217"
        },
        "billingAddress": {
            "email": "someone@somedomain.com",
            "county": "GB" 
        },
        "deviceDetails": {
            "ipAddress": "93.146.254.172" 
        },
        "timeStamp":"20170118191751",
        "checksum":"6b53666fc048a825be63cbb820da467b" 
    }
}

    The authenticate3d() method returns the 3D-Secure authentication values:

    • cavv – The card authentication verification value received from the MPI.
    • eci – The Electronic Commerce Indicator received from the MPI
    • xid – The Transaction ID received from the MPI (for 3D v1).
    • dsTransID – The Transaction ID received from the MPI (for 3D v2).
Next Steps:
  • If the 3D-Secure validation completed successfully, then you can use the authentication values to either:
    • Process the payment using another (third-party) payment provider (with liability shift), by sending an External MPI (Third-Party 3D-Secure) call.
    • Or, you can process the payment using Nuvei as the payment provider, by sending a /payment API call and set the relatedTransactionId field to the transactionId returned by the authenticate3d() method (to guarantee a 3D-Secured transaction).
  • If the 3D-Secure validation either:
    • Failed
    • Or, could not be done (e.g. the user is not enrolled for 3DS (“unenrolled”)) – the cavv value will be returned empty.

    You can either:

3D-Secure-Only Transaction (MPI) – Another PSP as the 3D-Secure Provider

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

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

Follow these steps to perform the 3D-Secure validation only, without processing the payment:

  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, which performs the 3D-Secure validation only, without continuing to payment.
    In order to send the authentication request to another PSP, set the following fields under the threeD block:
    • bin – The BIN number representing the other PSP.
    • merchantId – Your merchant ID (MID) at the acquirer who will process the payment transaction.
    • merchantName – Your merchant name as registered at the acquirer who will process the payment transaction.
    Example of calling the authenticate3d() method: 
    {
"merchantId":"427583496191624621",
   "merchantSiteId":"142033",
   "userTokenId":" 487106",
   "clientUniqueId":"12345",
   "clientRequestId":"1484759782197",
   "currency":"USD",
   "amount":"10",
   "paymentOption": {
        "card": {
            "threeD": {
                  "bin" : "123456",
                  "merchantId" : "654331",
                  "merchantName" : "test merchant"
            }
        }
    },
    "billingAddress": {
        "country": "GB",
        "email": "john.smith@safecharge.com"
    },
    "deviceDetails": {
        "ipAddress": "93.146.254.172"
    }
   "timeStamp":"20170118191751",
   "checksum":"6b53666fc048a825be63cbb820da467b"
}

    The authenticate3d() method returns the 3D-Secure authentication values:

    • cavv – The card authentication verification value received from the MPI.
    • eci – The Electronic Commerce Indicator received from the MPI
    • xid – The Transaction ID received from the MPI (for 3D v1).
    • dsTransID – The Transaction ID received from the MPI (for 3D v2).
  3. TBD After the 3D-Secure validation is completed successfully, you can use the authentication values to continue and process an External MPI (Third-Party 3D-Secure) (with liability shift) with any third-party payment provider.
    Naturally, you can also process the transaction with Nuvei using the /payment API method:
    • To guarantee a 3D-Secured transaction, you must reference the 3D-Secure authentication you performed by setting the transactionId returned from the authenticate3d() method, as the relatedTransactionId field of /payment call.
    • If the 3D failed, but you nevertheless wish to charge it without 3D-Secure protection, then you can send a non-3D-Secure transaction, as described in the Perform a Non-3D-Secure Transaction section below.
Next Steps:
  • If the 3D-Secure validation completed successfully, then you can use the authentication values to either:
    • Process the payment using another (third-party) payment provider (with liability shift), by sending an External MPI (Third-Party 3D-Secure) call.
    • Or, you can process the payment using Nuvei as the payment provider, by sending a /payment API call and set the relatedTransactionId field to the transactionId returned by the authenticate3d() method (to guarantee a 3D-Secured transaction).
  • If the 3D-Secure validation either:
    • Failed
    • Or, could not be done (e.g. the user is not enrolled for 3DS (“unenrolled”)) – the cavv value will be returned empty.

    You can either:

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”.

{
    "merchantSiteId": "{{merchantSiteId}}",
    "merchantId": "{{merchantId}}",
    "sessionToken": "{{sessionToken}}",
    "clientRequestId": "20190605094208",
    "timeStamp": "20190228160209",
    "checksum": "eb50508f5cd2e99797a658f686ceb5ea",
    "clientUniqueId": "uniqueIdCC",
    "currency": "EUR",
    "amount": "10",
    "userTokenId": "someone@website.com",
    "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 a third-party provider. This practice is most commonly used for merchants who are processing with more than one payment provider and have one 3D-Secure provider for all their transactions.

Work with a full third-party 3D-Secure workflow using the Liability-shifted Transaction using 3D Authentication sample. The scenario is contained in the Nuvei Postman collection. Access the collection by importing the JSON file in the link into Postman and following additional instructions in Testing APIs with Postman.

To implement this workflow, you must be sure you retrieve the relevant 3D-Secure authentication value from your third-party 3D-Secure provider:

  • cavv – The card authentication verification value as received from the MPI.
  • eci – The Electronic Commerce Indicator as received from the MPI
  • xid – The Transaction ID received from the MPI for 3D v1. This field is optional for 3D v1; do not send it at all in 3D v2.
  • dsTransID – The Transaction ID received from the MPI for 3D v2. This field is mandatory for 3D v2; do not send at all in 3D v1.

Then, when calling the Nuvei /payment API method, you must set them in the ExternalMpi block:

{
    "merchantSiteId": "{{merchantSiteId}}",
    "merchantId": "{{merchantId}}",
    "sessionToken": "{{sessionToken}}",
    "clientRequestId": "20190605094208",
    "timeStamp": "20190228160209",
    "checksum": "{{checksum}}",
    "clientUniqueId": "uniqueIdCC",
    "currency": "EUR",
    "amount": "10",
    "userTokenId": "someone@website.com",
    "paymentOption": {
        "card": {
            "cardNumber": "5115806139808464",
            "cardHolderName": "test name",
            "expirationMonth": "01",
            "expirationYear": "2020",
            "CVV": "122",
            "threeD": {
                "externalMpi": {
                    "eci": "2",
                    "cavv": "ZkhQRHd3Mzd6Z2t2MlFLQmRMbW8",
                    "xid": "9bd98ea9-035e-4ec3-a863-831fc547473f"
                }
            }
        }
    },
    "billingAddress": {
        "country": "GB",
        "email": "john.smith@safecharge.com"
    },
    "deviceDetails": {
        "ipAddress": "93.146.254.172"
    }
}

API-Only Integration

Nuvei offers an API-only integration to enable accepting payments. The integration methods are more complicated and, in most cases, less recommended than our easier Web SDK Checkout Page solutions. There are, however, several scenarios in which you might prefer it. For more information, see API-Only Integration.

Server to Server MPI Integration

MPI stands for Merchant Plugin, which is the 3D-Secure terminology for a third-party 3D-Secure provider. If you wish to consume 3D-Secure services only from Nuvei, or if you would like to separate the 3D-Secure process from the payment process, you should follow the instructions in the API-Only Integration topic but with the following differences:

  • Calling the /authorize3d (API) method instead of the /payment method. The /verify3d method (unlike the /payment method) performs only the 3D-Secure authorization without proceeding to payment in case of Friction.
  • Once a challenge is performed, you will need to call the /verify3d method rather than the /payment method. Again, instead of performing a fiscal transaction, the /verify3d method merely returns the 3D-Secure authentication values (cavv and eci) that you need to process the transaction with your PSP.