📃
Developer Docs
  • Overview
  • Integration Options
  • Webhooks
    • Build a webhook endpoint
    • Check signature
  • Getting Started
    • 1. Creating User Accounts
    • 2. User Account Types & Permissions
    • 3. Generate Access Tokens
    • 4. Choose Integration Options
    • 5. Securing Embedded UIs
      • 5a. Securing Embedded UIs Using HMAC (deprecated)
    • 6. Loading the frontend library
      • 6a. Preloading PayEngine Web-Component in SPA
    • 7. Custom styling the Web-Components
    • 8. Handling Callbacks from Web-Components
    • 9. Available Web-Components
    • 10. Available Webhooks
  • Merchant Onboarding
    • Overview
    • Integration Options
    • Onboarding/Payments Application Workflow
    • Embedded Onboarding UI
    • Merchant onboarding APIs
    • Partner's Onboarding UI
    • Merchant Lifecycle
    • Onboarding to Partner Relationships
  • Processing Payments
    • Introduction
      • Transaction Flow and Status
    • SecureFields JS
      • SecureFields Bank Account
      • Using tokens
    • Credit Card Form
    • Connect with Plaid
    • Connect Mailgun
    • 3D Secure
    • Payments API
    • Searching Transactions
    • Registering a cloud connected device
    • Apple Pay
      • Apple Pay in your native app
    • Google Payâ„¢
    • Level 2 and Level 3 Data
    • Fraud Prevention
    • Reporting
    • PCI Compliance
    • Address Verification Service (AVS) Check
    • Hosted Payments
    • Tap to Pay
  • Card Account Updater
  • ORCHESTRATION SYSTEM
    • Orchestration Overview
    • Onboarding Orchestration
    • Transactions Orchestration
    • Omnicommerce Orchestration
    • Merchant Servicing
    • Universal Reporting
  • TOKENIZATION
    • Automatic Network Tokenization
    • Token Migration Process
  • DISPUTE MANAGEMENT
    • Retrieval Requests & Chargebacks
  • Certification
    • Partner Certification
  • Data Sharing
    • Secure Data Sharing with PayEngine
  • eCommerce Integration
    • PayEngine Payment Gateway for WooCommerce
Powered by GitBook
On this page
  • What is 3D Secure?
  • Integrating 3D Secure in your application.
  • Step 1 - Initiate 3D Secure Flow
  • Step 2 - Handle 3D Secure Actions
  • Step 3 - Retrieve Completed Transaction
  1. Processing Payments

3D Secure

PreviousConnect MailgunNextPayments API

Last updated 28 days ago

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 <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/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 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

{
    "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" : "test@test.com"
        }
    }
}

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

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
    }
);
// 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.

$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');
});

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 ).

Visa Secure Program Guide Updates
/api/payments/sale
Step 3
here