3DS External MPI

Home    Online Payments    3D Secure    3DS Implementations    3DS External MPI

On this page:

Overview

Nuvei supports processing 3D Secure (3DS) transactions using 3DS authentication values received from an external MPI provider.

If you use an external 3DS provider to process your 3DS authentications, then you can use the 3DS authentication values received from them to complete the payment processing with Nuvei.

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

Handling a “Soft Decline” from the External MPI Provider

If the 3DS authentication performed by the External MPI provider returns an “ERROR” response (specifically “error” not “DECLINED“), then, subject to your own risk considerations, you may still want to proceed with a Non-3DS transaction payment without liability shift by simply sending a payment request without a threeD class. To see an example, refer to the Non-3DS Transaction topic.

You can use Postman to run a full third-party “3DS Liability-Shifted Transaction” workflow simulation in the “External MPI” in the Nuvei sandbox environment.

To install Postman and the relevant simulation collection, follow the steps in the Testing APIs with Postman topic.

Payment with externalMpi

To process a payment, send an API /payment request and include the relevant 3DS authentication values received from the external 3DS provider in an externalMpi class as shown in the example below. Include the relevant input parameters:

Input Parameters for the paymentOption.card.threeD.externalMpi Class
ParameterDescriptionMandatory
eciThe 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
cavvThe card authentication verification value as received from the MPI.Required
dsTransIDThe 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 Request with the externalMpi Class (in this case for 3DS)
{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "amount":"200",
    "currency":"USD",
    "userTokenId":"<unique customer identifier in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"CL-BRW1",
            "expirationMonth":"12",
            "expirationYear":"2030",
            "CVV":"217",
            "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' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2030',
            'CVV'             => '217',
            'threeD' =>[
                'externalMpi' =>[
                    'eci'       => '2',
                    'cavv'          => 'ejJRWG9SWWRpU2I1M21DelozSXU',
                    'dsTransID'         => '9e6c6e9b-b390-4b11-ada9-0a8f595e8600'
                ]
            ]
        ]
    ],
    '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";

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

    ThreeD threeD = new ThreeD();
    threeD.setExternalMpi(externalMpi);

    Card card = new Card();
    card.setCardNumber("4000027891380961");
    card.setCardHolderName("CL-BRW1");
    card.setExpirationMonth("12");
    card.setExpirationYear("2030");
    card.setCVV("217");
    card.setThreeD(threeD);

    PaymentOption paymentOption = new PaymentOption();
    paymentOption.setCard(card);

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

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

    Safecharge safecharge = new Safecharge();
    PaymentResponse response = safecharge.payment(userTokenId, clientUniqueId, clientRequestId, paymentOption, null, currency, amount, null, null, deviceDetails, null, billingAddress, null, null, null, null, null, null, null, null, null, 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
        {
            CardNumber = "4000027891380961",
            CardHolderName = "CL-BRW1",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217",
            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>",
    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 : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "CL-BRW1",
            expirationMonth : "12",
            expirationYear  : "2030",
            CVV             : "217",
            threeD :{
                externalMpi :{
                    eci       : "2",
                    cavv          : "ejJRWG9SWWRpU2I1M21DelozSXU",
                    dsTransID         : "9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
                }
            }
        }
    },
    billingAddress : {
        country   : "US",
        email     : "[email protected]"
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});
Last update iconLast modified February 2025