3D Secure

What is 3D Secure?

3D Secure (3DS) is a messaging protocol that enables consumers authenticate with their card issuer when making Card Not Present transactions. The specification was developed by EMVCo and can be found here.

This platform supports 3D Secure 2 (2.1.0, 2.2.0). The issuer uses many parameters to verify card holder authenticity and also asses the risk level to authorize transactions.

It is highly recommended to avoid integrating 3D Secure V1 as major networks are deprecating the support for older versions as early as October 2022.

Integrating 3D Secure in your application.

The library must be loaded before 3D Secure can be used in your application. To enable library please refer to our guide

Step 1 - Initiate 3D Secure Flow

To use 3D Secure, your backend system must initiate the flow by setting attempt3DSecure to true while making the https://<Host>/api/payments/sale API call. It is also required to provide browserInfo parameter when using 3D secure.

You can collect browser info by using PayEngine.collectBrowserInfo() API in your web application.

Visa 3D Secure Update: Action Required

Partners must collect cardholder's mobile number OR email address during payment processing by January 20, 2025. Update existing tokens with this information before use. See Visa Secure Program Guide Updates for details. Contact PayEngine support with any questions you have.

Here is the sample response when you initiate the 3DS flow while making the https://<Host>/api/payments/sale API call

Sample 3DS Response

{
    "data": {
        "ID": "785bee37-8e14-427e-ab07-a3b0c16756a7",
        "TransactionID": "06c2aa36-f968-4205-a5dd-8bf455bdad59",
        "MerchantID": "e6803b29-68a4-4c2a-b3ee-019dfad86c61",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "Description": "Payment for the services",
        "ThreeDSActionRequired": false,
        "token": "card_sandbox_tE8BT9Betjsp7PV46IS9xb1c",
        "ThreeDSType": "frictionless",
        "ThreeDSStatus": "succeeded",
        "ThreeDSData": "eyJ0IjoiMDZjMmFhMzYtZjk2OC00MjA1LWE1ZGQtOGJmNDU1YmRhZDU5IiwiZSI6InNhbmRib3giLCJzIjoiMjAyMi0wMS0xOVQyMjozNDoyMS4wNzJaIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjZjRjOGI2NS0wZjc5LTQzZjYtODhiZi0wMmYwNzYzZTgxMGQiLCJ0aHJlZURTTWV0aG9kVVJMIjoiaHR0cHM6Ly9hY3Muc2FuZGJveC4zZHNlY3VyZS5pby8zZHNtZXRob2QifQ",
        "SaleResponse": {
            "status": "PENDING_3DSAUTH"
        },
        "Metadata": {
            "customerId": "123",
            "email" : "[email protected]"
        }
    }
}

Note: The response will include a transaction ID, which you will use in Step 3 to retrieve transaction details.

Step 2 - Handle 3D Secure Actions

If the response from the https://<Host>/api/payments/sale API call indicates that a 3D secure action is required (i.e. ThreeDSActionRequired=true ), your backend should send the information back to your frontend so the 3DS authentication flow can be performed.

On your frontend, you can easily manage the flow by initiating PayEngine.perform3DSFlow(...) method.

Step 3 - Retrieve Completed Transaction

Once you receive confirmation that sale with 3D Secure has been completed, you can use server-to-server communication to retrieve the transaction details using the transaction ID returned in the /sale API call (Refer here for the sample response)

To retrieve transaction detail, please use https://<Host>/api/merchant/:merchantId/3dstransaction/:transactionId API from your server application using the private API key.

Example: Complete 3DS flow

1. Your client application attempts a secure sale through your backend system.

const response = await axios.post(
    YOUR_BACKEND_SERVER + "/payment/sale",
    {
        browserInfo: PayEngine.collectBrowserInfo(),
        token: token, //Card Token
        invoiceID: invoiceId, //Your system's Invoice ID
    }
);

2. Your backend service initiates 3DS workflow by setting attempt3DSecure to true when making a sale call to the system (see /api/payments/sale).

PHP

// payment/sale handler
$app->post('/payment/sale', function (Request $request, Response $response) use ($client) {

    $body = json_decode($request->getBody()->getContents(), true);

    // POST api/payment/sale request to PayEngine. 
    // Note that the attempt3DSecure was set to true and browser info was 
    // forwarded to PayEngine as provided by the client app.
    $resp = $client->post('/api/payment/sale', [
        'json' => [
            "attempt3DSecure"=> true, 
            "browserInfo" => $body['browserInfo'],
            "merchant_id" => <Your Merchant ID>,
            "data" => [
                'transactionAmount' => <Transaction Amount>,
                'cardToken' => $body['token'],
                'currencyCode' => 'USD'
            ]
        ]
    ]);
    $payload = json_decode($resp->getBody()->getContents());
    
    
    // If 3DS action is required, create a response that your client application
    // can process and initiate 3DS action handling through PayEngine client side
    // library.
    if($payload->data->ThreeDSActionRequired == true ){
        $resp_body = array(
            "ThreeDSActionRequired" => true,
            "ThreeDSData" => $payload->data->ThreeDSData,
        );
        $response->getBody()->write(json_encode($resp_body));
        return $response;
    }


    // If not 3DS payment is needed then process the sale response 
    // as normal sale response and provide appropriate response to your 
    // client application.    
    $response->getBody()->write(json_encode($payload->data));
    return $response
        ->withHeader('Content-Type', 'application/json');
});

3. Your client application checks for 3D secure action required and initiates action handling by calling PayEngine.perform3DSFlow(...)

// Request from Step 1 above.
const response = await axios.post(
    YOUR_BACKEND_SERVER + "/payment/sale",
    {
        browserInfo: await PayEngine.collectBrowserInfo(),
        token: token, //Card Token
        invoiceID: invoiceId, //Your system's Invoice ID
    }
);

// Response handler if 3DS Action is required.
if (response.data.ThreeDSActionRequired) {
    // This call handlers the 3DS workflow
    // Example handler function that just displays the response 
    // In an element called elResult
    PayEngine.perform3DSFlow( 
        response.data.ThreeDSData,        
        function (response) {
            if (response.success) {
                //3DS workflow completed successfully
                //You can call your backend API to retrieve transcation details
            } else {
                //3DS Attempt failed
            }
        }
    );
}

4. Once 3DS transaction is completed successfully, your client application can call your backend system to request for transaction detail.

PHP

$app->get('/transaction/{merchantId}/{transactionId}', function (Request $request, Response $response, array $args) use ($client) {
    $transactionId = $args['transactionId'];
    $merchantId = $args['merchantId'];

    $resp = $client->get('/api/merchant/'. $merchantId .'/3dstransaction/'.$transactionId);
    $payload = json_decode($resp->getBody()->getContents());
    $response->getBody()->write(json_encode($payload->data));
    return $response
        ->withHeader('Content-Type', 'application/json');
});