Home    _TEMP_    3DS External MPI

Tell us about your experience

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
authenticationResponseApplied authentication mode.Conditional
cavvThe card authentication verification value as received from the MPI.Required
cavvAlgorithm3DS 'Cardholder Authentication Verification Value' algorithm. Required for local processing of Carte Bancaire dual branded cards.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
dsTransIDThe transaction ID received from the MPI.Required
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
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
resultResponse3DS authentication status.Conditional
threeDProtocolVersionVersion of the 3DS protocol used for the transaction.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=",
                    "cavvAlgorithm": "<3DSecure Cardholder Authentication Verification Value algorithm>",
                    "dsTransID":"9e6c6e9b-b390-4b11-ada9-0a8f595e8600"
                }
            }
        }
    },
    "billingAddress":{
        "country":"US",
        "email":"[email protected]"
    },
    "deviceDetails":{
        "ipAddress":"<customer's IP address>"
    },
    "timeStamp":"<YYYYMMDDHHmmss>",
    "checksum":"<calculated checksum>"
}
Last update iconLast modified October 2026