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 <a href="
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/saleAPI 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 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/saleAPI call
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
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.
// 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.
Note: The response will include a transaction ID, which you will use in to retrieve transaction details.
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 for the sample response)
2. Your backend service initiates 3DS workflow by setting attempt3DSecure to true when making a sale call to the system (see ).