3DS MPI-Only Web SDK

On this page:

Overview
Initiating a Session
3DS Authentication
- Handling the authenticate3d() Response
Performing the Server-Side Payment

Overview

This section describes the Nuvei 3DS MPI-Only Web SDK integration for accepting payments.

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

Who uses the Nuvei 3DS MPI-Only Web SDK Integration

The integration is suited to these scenarios:

To use the Nuvei 3DS Authentication-only service and then pass the results to another payment provider (MPI only) to process the transaction.
As one of the steps in a server-to-server payment flow, where you want to perform a 3DS authentication followed by a /payment API call (instead of using the createPayment() method, which would perform all the steps at once).

Refer to our Server SDK guides on how to perform integration in both the strong type (Java, .NET) and the latent type (PHP, Node.JS) language systems.

Refer to the Testing Cards section for Nuvei test card details and instructions of how to use them in the supported scenarios.

Initiating a Session

Sending an /openOrder API call has two main functions:

Authenticates you as our merchant using your given credentials.
Sets up an order in the Nuvei system containing the transaction details, and generates a sessionToken, which is referenced later in the payment flow.

This call must be performed on your backend server, never on the frontend. The /openOrder call described here requires your password, which should NOT be exposed client side.
It is also important to set the order from the server side to prevent front-end user manipulation.
Before using the Server SDK, make sure to initialize the SDK before any request by including the relevant SDK initialization.

You can use Postman to simulate the /openOrder workflow using the “Server to Server with Web SDK” postman collection in the Nuvei sandbox environment. To install Postman and the relevant simulation collection, follow the steps in the Testing APIs with Postman topic.

Send the /openOrder API call and include:

The relevant input parameters as described in the /openOrder topic.

Include a checksum, which is the SHA-256 hash of the following concatenated fields, in this order, with no spaces, and no separators between the fields:
merchantId, merchantSiteId,clientRequestId, amount, currency, timeStamp, merchantSecretKey

Example `/openOrder` Request

{  
  "merchantId":"<your merchantId goes here>",
  "merchantSiteId":"<your merchantSiteId goes here>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "clientRequestId":"<unique request ID in merchant system>",
  "currency":"USD",
  "amount":"200",
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

<?php
$safecharge = new \SafeCharge\Api\RestClient([
'environment' => \SafeCharge\Api\Environment::INT,
'merchantId' => '<your merchantId>',
'merchantSiteId' => '<your merchantSiteId>',
'merchantSecretKey' => '<your merchantSecretKey>',
]);

$openOrderRequest = $SafeCharge->getPaymentService()->openOrder([
    'clientUniqueId'    => '<unique transaction ID in merchant system>',
    'clientRequestId'   => '<unique request ID in merchant system>',
    'currency'          => 'USD',
    'amount'            => '200',
]);
?>

public static void main(String[] args) {
// for initialization 
String merchantId = "<your merchantId>";
String merchantSiteId = "<your merchantSiteId>";
String merchantKey = "<your merchantKey>";
safecharge.initialize(merchantId, merchantSiteId, merchantKey, 
APIConstants.Environment.INTEGRATION_HOST.getUrl(), Constants.HashAlgorithm.SHA256);

//for openOrder
String clientUniqueId = "<unique transaction ID in merchant system>";
String clientRequestId = "<unique request ID in merchant system>";
String currency = "USD";
String amount = "200";
SafechargeResponse response = safecharge.openOrder(userTokenId, clientRequestId,
clientUniqueId, null, null, null, null, currency, amount, null, null, null, null, 
null, null, null, null, null, null, null, null, null, null, null, null, 
null, null, null, null, null, null);
}

var safecharge = new Safecharge(
"<your merchantSecretKey>",
"<your merchantId>",
"<your merchantSiteId>",
"<your server host value",
HashAlgorithmType.SHA256
);
var response = safecharge.OpenOrder(
 "USD",
 "200",
 clientUniqueId: "<unique transaction ID in merchant system>",
 clientRequestId: "<unique request ID in merchant system>"
);

const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
safecharge.paymentService.openOrder({
    'clientUniqueId'   : '<unique transaction ID in merchant system>',
    'clientRequestId'   : '<unique request ID in merchant system>',
    'currency'         : 'USD',
    'amount'           : '200',
}, function (err, result) {
    console.log(err, result)
});

Example `/openOrder` Response

{
  "sessionToken": "64fe6953-69d1-440f-8e21-878c85701f09",
  "orderId": "39272",
  "merchantId": "427583496191624621",
  "merchantSiteId": "142033",
  "clientUniqueId": "12345",
  "clientRequestId": "1484759782197",
  "internalRequestId": 866,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "version": "1.0"
}

3DS Authentication

Perform a 3DS-Only validation by calling the Nuvei Web SDK authenticate3d() method, which validates without performing a payment.

The following example shows the call to authenticate3d() using Nuvei Fields to gain full PCI descoping (PCI SAQ A).
If PCI SAQ A-EP is sufficient, you can pass the cardholder details directly as explained in authenticate3d().
For the HTML part of Nuvei fields, please refer to the Nuvei Fields guide.

Example `authenticate3d()` Request

// Instantiate SafeCharge API
var sfc = SafeCharge({
  env: 'int', // Nuvei API environment - 'int' (integration) or 'prod' (production - default if omitted)
  merchantId: '<merchantId>', //as assigned by Nuvei
  merchantSiteId: '<merchantSiteId>' // your Merchant Site ID provided by Nuvei
});

//Instantiate Nuvei Fields
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.
});

// Activate Nuvei Fields
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() {
  // call authenticate3d
  sfc.authenticate3d({
    "sessionToken": "<sessionToken from openOrder>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "paymentOption": scard,
      "cardHolderName": document.getElementById('cardHolderName').value,
    "billingAddress": {
      "email": "[email protected]",
      "country": "US"
    }
  }, function(result) {
    console.log(result)
  })

}

Example `authenticate3d()` Response

{
  "result": "APPROVED",
  "errCode": 0,
  "errorDescription": "",
  "cavv": "Vk83Y2t0cHRzRFZzRlZlR0JIQXo=",
  "eci": "2",
  "dsTransID": "737eace8-353c-481e-9504-d496aa40485a",
  "ccCardNumber": "4****0961",
  "ccTempToken": "fb13b742-88f6-465d-ba87-3e676beac4d3",
  "bin": "511142",
  "last4Digits": "0961",
  "ccExpMonth": "12",
  "ccExpYear": "22",
  "transactionId": "1110000000004146935",
  "threeDReason": "",
  "threeDReasonId": "",
  "challengeCancelReasonId": "",
  "challengeCancelReason": "",
  "challengePreferenceReason": "12",
  "cancelled": false
}

Handling the `authenticate3d()` Response

The response from the authenticate3d() call includes the result parameter that can have one of these values:

Result	Notes	Next action
APPROVED	A `cavv` value is returned, and the `eci`* value is either 5 (Visa) or 2 (Mastercard). The issuer accepts liability (liability shift). *The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3DS program.	You can do one of these options: Pass the payment details and these results to another payment provider to process the transaction. Perform a server-side liability shift payment by sending a `/payment` API call, and include an `externalMpi` class containing the 3DS authentication values received from the `authenticate3d()` call, as shown below.
APPROVED	For 3DS, if you requested a 3DS Exemption, then "APPROVED" means that the issuer has approved a non-3DS payment (the issuer does not accept liability (no liability shift).	The request for a 3DS Exemption was "APPROVED". Proceed with a non-3DS transaction payment, without liability shift, by simply submitting a payment, without the `threeD` class, as shown below in Example /payment API Request without Liability Shift.
DECLINED	The authentication failed. `eci` is a negative value, and no `cavv` is returned. `errCode` and `errorDescription` are returned.	The transaction should not proceed to payment.
ERROR	The authentication failed. `eci` is a negative value, and no `cavv` is returned. `errCode` and `errorDescription` are returned.	The 3DS authentication failed; however, subject to risk considerations, you may still want to proceed with a non-3DS transaction payment, without liability shift, by simply submitting a payment, without the `threeD` class, as shown below in Example /payment API Request without Liability Shift.

Performing the Server-Side Payment

If the result is APPROVED, then you can proceed to perform a liability shift payment.

Send a /payment API call and include an externalMpi class containing the 3DS authentication values received from the authenticate3d() call as shown in the example below.

Unless you are at PCI level 1, you must send ccTempToken as tokenization. If you are at PCI level 1, you can simply submit the card details under the card class as described in /payment.

The checksum is a hash of the following fields and order: merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey.

If the 3DS authenticate failed (eci=7,6,1; cavv is empty or null), you may still want to proceed with the payment, without liability shift. You can do so by simply submitting a payment without the threeD class.

The /payment API call must be performed server side, never on the front-end.

Input Parameters for the `paymentOption.card.threeD.externalMpi` Class:

Parameter	Description	Mandatory
eci	The ECI value received from the MPI. The ECI value is the result of a 3DS authentication request returned by a Directory Server ("issuer ACS") (namely Visa, Mastercard, JCB, and American Express).)	Required
cavv	The card authentication verification value as received from the MPI.	Required
dsTransID	The transaction ID received from the MPI.	Required
challengePreference	(Note: The use of this parameter is only for "advanced" situations to force 3DS exemptions or challenges.) Note: If you are sending the values received from an external MPI provider, then the `challengePreference` parameter is mandatory. This indicates if an exemption has already been requested in the authentication. (This information can be used to synchronize the exemption flag according to EMVCO and schemes guidelines.) Possible values: ExemptionRequest or NoPreference	Conditional
exemptionRequestReason	(Note: The use of this parameter is only for "advanced" situations to force 3DS exemptions.) Note: If you are sending an exemption requested using `"challengePreference" = "ExemptionRequest"`, then the `exemptionRequestReason` parameter is mandatory. Possible values: AddCard, AccountVerification, LowValuePayment, or TransactionRiskAnalysis.	Conditional

Example `/payment` API Request With Liability Shift – With the `externalMpi` Class

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "card":{
      "ccTempToken":"<ccTempToken received from authenticate3d()>",
      "cardHolderName":"CL-BRW1",
      "threeD":{
        "externalMpi":{
          "eci":"2",
          "cavv":"ejJRWG9SWWRpU2I1M21DelozSXU=",
          "dsTransID":"9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
        }
      }
    }
  },
  "billingAddress":{
    "country":"US",
    "email":"[email protected]"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

//Initialize the SDK (see https://docs.nuvei.com/?p=53233) 

<?php $createPaymentResponse = $safeCharge
    ->getPaymentService()
    ->createPayment([
        'currency' => 'USD',
        'amount' => '200',
        'userTokenId' => '<unique customer identifier in merchant system>',
        'clientRequestId' => '<unique request ID in merchant system>',
        'clientUniqueId' => '<unique transaction ID in merchant system>',
        'paymentOption' => [
            'card' => [
                'ccTempToken' => '<received from authenticate3d()>',
                'cardHolderName'  => 'CL-BRW1',
                'threeD' => [
                    'externalMpi' => [
                        'eci' => '2',
                        'cavv' => 'ejJRWG9SWWRpU2I1M21DelozSXU',
                        'dsTransID' => '9e6c6e9b-b390-4b11-ada9-0a8f595e8600',
                    ],
                ],
            ],
        ],
        'relatedTransactionId' => '<paymentTransactionId>',
        'billingAddress' => [
            'country' => 'US',
            'email' => '[email protected]',
        ],
        'deviceDetails' => ['ipAddress' => '<customer's IP address>'],
    ]); ?>

//Initialize the SDK (see https://docs.nuvei.com/?p=29433)
{
    String userTokenId = "<unique customer identifier in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "<paymentTransactionId>";

    externalMpi.setEci("2");
    externalMpi.setCavv("ejJRWG9SWWRpU2I1M21DelozSXU=");
    externalMpi.setDsTransID("9e6c6e9b-b390-4b11-ada9-0a8f595e8600");

    threeD.setExternalMpi(externalMpi);

    card.setccTempToken("<ccTempToken received from authenticate3d()>");
    card.setCardHolderName("CL-BRW1");
    card.setThreeD(threeD);

    paymentOption.setCard(card);

    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    deviceDetails.setIpAddress("<customer's IP address>");

    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, billingAddress, null, null, null, null, null, null, null, null, relatedTransactionId, null, null, null, null, null, null, null, null);
}

//Initialize the SDK (see https://docs.nuvei.com/?p=48413)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            ccTempToken = "<ccTempToken received from authenticate3d()>",
            CardHolderName = "CL-BRW1",
            ThreeD = new ThreeD
            {
                ExternalMpi = new ExternalMpi
                {
                    Eci = "2",
                    Cavv = "ejJRWG9SWWRpU2I1M21DelozSXU",
                    DsTransID = "9e6c6e9b-b390-4b11-ada9-0a8f595e8600", 
                }
            }
        }
    },
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    relatedTransactionId: "<paymentTransactionId>", // as returned from 1st payment call
    billingAddress: new UserAddress
    {
        Country = "US",
        Email = "[email protected]",
    },
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });

//Initialize the SDK (see https://docs.nuvei.com/?p=53443)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "<unique customer identifier in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    clientUniqueId : "<unique transaction ID in merchant system>",
    paymentOption  : {
        card : {
            ccTempToken      : "<ccTempToken received from authenticate3d()>",
            cardHolderName : "CL-BRW1",
            threeD :{
                externalMpi :{
                    eci       : "2",
                    cavv          : "ejJRWG9SWWRpU2I1M21DelozSXU",
                    dsTransID         : "9e6c6e9b-b390-4b11-ada9-0a8f595e8600" 
                }
            }
        }
    },
    relatedTransactionId = > "<paymentTransactionId>", //as returned from 1st payment call
    billingAddress : {
        country   : "US",
        email     : "[email protected]"
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

Example `/payment` API Request Without Liability Shift

{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "card":{
      "ccTempToken":"ccTempToken received from authenticate3d()",
      "cardHolderName":"CL-BRW1"
    }
  },
  "billingAddress":{
    "country":"US",
    "email":"[email protected]"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

//Initialize the SDK (see https://docs.nuvei.com/?p=53233)

<?php
$createPaymentResponse = $safeCharge->getPaymentService()->createPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '<unique customer identifier in merchant system>',
    'clientRequestId'=> '<unique request ID in merchant system>',
    'clientUniqueId'=> '<unique transaction ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'ccTempToken' => '<ccTempToken received from authenticate3d()>',
            'cardHolderName' => 'CL-BRW1',
        ]
    ],
    'relatedTransactionId' => '<paymentTransactionId>',
    'billingAddress' => [
        'country'   => 'US',
        'email'     => '[email protected]',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '<customer's IP address>',
    ],
]);
?>

//Initialize the SDK (see https://docs.nuvei.com/?p=29433)
{
    String userTokenId = "<unique customer identifier in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String currency = "USD";
    String amount = "200";
    String relatedTransactionId = "<paymentTransactionId>";

    externalMpi.setEci("2");
    externalMpi.setCavv("ejJRWG9SWWRpU2I1M21DelozSXU=");
    externalMpi.setDsTransID("9e6c6e9b-b390-4b11-ada9-0a8f595e8600");

    threeD.setExternalMpi(externalMpi);

    card.setccTempToken("<ccTempToken received from authenticate3d()>");
    card.setCardHolderName("CL-BRW1");
    
    paymentOption.setCard(card);

    billingAddress.setCountry("US");
    billingAddress.setEmail("[email protected]");

    deviceDetails.setIpAddress("<customer's IP address>");

    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, billingAddress, null, null, null, null, null, null, null, null, relatedTransactionId, null, null, null, null, null, null, null, null);
}

//Initialize the SDK (see https://docs.nuvei.com/?p=48413)

var response = safecharge.Payment(
    "USD",
    "200",
    new PaymentOption
    {
        Card = new Card
        {
            ccTempToken = "<ccTempToken received from authenticate3d()>",
            CardHolderName = "CL-BRW1"
        }
    },
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    userTokenId: "<unique customer identifier in merchant system>",
    relatedTransactionId: "<paymentTransactionId>", // as returned from 1st payment call
    billingAddress: new UserAddress
    {
        Country = "US",
        Email = "[email protected]",
    },
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });

//Initialize the SDK (see https://docs.nuvei.com/?p=53443)

$createPaymentResponse = $safeCharge->getPaymentService()->createPayment({
    currency       : "USD",
    amount         : "200",
    userTokenId    : "<unique customer identifier in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    clientUniqueId : "<unique transaction ID in merchant system>",
    paymentOption  : {
        card : {
            ccTempToken      : "<ccTempToken received from authenticate3d()>",
            cardHolderName : "CL-BRW1"
        }
    },
    relatedTransactionId = > "<paymentTransactionId>", //as returned from 1st payment call
    billingAddress : {
        country   : "US",
        email     : "[email protected]",
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

Overview

Who uses the Nuvei 3DS MPI-Only Web SDK Integration

Initiating a Session

Example /openOrder Request

Example /openOrder Response

3DS Authentication

Example authenticate3d() Request

Example authenticate3d() Response

Handling the authenticate3d() Response