3DS External MPI

On this page:

Overview

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

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

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

Handling a “Soft Decline” from the External MPI Provider

If the 3D-Secure 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 block. To see an example, refer to the Non-3DS Transaction topic.

You can use Postman to run a full third-party “3D-Secure 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 3D-Secure authentication values received from the external 3D-Secure provider in an externalMpi block as shown in the example below. Include the relevant input parameters:

Input Parameters for the paymentOption.card.threeD.externalMpi Block
ParameterDescriptionMandatory
eciThe 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
cavvThe card authentication verification value as received from the MPI.Required
xidThe transaction ID received from the MPI.
(Optional for 3D-Secure v1.)(Do not send it at all for 3D-Secure v2.)		Conditional
dsTransIDThe 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 Request – (in this case for 3D-Secure v2) – with the externalMpi Block
{
    "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":"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' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2030',
            'CVV'             => '217',
            'threeD' =>[
                'externalMpi' =>[
                    'eci'       => '2',
                    'cavv'          => 'ejJRWG9SWWRpU2I1M21DelozSXU',
                    'dsTransID'         => '9e6c6e9b-b390-4b11-ada9-0a8f595e8600'  //xid in case of 3Dv1
                ]
            ]
        ]
    ],
    '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";

    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("john.smith@email.com");

    DeviceDetails deviceDetails = new DeviceDetails();
    deviceDetails.setIpAddress("127.0.0.1");

    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.safecharge.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", //xid in case of 3Dv1
                }
            }
        }
    },
    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 = "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 : {
            cardNumber      : "4000027891380961",
            cardHolderName  : "CL-BRW1",
            expirationMonth : "12",
            expirationYear  : "2030",
            CVV             : "217",
            threeD :{
                externalMpi :{
                    eci       : "2",
                    cavv          : "ejJRWG9SWWRpU2I1M21DelozSXU",
                    dsTransID         : "9e6c6e9b-b390-4b11-ada9-0a8f595e8600"  //xid in case of 3Dv1
                }
            }
        }
    },
    billingAddress : {
        country   : "US",
        email     : "john.smith@email.com"
    },
    deviceDetails  : {
        ipAddress  : "127.0.0.1"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult);
});
 
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 (Note: The use of this parameter is only for “advanced” situations to force 3DS exemptions or challenges.)

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

If you are sending an exemption requested using "challengePreference" = "ExemptionRequest", then the exemptionRequestReason parameter is mandatory.
Possible values: AddCard, AccountVerification, LowValuePayment, or TransactionRiskAnalysis.

Conditional