3DS Authentication

3DS Challenge Flow

Outlines the mandatory integration steps the Merchant (Frontend and Backend) must perform to execute a 3DS Authentication flow. The process is divided into two distinct phases:

• Initialize (device data collection).

• Authentication (final transaction submission).

• 3DS Status Check Request for real-time status of a 3DS authentication and device fingerprinting process.

Assumption: Customers card is already created with CMP and a card_id has been generated.

For detailed API definitions and parameters, see the 3DS API Spec.

Initialize (Device Fingerprinting)

This is executed primarily on the Merchant Frontend to silently collect device-specific information from the cardholder’s browser. This process must be initiated when the checkout page first loads.

1. Call the VGS Initialize Endpoint:

   • Action: The Merchant Frontend sends a POST request to the VGS method endpoint (/cards/{card_id}/3ds-initialize).

   • Data Required: Include key identifiers such as card_id, merchant_tx_id, and token_type.

   • Initialize API Spec.

2. Embed the Hidden Iframe:

   • Action: Upon receiving the response, which contains the tDSMethodContent (an iframe payload), the Merchant Frontend must immediately embed this content into a hidden iframe on the page.

   • Purpose: This iframe executes the necessary script for silent device fingerprinting and must remain active for up to 10 seconds.

3. Collect Browser Data:

   • Action: Concurrently, the Merchant Frontend must collect standard, non-fingerprint browser details, such as the user agent and the user's IP address. This data will be required for the subsequent Authentication request.

   

Authentication - Challenge Flow

This is triggered by the cardholder confirming the payment. Unlike the frictionless flow, the challenge flow introduces a mandatory user interaction step that must be handled by the Merchant Frontend.

1. Trigger Authentication:

   • Action: When the user clicks the "Pay" button, the Merchant Frontend collects and transmits all necessary data (card data, purchase info, and the browser data from Phase 1, Step 3) to the Merchant Backend.

2. Call VGS Authenticate:

   • Action: The Merchant Backend sends the core transaction request to the VGS /cards/{card_id}/3ds-authenticate endpoint.

   • Data Required: Include all collected data, transaction details (purchase_info), and set the type parameter to challenge.

   • Challenge API Spec.

3. Receive Challenge HTML:

   • Action: Instead of a final status, the Merchant Backend will receive an Intermediate Response (status 'CHALLENGE_REQUIRED' or REJECTED) containing the Challenge HTML (challengeHtml) and transaction IDs.

   • Backend Responsibility: The Merchant Backend must relay this Challenge HTML directly to the Merchant Frontend.

4. Display the Challenge Window:

   • Action: The Merchant Frontend must open a modal, pop-up, or dedicated iframe to display the received Challenge HTML to the cardholder.

   • User Interaction: The cardholder interacts directly with the Issuer ACS interface inside this challenge window (e.g., entering an OTP or password).

5. Handle Challenge Completion (Client-Side Listener):

   • Action: Once the user completes the challenge, the Issuer ACS redirects the browser within the frame to a VGS success/failure endpoint, which then passes the result to the Merchant’s pre-configured endpoint. The Merchant Frontend must have a listener or mechanism to detect when the challenge window closes or redirects.

6. Receive Final Result (Asynchronous or Synchronous):

   • Action: The Merchant Backend will receive an asynchronous webhook with the final success/failure status of the challenge, or if the challenge was abandoned/timed out, a final synchronous result may be returned. The backend must be configured to accept and process this final result.

   • Key Data Received: The final response contains the authentication status (e.g., 'APPROVED', 'UNABLE_TO_AUTHENTICATE'), the cryptographic value (cryptogram), and transaction_info.

7. Authorize Payment:

   1. Action: The Merchant Backend uses the received final status to determine the final risk decision. If the challenge was successful (status APPROVED or equivalent), the backend must use the provided cryptogram to submit the final payment authorization request to the payment processor.

   

3DS Status Check

The VGS 3DS Status Check endpoint allows merchants to retrieve the real-time status of a transaction’s 3DS authentication and device fingerprinting flow. It provides immediate visibility into the authentication process and can be used as a synchronous alternative to webhooks.

• Endpoint to Check Initialize Device Fingerprint Status: GET /cards/{card_id}/3ds-check?inti_received={true}&xid={xid}&merchant_transaction_id={merchant_transaction_id}

• Endpoint to Check Authentication Status: GET /cards/{card_id}/3ds-check?xid={xid}&merchant_transaction_id={merchant_transaction_id}

• 3DS Flow & Real-Time Status Retrieval

  • 3DS Flow Overview – During a 3DS transaction, the customer may go through device fingerprinting or a challenge questionnaire as part of the authentication process.

  • Client Polling for Status – While the transaction is in progress, the client polls the /3ds-check endpoint with the following parameters:

    • cardID

    • xid

    • merchant_transaction_id

    • inti_received (conditional)

  • Behavior based on inti_received:

    • inti_received=true – Returns device fingerprinting initialization status. Call this after the iframe from the synchronous initialize response is rendered and the form containing the iframe is submitted on the front end. This allows the issuer to collect the device fingerprinting.

    • inti_received=false or omitted – Returns authentication status after the challenge questionnaire/html is submitted by the user.

  • Status Retrieval – VGS responds with the most up-to-date status, enabling the merchant to take immediate next steps:

    • Proceed to authorization

    • Update internal transaction state