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 authorization and initiating the next relevant step.

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

When to Use This Integration

The integration is suited to these scenarios:

  • To use the Nuvei 3D-Secure 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 3D-Secure 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)”
  • “3D secure challenge flow”
  • “3D secure 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 3D-Secure v2 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 3D-Secure with /initPayment

Send an /initPayment request to determine if the card supports 3D-Secure 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 3D-Secure v2 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 3D-Secure v2.x version is supported by the card.
    • The v2supported Boolean field –  If true then 3D-Secure v2 is supported by the card.
    • For 3D-Secure v2 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 3D-Secure v2 flow and only if the methodUrl was returned in the previous step (Step 3: Initialize 3D-Secure).

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

Step 5: Perform 3D-Secure Authorization

Now that 3D-Secure initialization is done, you can use a /authorize3d request to perform a 3D-Secure 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-3D 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 3D-Secure v2 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 3D-Secure challenge. This URL is needed for the next step (3D-Secure 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 3D 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 3D 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: 3D-Secure 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 3D-Secure program.

      The process ends here.

    • For 3D-Secure v2 – If you requested a 3D-Secure Exemption, the issuer has approved a non-3D 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 3D-Secure 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: 3D-Secure Challenge

For instructions on implementing authentication challenges, see 3D-Secure Authentication Challenge.

Step 7: Verify the 3D-Secure Authorization Result

This step is only relevant if a challenge was performed.

Perform the next relevant step based on the outcome of the 3D-Secure 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 3D-Secure Authorization results (eci and cavv), which you need to send to your PSP or acquirer (to benefit from the 3D-Secure 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 3D-Secure Response Parameters section under the threeD Output Class topic.

Last update iconLast modified October 2024