3DS MPI-Only REST

Home    Online Payments    3D Secure    3DS Implementations    3DS MPI-Only REST

On this page:

Overview

This topic describes the Nuvei 3DS MPI-Only REST (for Server-to-Server) integration for 3D Secure (3DS) authorization and initiating the next relevant step.

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

When to Use This Integration

The integration is suited to these scenarios:

  • To use the Nuvei 3DS Authorization-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 3DS Authorization-only followed by a /payment API call.
  • PCI level-1 merchants – Merchants with the highest PCI level, who process, transmit and store cardholder information for themselves.
  • Multiple-PSP processing merchants – Merchants who process with Nuvei as well as other PSPs and acquirers.

Server-to-server integrations are relatively complex. In most cases, these integrations are less recommended than our 3DS MPI-Only Web SDK solution, which is easier to implement. However, there are clear cases where server-to-server is the correct integration to use.

Simulating and Testing Your Integration

You can use Postman to run the full workflow in any of these workflow simulations in the Nuvei sandbox environment:

  • “MPI Only (using /authorize3d and /verify3d)”
  • “3DS Challenge flow”
  • “3DS Frictionless flow”

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

Refer to the Testing Cards section for Nuvei test card details and instructions on how to use them in the supported scenarios.

Other test values on the code samples:

  • Use CL-BRW1 as the cardHolderName for the challenge flow.
  • Set amount greater than 150 to trigger a challenge.

The test card used in the code samples demonstrates 3DS flow.


Step 1: Authentication

To generate the authentication token required for the API calls (sessionToken), either:

  • Post a /getSessionToken API server-side call.
  • Initialize the SafeCharge object as shown in the example below.

You must calculate the checksum value as follows:

  1. Concatenate the following fields in this order, with no spaces, and no separators between the fields:
    merchantId, merchantSiteId,clientRequestId,timeStamp, merchantSecretKey
  2. Calculate the SHA-256 hash of the concatenated fields.
Example /getSessionToken Request
{
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "clientRequestId": "<unique request ID in merchant system>",
    "timeStamp": "<YYYYMMDDHHmmss>",
    "checksum": "<calculated checksum>"
}
$safecharge = new SafeChargeApiRestClient([
'environment' => SafeChargeApiEnvironment::INT,
'merchantId' => '<your merchantId>',
'merchantSiteId' => '<your merchantSiteId>',
'merchantSecretKey' => '<your merchantSecretKey>',
]);
public class Main {
    public static void main(String[] args) {
        String merchantId = "<your merchantId>";
        String merchantSiteId = "<your merchantSiteId>";
        String merchantKey = "<your merchantKey>";

            safecharge.initialize(merchantId, merchantSiteId, merchantKey, Constants.HashAlgorithm.SHA256);
    }
}
var safecharge = new Safecharge(
"<your merchantKey>",
"<your merchantId>",
"<your merchantSiteId>",
"<your server host value>",
HashAlgorithmType.SHA256
);
const safecharge = require('safecharge');
safecharge.initiate(<merchantId>, <merchantSiteId>, <merchantSecretKey>, <env>);
Example /getSessionToken Response

The response returns a sessionTokento use in the payment flow.

{
    "sessionToken": "7db38b03-c1ae-45fc-8fce-8a55cfa4a6e0",
    "internalRequestId": 188635168,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "479748173730597238",
    "merchantSiteId": "180083",
    "version": "1.0",
    "clientRequestId": "20200510165419"
}

Step 2: Render a Payment Form

Render a form to collect the cardholder details on your payment page.

Step 3: Initialize 3DS with /initPayment

Send an /initPayment request to determine if the card supports 3DS and initializes the payment in the Nuvei system.

Include these fields in the request:

  • Provide the payment method details by including either of these (not both):
    • The paymentOption.card class with full card details (as shown below).
    • Or, for a returning customer, you can provide their previously stored payment method, by including these parameters:
      • userTokenId
      • paymentOption.userPaymentOptionId: “<ID of a previously stored payment option>“
  • For 3DS only, if you intend to perform Web Browser Fingerprinting (in the next step), then include the paymentOption.card.threeD.methodNotificationUrl field containing the URL for the issuer to return the fingerprinting notification response.
Example /initPayment Request
{
    "sessionToken": "<sessionToken from /getSessionToken>",
    "merchantId": "<your merchantId>",
    "merchantSiteId": "<your merchantSiteId>",
    "userTokenId": "<unique customer identifier in merchant system>",
    "clientRequestId": "<unique request ID in merchant system>",
    "clientUniqueId": "<unique transaction ID in merchant system>",
    "currency": "USD",
    "amount": "200",
    "paymentOption": {
        "card": {
            "cardNumber": "4000027891380961",
            "cardHolderName": "CL-BRW1",
            "expirationMonth": "12",
            "expirationYear": "2030",
            "CVV": "217",
            "threeD": {
                "methodNotificationUrl": "<methodNotificationURL>"
            }
        }
    },
    "deviceDetails": {
        "ipAddress": "<customer's IP address>"
    }
}
<?php
//initPayment
$initPaymentResponse = $safeCharge->getPaymentService()->initPayment([
    'currency'       => 'USD',
    'amount'         => '200',
    'userTokenId'    => '<unique customer identifier in merchant system>',
    'clientRequestId' => '<unique request ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2030',
            'CVV'             => '217',
            'threeD' =>[
                'methodNotificationUrl'=>'<methodNotificationURL>',
            ]
        ]
    ],
    'deviceDetails'     => [
        "ipAddress"  => "<customer's IP address>"
    ],
]);
?>
{
    // Parameters needed for initPayment call
    String userTokenId = "<unique customer identifier in merchant system>";
    String clientUniqueId = "<unique transaction ID in merchant system>";
    String clientRequestId = "<unique request ID in merchant system>";
    String currency = "USD";
    String amount = "200";

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

    threeD.setMethodNotificationUrl("<methodNotificationURL>");

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

    initPaymentOption.setCard(card);

    SafechargeResponse response = safecharge.initPayment(userTokenId, clientUniqueId, clientRequestId, currency, amount, deviceDetails, initPaymentOption, null, null, null, null);
}
var response = safecharge.InitPayment(
    "USD",
    "200",
    new InitPaymentOption
    {
        Card = new InitPaymentCard
        {
            CardNumber = "4000027891380961",
            CardHolderName = "CL-BRW1",
            ExpirationMonth = "12",
            ExpirationYear = "22",
            CVV = "217",
            ThreeD = new InitPaymentThreeD
            {
                MethodNotificationUrl = "<MethodNotificationUrl>",
            }
        }
    },
    userTokenId: "<unique customer identifier in merchant system>",
    orderId: "33704071",
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    deviceDetails: new DeviceDetails { IpAddress = "<customer's IP address>" });
safecharge.paymentService.initPayment({
    userTokenId            : "<unique customer identifier in merchant system>",
    clientRequestId        : "<unique request ID in merchant system>",
    clientUniqueId         : "<unique transaction ID in merchant system>",
    amount                 : "200",
    currency               : "USD",
    paymentOption  : {
        card: {
            cardNumber      : "4000027891380961",
            cardHolderName  : "CL-BRW1",
            expirationMonth : "12",
            expirationYear  : "2030",
            CVV             : "217",
            threeD :{
                methodNotificationUrl : "<methodNotificationUrl>"
                }
        }
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (initPErr, initPRes, reqData) {
    console.log(initPErr, initPRes);
});
Example /initPayment Response

The fields returned by the /initPayment method include:

  • A threeD class that includes these fields:
    • The version field – Indicates which 3DS version is supported by the card.
    • The v2supported Boolean field –  If true then 3DS is supported by the card.
    • For 3DS only – The methodUrl and methodPayload fields.
  • The transactionId (which is needed if you are using the /authorize3d call in Step 5).
{
    "orderId": "276984098",
    "userTokenId": "asdasd",
    "transactionId": "1110000000011280648",
    "transactionType": "InitAuth3D",
    "transactionStatus": "APPROVED",
    "gwErrorCode": 0,
    "gwExtendedErrorCode": 0,
    "paymentOption": {
        "card": {
            "ccCardNumber": "4****0961",
            "bin": "400002",
            "last4Digits": "0961",
            "ccExpMonth": "12",
            "ccExpYear": "25",
            "cardType": "Credit",
            "issuerCountry": "GB",
            "threeD": {
                "methodUrl": "https://3dsn.sandbox.nuvei.com/ThreeDSMethod/api/ThreeDSMethod/threeDSMethodURL",
                "version": "2.1.0",
                "v2supported": "true",
                "methodPayload": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjMzY2I0ODA0LTA0YmQtNDRhOC1hNmYzLTIxMjRmMDUwM2M3MSIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJ3d3cuVGhpc0lzQU1ldGhvZE5vdGlmaWNhdGlvblVSTC5jb20ifQ==",
                "directoryServerId": "A000000003",
                "directoryServerPublicKey": "rsa;MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAst+HGfPPsX3p6HHEQ9YzourlQj16Nscmm13Cp7cZe4dZB2oWnJqZ7oh/pEoEoOAxBw1x4NFgXKTKdHAeu3VBNVw8SwMTdIC+X16VV+3VIyPbUvJXFp3QoR8WUwPB3F1Lb9SMFNS95boYDZKIOdPW0cP1dRi7pFugsBUZDCP/H3nFfBFHMCBoga+P3AHGj5y8RVpv0hS9jaIsYjX+i58B61OGCB7D0AiADNZJuFzw2+xpNkt6NJJF66FPO8qIh8xR2xGVDf7TtCbss/CugLRgSqKab9YRB8/TBTcy5bxj6O8HD6aL2zGLcMY9dCobXxCodLEtMjJdVL8N+iZrsI2gtwIDAQAB",
                "serverTransId": "33cb4804-04bd-44a8-a6f3-2124f0503c71"
            }
        }
    },
    "customData": "",
    "sessionToken": "3b2126a2-6778-4214-a8c4-269915d5b1e4",
    "internalRequestId": 234842078,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "20210125143714"
}

Step 4: Web Browser Fingerprinting

This step is relevant only for the 3DS flow and only if the methodUrl was returned in the previous step (Step 3: Initialize 3DS).

For instructions on implementing 3DS Web Browser Fingerprinting, see 3DS Web Browser Fingerprinting. This collects client side 3DS browser information and sends a notification (containing the threeDSServerTransId and methodCompletionInd) back to the methodNotificationUrl.

Step 5: Perform 3DS Authorization

Now that 3DS initialization is done, you can use a /authorize3d request to perform a 3DS Authorization-only. This determines whether the issuer:

  • Authorizes the payment and accepts liability (frictionless).
  • Authorizes the payment but does not accept liability (exemption or non-3DS transaction).
  • Declines the payment.
  • Requires a challenge to be performed.

The /authorize3d method uses the same input fields as the /payment method plus a few extra.

The example below shows the mandatory input fields, the threeD class, and other important fields.

Include these fields:
  • Set the relatedTransactionId field to the transactionId returned in Step 3.
  • The threeD Input Class (paymentOption.card.threeD) containing the 3DS fields.
  • In the paymentOption.card.threeD class:
    • If Step 4: Web Browser Fingerprinting was performed, then set paymentOption.card.threeD.methodCompletionInd to the value returned in Step 4.
    • If Web Browser Fingerprinting was not performed, then set the value of the paymentOption.card.threeD.methodCompletionInd to “U” to indicate “unavailable”.
    • Include the notificationUrl field, containing the URL that the issuer should send a notification to after performing the 3DS challenge. This URL is needed for the next step (3DS Challenge).
  • billingAddress class containing:
    • country
    • email
    • firstName
    • lastName
    • address
    • phone (for 3DS card authentication if email not provided)
    • zip
    • city
    • state

      Providing the full billingAddress and shippingAddress classes instead of only the mandatory parameters improves the chances of achieving frictionless authentication.

  • paymentOption class containing:
    • card.cardNumber
    • card.expirationMonth
    • card.expirationYear
    • card.cardHolderName
    • card.threeD.browserDetails.ip (for 3DS card authentication)
    • card.threeD.browserDetails.screenHeight (for 3DS card authentication)
    • card.threeD.browserDetails.screenWidth (for 3DS card authentication)
  • Calculate and include the checksum value as follows:
    1. Concatenate the following fields in this order, with no spaces, and no separators between the fields:
      merchantId, merchantSiteId, clientRequestId, amount, currency, timeStamp, merchantSecretKey
    2. Calculate the SHA-256 hash of the concatenated fields.
Example /authorize3d Request
{
    "sessionToken":"<sessionToken from /getSessionToken>",
    "merchantId":"<your merchantId>",
    "merchantSiteId":"<your merchantSiteId>",
    "clientRequestId":"<unique request ID in merchant system>",
    "clientUniqueId":"<unique transaction ID in merchant system>",
    "amount":"200",
    "currency":"USD",
    "paymentOption":{
        "card":{
            "cardNumber":"4000027891380961",
            "cardHolderName":"CL-BRW1",
            "expirationMonth":"12",
            "expirationYear":"2030",
            "CVV":"217",
            "threeD":{
                "methodCompletionInd":"Y",
                "version":"2.1.0",
                "notificationURL":"<notificationURL>",
                "merchantURL":"<merchantURL>",
                "platformType":"02",
                "v2AdditionalParams":{
                    "challengeWindowSize":"05"
                },
                "browserDetails":{
                    "acceptHeader":"text/html,application/xhtml+xml",
                    "ip":"192.168.1.11",
                    "javaEnabled":"TRUE",
                    "javaScriptEnabled":"TRUE",
                    "language":"EN",
                    "colorDepth":"48",
                    "screenHeight":"400",
                    "screenWidth":"600",
                    "timeZone":"0",
                    "userAgent":"Mozilla"
                }
            }
        }
    },
    "relatedTransactionId":"<initPaymentTransactionId>",
    "billingAddress":{
        "firstName": "John",
        "lastName": "Smith",
        "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',
    'clientRequestId'=> '<unique request ID in merchant system>',
    'paymentOption'  => [
        'card' => [
            'cardNumber'      => '4000027891380961',
            'cardHolderName'  => 'CL-BRW1',
            'expirationMonth' => '12',
            'expirationYear'  => '2030',
            'CVV'             => '217',
            'threeD' =>[
                'methodCompletionInd'=> 'Y',
                'version'=>'2.1.0',
                'notificationUrl'      => '<notificationURL>',
                'merchantUrl'          => '<merchantURL>',
                'platformType'         => '02',
                'v2AdditionalParams' =>[
                    'challengeWindowSize' =>'05',
                ],
                'browserDetails' =>[        // collected on the 3DS fingerprinting
                    'acceptHeader'      => 'text/html,application/xhtml+xml',
                    'ip'                => '190.0.23.160',
                    'javaEnabled'       => 'TRUE',
                    'javaScriptEnabled' => 'TRUE',
                    'language'          => 'EN',
                    'colorDepth'        => '48',
                    'screenHeight'      => '400',
                    'screenWidth'       => '600',
                    'timeZone'          => '0',
                    'userAgent'         => 'Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)'
                ]
            ]
        ]
    ],
    'relatedTransactionId' => 'initPaymentTransactionId', //as returned from initPayment
    'billingAddress' => [
        'firstName' => 'John',
        'lastName' => 'Smith',
        'country'   => 'US',
        'email'     => '[email protected]',
    ],
    'deviceDetails'  => [
        'ipAddress'  => '<customer's IP address>',
    ],
]);
?>
//Initialize the SDK (see https://docs.nuvei.com/?p=29433)

{
    String clientRequestId = "<unique request ID in merchant system>";
    String currency = "USD";
    String amount = "200";

    v2AdditionalParams.setChallengeWindowSize("05");

    browserDetails.setAcceptHeader("text/html,application/xhtml+xml");
    browserDetails.setIp("192.168.1.11");
    browserDetails.setJavaEnabled("TRUE");
    browserDetails.setJavaScriptEnabled("TRUE");
    browserDetails.setLanguage("EN");
    browserDetails.setColorDepth("48");
    browserDetails.setScreenHeight("400");
    browserDetails.setScreenWidth("600");
    browserDetails.setTimeZone("0");
    browserDetails.setUserAgent("Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)");

    threeD.setMethodCompletionInd("Y");
    threeD.setVersion("2.1.0");
    threeD.setNotificationURL("<notificationURL>");
    threeD.setMerchantURL("<merchantURL>");
    threeD.setV2AdditionalParams(v2AdditionalParams);
    threeD.setBrowserDetails(browserDetails);

    card.setCardNumber("4000027891380961");
    card.setCardHolderName("CL-BRW1");
    card.setExpirationMonth("12");
    card.setExpirationYear("25");
    card.setCVV("217");
    card.setThreeD(threeD);

    paymentOption.setCard(card);

    billingAddress.setFirstName("John");
    billingAddress.setLastName("Smith");
    billingAddress.setEmail("[email protected]");
    billingAddress.setCountry("US");

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

    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
            {
                MethodCompletionInd = "Y",
                Version = "2.1.0",
                NotificationURL = "<notificationURL>",
                MerchantURL = "<merchantURL>",
                PlatformType = "02",
                V2AdditionalParams = new V2AdditionalParams
                {
                    ChallengeWindowSize = "05"
                },
                BrowserDetails = new BrowserDetails
                {
                    AcceptHeader = "text/html,application/xhtml+xml",
                    Ip = "192.168.1.11",
                    JavaEnabled = "TRUE",
                    JavaScriptEnabled = "TRUE",
                    Language = "EN",
                    ColorDepth = "48",
                    ScreenHeight = "400",
                    ScreenWidth = "600",
                    TimeZone = "0",
                    UserAgent = "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                }
            }
        }
    },
    clientUniqueId: "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    relatedTransactionId: "initPaymentTransactionId", // as returned from initPayment
    billingAddress: new UserAddress
    {
        FirstName = "John",
        LastName = "Smith",
        Email = "[email protected]",
        Country = "US",
    },
    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",
    clientUniqueId : "<unique transaction ID in merchant system>",
    clientRequestId: "<unique request ID in merchant system>",
    paymentOption  : {
        card : {
            cardNumber      : "CL-BRW1",
            cardHolderName  : "john smith",
            expirationMonth : "12",
            expirationYear  : "2030",
            CVV             : "217",
            threeD :{
                methodCompletionInd:"Y",
                version:"2.1.0",
                notificationUrl      : "<notificationURL>",
                merchantUrl          : "<merchantURL>",
                platformType         : "02",
                v2AdditionalParams :{
                    challengeWindowSize : "05"
                browserDetails :{      // collected on the 3DS fingerprinting
                    acceptHeader      : "text/html,application/xhtml+xml",
                    ip                : "192.168.1.11",
                    javaEnabled       : "TRUE",
                    javaScriptEnabled : "TRUE",
                    language          : "EN",
                    colorDepth        : "48",
                    screenHeight      : "400",
                    screenWidth       : "600",
                    timeZone          : "0",
                    userAgent         : "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:47)"
                }
            }
        }
    },
    relatedTransactionId : "initPaymentTransactionId", //as returned from initPayment
    billingAddress : {
        firstName: "John",
        lastName: "Smith",
        country: "US",
        email: "[email protected]"
    },
    deviceDetails  : {
        ipAddress  : "<customer's IP address>"
    },
}, function (pErr, pResult) {
    console.log(pErr, pResult)
});
Example /authorize3d Response (in this case it includes transactionStatus: “REDIRECT”)
{
    "orderId": "277057469",
    "paymentOption": {
    "userTokenId":"<unique customer identifier in merchant system>",
        "userPaymentOptionId": "<user Payment Option Id>",
        "card": {
            "ccCardNumber": "4****0961",
            "bin": "400002",
            "last4Digits": "0961",
            "ccExpMonth": "12",
            "ccExpYear": "22",
            "acquirerId": "19",
            "cvv2Reply": "",
            "avsCode": "",
            "cardType": "Credit",
            "cardBrand": "VISA",
            "threeD": {
                "threeDFlow": "1",
                "acsUrl": "https://3dsn.sandbox.nuvei.com/ThreeDSACSEmulatorChallenge/api/ThreeDSACSChallengeController/ChallengePage?eyJub3RpZmljYXRpb25VUkwiOiJodHRwczovL2RvY3Muc2FmZWNoYXJnZS5jb20vM0RzaW11bGF0b3Ivbm90aWZpY2F0aW9uVXJsLnBocCIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiOTIyNzgxZjEtMmZlYy00MGQ5LWIyYjUtYTMwMmZkMzRlNWI2IiwiYWNzVHJhbnNJRCI6ImQ1ZWMxMmRkLTQ1ZGUtNDRkYS04YjZmLWNhYjJjYzU0MTVkNCIsImRzVHJhbnNJRCI6IjdmN2UwZGNjLTg3ZTktNDkwYy1iOTFlLWNiZjgwOTdmYjllOSJ9",
                "eci": "5",
                "version": "2.1.0",
                "whiteListStatus": "",
                "cavv": "",
                "acsChallengeMandated": "Y",
                "cReq": "eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjkyMjc4MWYxLTJmZWMtNDBkOS1iMmI1LWEzMDJmZDM0ZTViNiIsImFjc1RyYW5zSUQiOiJkNWVjMTJkZC00NWRlLTQ0ZGEtOGI2Zi1jYWIyY2M1NDE1ZDQiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDUiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIn0=",
                "authenticationType": "01",
                "cardHolderInfoText": "",
                "sdk": {
                    "acsS0ignedContent": ""
                },
                "result": "C",
                "acsTransId": "d5ec12dd-45de-44da-8b6f-cab2cc5415d4",
                "dsTransID": "7f7e0dcc-87e9-490c-b91e-cbf8097fb9e9",
                "threeDReasonId": "",
                "isExemptionRequestInAuthentication": "0",
                "challengePreferenceReason": "12"
            }
        }
    },
    "transactionStatus": "REDIRECT",
    "gwErrorCode": 0,
    "gwExtendedErrorCode": 0,
    "transactionType": "Auth3D",
    "transactionId": "1110000000011302215",
    "externalTransactionId": "",
    "authCode": "",
    "customData": "",
    "sessionToken": "acb48e94-a464-48d8-846a-9142ed556231",
    "internalRequestId": 235059509,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "20210126115246"
}

Handling the authorize3d() Response

The authorize3d() response includes the transactionStatus field which can have one of these values:

  • REDIRECT – A challenge is required, as described in Step 6: 3DS Challenge.
  • APPROVED – The authentication was approved successfully as (frictionless).
    This can be due to one of these cases:
    • A cavv value is returned, the eci* value is either 5 (for Visa) or 2 (for Mastercard), and the issuer accepts liability (liability shift).
      *The Electronic Commerce Indicator (ECI) indicates the level of security used in a 3DS program.

      The process ends here.

    • For 3DS – If you requested a 3DS Exemption, the issuer has approved a non-3DS transaction (the issuer does not accept liability (no liability shift).

      The process ends here.

  • DECLINED – The authentication was declined by the card issuer and the transaction should not proceed to payment.

    The process ends here.

    The authorize3d() response also includes:
    • eci is a negative value and no cavv is returned.
    • errCode and errorDescription are returned.
  • ERROR – An error occurred. The 3DS authentication failed.

    The process can end here.
    However, subject to risk considerations, you may still want to proceed with a Non-3DS (without liability shift) payment transaction, by simply submitting a payment without the threeD class, as shown in the Non-3DS Transaction topic.

    The authorize3d() response also includes:
    • eci is a negative value and no cavv is returned.
    • errCode and errorDescription are returned.

Step 6: 3DS Challenge

For instructions on implementing authentication challenges, see 3DS Authentication Challenge.

Step 7: Verify the 3DS Authorization Result

This step is only relevant if a challenge was performed.

Perform the next relevant step based on the outcome of the 3DS Challenge:

  • If the customer challenge failed, then:
    • CRes contains: transStatus:”N“.
    • The authentication process ends here.
  • If the customer completed the challenge successfully, then:
    • CRes contains: transStatus:”Y“.
    • To complete the authentication process, Call Verify3d, see below.

Step 8: Call verify3d()

Call the /verify3d() request with its mandatory fields, and set the relatedTransactionId to the transactionId returned from the authorize3d call.

This should return the 3DS Authorization results (eci and cavv), which you need to send to your PSP or acquirer (to benefit from the 3DS liability shift).

Example /verify3d() Request
{
  "merchantSiteId": "<your merchantSiteId>",
  "merchantId": "<your merchantId>",
  "sessionToken": "<sessionToken from /getSessionToken>",
  "relatedTransactionId": "<authorize3dPaymentTransactionId>",
  "currency": "USD",
  "amount": "200",
  "paymentOption": {
    "card": {
      "cardNumber": "4000027891380961",
      "cardHolderName": "CL-BRW1",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "CVV": "217"
    }
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "email": "[email protected]",
    "country": "US"
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  }
}
Example /verify3d() Response

A successful authentication returns these values:

  • eci – Either 5 (for Visa) or 2 (for Mastercard).
  • cavv – The encrypted authentication value.
{
  "orderId": "29264489",
  "transactionStatus": "APPROVED",
  "transactionType": "VerifyAuth3D",
  "transactionId": "2110000000000644999",
  "customData": "customData",
  "merchantDetails": {
    "customField1": "merchantName"
  },
  "paymentOption": {
    "card": {
      "ccCardNumber": "4****0961",
      "bin": "541333",
      "last4Digits": "0961",
      "ccExpMonth": "12",
      "ccExpYear": "22",
      "threeD": {
        "threeDFlow": "0",
        "eci": "5",
        "version": "2.1.0",
        "serverTransId": "34cfeb35-5ba6-4df3-a5f1-bf4b93e14476",
        "whiteListStatus": "",
        "cavv": "ZkhQRHd3Mzd6Z2t2MlFLQmRMbW8=",
        "sdk": {},
        "result": "Y",
        "acsTransId": "",
        "dsTransID": "9bd98ea9-035e-4ec3-a863-831fc547473f"
      }
    }
  },
  "sessionToken": "9e07802d-5126-4b02-b4b3-ef09dfb94219",
  "clientUniqueId": "clientUniqueId",
  "internalRequestId": 3329188,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "version": "1.0"
}

For more details about the threeD class returned, see the First Call 3DS Response Parameters section under the threeD Output Class topic.

Last update iconLast modified February 2025