3DS MPI-Only Web SDK

On this page:

Overview
Initiating a Session
3D-Secure 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 terminology for a third-party (external) 3D-Secure provider.

Who uses the Nuvei 3D-Secure MPI-Only Web SDK Integration

The integration is suited to these scenarios:

To use the Nuvei 3D-Secure 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 3D-Secure 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 SHA256 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"
}

3D-Secure Authentication

Perform a 3D-Secure-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": "john.smith@email.com",
      "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).	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` block containing the 3D-Secure authentication values received from the `authenticate3d()` call, as shown below.
APPROVED	For 3D-Secure v2, if you requested a 3D-Secure Exemption, then "APPROVED" means that the issuer has approved a non-3D payment (the issuer does not accept liability (no liability-shift).	The request for a 3D-Secure Exemption was "APPROVED". Proceed with a Non-3D-Secure transaction payment, without liability shift, by simply submitting a payment, without the `threeD` block, 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. An `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. An `errCode` and `errorDescription` are returned.	The 3D-Secure authentication failed; however, subject to risk considerations, you may still want to proceed with a Non-3D-Secure transaction payment, without liability shift, by simply submitting a payment, without the `threeD` block, 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 block containing the 3D-Secure 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 block as described in /payment.

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

If the 3D-Secure 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 block.

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

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

Parameter	Description	Mandatory
eci	The ECI value received from the MPI. (An Electronic Commerce Indicator (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
xid	The transaction ID received from the MPI. (Optional for 3D-Secure v1.)(Do not send it at all for 3D-Secure v2.)	Conditional
dsTransID	The transaction ID received from the MPI. (Mandatory for 3D-Secure v2.)(Do not send it for 3D-Secure v1.)	Conditional
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` Block

{
  "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":"john.smith@email.com"
  },
  "deviceDetails":{
    "ipAddress":"127.0.0.1"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

//Initialize the SDK (see https://docs.safecharge.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' => 'john.smith@email.com',
        ],
        'deviceDetails' => ['ipAddress' => '127.0.0.1'],
    ]); ?>

//Initialize the SDK (see https://docs.safecharge.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("john.smith@email.com");

    deviceDetails.setIpAddress("127.0.0.1");

    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.safecharge.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 = "john.smith@email.com",
    },
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

//Initialize the SDK (see https://docs.safecharge.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     : "john.smith@email.com"
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, 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":"john.smith@email.com"
  },
  "deviceDetails":{
    "ipAddress":"127.0.0.1"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

//Initialize the SDK (see https://docs.safecharge.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'     => 'john.smith@email.com',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '127.0.0.1',
    ],
]);
?>

//Initialize the SDK (see https://docs.safecharge.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("john.smith@email.com");

    deviceDetails.setIpAddress("127.0.0.1");

    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.safecharge.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 = "john.smith@email.com",
    },
    deviceDetails: new DeviceDetails { IpAddress = "127.0.0.1" });

//Initialize the SDK (see https://docs.safecharge.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     : "john.smith@email.com",
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});

Result	Notes	Next action
APPROVED	This result can be due to either of these cases: A `cavv` value is returned, and the `eci` value is either 5 (Visa) or 2 (Mastercard), and the issuer accepts liability (liability-shift). For 3D-Secure v2 – If you requested a 3D-Secure Exemption, the issuer has approved a non-3D payment (the issuer does not accept liability (no liability-shift).	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` block containing the 3D-Secure authentication values received from the `authenticate3d()` call, as shown below.
DECLINED	The authentication failed. `eci` is a negative value, and no `cavv` is returned. An `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. An `errCode` and `errorDescription` are returned.	The 3D-Secure authentication failed, however, subject to risk considerations, you may still want to proceed with a Non-3D-Secure transaction payment, without liability shift, by simply submitting a payment, without the `threeD` block, as shown below in Example /payment API Request without Liability Shift.


Parameter	Description	Mandatory
eci	The ECI received from the MPI. (An Electronic Commerce Indicator (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
xid	The transaction ID received from the MPI. (Optional for 3D-Secure v1.)(Do not send it at all for 3D-Secure v2.)	Conditional
dsTransID	The transaction ID received from the MPI. (Mandatory for 3D-Secure v2.)(Do not send it for 3D-Secure v1.)	Conditional
challengePreference	(The use of this parameter is only for “advanced” situations to force 3DS exemptions or challenges.) 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	Optional
exemptionRequestReason	(The use of this parameter is only for “advanced” situations to force 3DS exemptions.) If the merchant submitted an exemption requested using a `challengePreference` field, then this parameter displays the reason for the request. Possible values: AddCard, AccountVerification, LowValuePayment, or TransactionRiskAnalysis.	Conditional

Overview

Who uses the Nuvei 3D-Secure MPI-Only Web SDK Integration

Initiating a Session

Example /openOrder Request

Example /openOrder Response

3D-Secure Authentication

Example authenticate3d() Request

Example authenticate3d() Response