• Documentation
  • API Reference
  • Documentation
  • API Reference
Expand All Collapse All
< BACK TO HOME
  • Online Payments
    • Introduction to Online Payments
    • Choosing an Integration Method
    • Payment Scenarios
    • Flow Diagrams
  • Accept Payment
    • Payment Page (Cashier)
      • Quick Start for Payment Page
      • Input Parameters
      • Output Parameters
      • Payment Page Features
      • Examples of Cashier Demo Sites
      • Cashier
        • Cashier Events Guide
        • Cashier Features
        • Withdrawal Guide
    • Web SDK
      • Quick Start for Web SDK
      • Nuvei Fields
        • Styling
      • Additional Functions
      • APM Payments with Web SDK
      • Tokenization-Only Flow
      • Web SDK Scenarios
      • Using ReactJS
        • Full Samples
        • Sandbox Examples
      • Web SDK FAQs
    • Simply Connect
      • Quick Start to Simply Connect
      • UI Customization
      • Payment Customization
      • Advanced Controls
      • Simply Connect Examples
    • Server-to-Server
      • REST 1.0
      • Server SDKs
        • Java SDK
        • .NET SDK
        • PHP SDK
        • Node.JS SDK
    • Mobile SDKs (Beta Release)
      • Android Mobile SDK (Beta Release)
      • iOS Mobile SDK (Beta Release)
    • Self Track
  • Features
    • Authentication
    • Financial Operations
      • Refund
      • Void
      • Auth and Settle
      • Partial Approval
      • Currency Conversion: DCC and MCP
        • Multiple Currency Pricing (MCP)
        • Dynamic Currency Conversion (DCC)
          • DCC in Cashier or Payment Page
          • DCC in REST API Workflows
          • DCC in Web SDK Workflows
      • Payout
      • Account Funding Transactions (AFTs)
      • P2P Payment with Nuvei
    • Card Operations
      • Card-on-File
      • PCI and Tokenization
      • Zero-Authorization
      • Merchant-Initiated Transactions (MIT)
      • Blocking Cards
    • Subscriptions (Rebilling)
    • 3D-Secure
      • 3D-Secure Explained
      • 3DS Implementations
        • 3DS MPI-Only Web SDK
        • 3DS MPI-Only REST
        • 3DS External MPI
        • 3DS Responses
        • Challenges and Exemptions
      • 3DS Functions
        • 3D-Secure Fingerprinting
        • 3D-Secure Authentication Challenge
    • Addendums
      • Airline
        • External Authorization
      • Local Payment (Installments)
      • Level 2&3 Processing Data
  • Integration
    • Testing Cards, APIs and APMs
      • Testing Cards
      • Testing APMs
      • Testing APIs with Postman
    • Response Handling
      • Webhooks (DMNs)
        • Payment Transaction Requests
        • Control Panel Events API
      • Payment Facilitators (PayFac)
    • Additional Links
      • FAQs
      • API Reference
      • Release Notes
      • Country and Currency Codes

    3DS External MPI

    Home    3D-Secure    3DS Implementations    3DS External MPI

    On this page:
    • Overview
    • Payment with externalMpi

    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
    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 – (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":"<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'     => 'john.smith@email.com',
        ],
        '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("john.smith@email.com");
    
        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 = "john.smith@email.com",
        },
        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     : "john.smith@email.com"
        },
        deviceDetails  : {
            ipAddress  : "<customer's IP address>"
        },
    }, 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

     

     

     

      • Language fr
    • Terms of use
    • Privacy Policy
    Nuvei. All rights reserved.