# 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](https://docs.verygoodsecurity.com/cmp/developer-resources/api/3d-secure-3ds).

### 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](https://docs.verygoodsecurity.com/cmp/developer-resources/api/3d-secure-3ds#post-cards-card_id-3ds-initialize).
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.

   <figure><img src="https://236204706-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg1pA9re6lCmtaiQAnvjh%2Fuploads%2FfJaoRabjE2DKXhYMuhEU%2F3DS%20Initialize%20flow%20diagram%20-%201%20light-min.png?alt=media&#x26;token=c7185583-45d7-4f7b-ba74-506b446c0333" alt=""><figcaption></figcaption></figure>

### 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](https://docs.verygoodsecurity.com/cmp/developer-resources/api/3d-secure-3ds#threeds-challenge).
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).
   * **Important - Rendering the Challenge HTML:**&#x20;
     * The `challengeHtml` returned by the VGS Authenticate API contains a redirect form generated by the issuer’s Access Control Server (ACS) and delivered through the 3DS server. This HTML initiates the cardholder challenge and must be rendered exactly as returned inside a browser context such as a modal, popup, or iframe.
     * The ACS redirect page may behave differently depending on the issuer implementation. Two common behaviors are possible:
       * The page displays a submit button that the cardholder must click to proceed to the issuer’s challenge screen.
       * The page automatically submits the form using JavaScript, immediately redirecting the browser to the issuer challenge without requiring any user interaction. In the auto-submit case, the “click here to continue” button only appears if JavaScript is blocked.
     * Both behaviors are valid and controlled entirely by the issuing bank. Your integration should not rely on the presence of a visible button or any specific UI elements within the challenge page.
     * **Implementation requirements:** When rendering the challenge HTML:
       * Treat the returned `challengeHtml` as opaque content and render it exactly as provided. Do not modify the form, scripts, or URLs contained within it.
       * Render the HTML inside a browser-capable environment (for example, an iframe, modal, popup window, or webview) that allows JavaScript execution and form redirects.
       * Allow the browser to follow any redirects initiated by the page.
       * After the form is submitted (either manually or automatically), the browser is redirected to the issuer’s ACS where the authentication may take place. Depending on the issuer’s risk decision, the cardholder may be presented with a challenge (for example OTP, banking app approval, or biometric verification), or the issuer may immediately return a final authentication result.
       * In some cases, the challenge UI may not appear even after the redirect. This can occur if the issuer makes a risk decision early in the authentication flow, or if there is a temporary technical issue with the ACS or a downstream service.
       * The final authentication result is determined by the issuer and delivered asynchronously. Once the authentication process is completed, abandoned, or times out, you will receive the final status via the VGS `cmp_threeds.challenge_result` webhook. Alternatively, you may retrieve the current status using the `/3ds-check` endpoint.
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.

{% hint style="info" %}
VGS does not currently return `messageVersion` in the `3ds-authenticate` or `3ds-check` responses. For PSPs that require the 3DS version to be provided explicitly in the authorization request, customers should **use `2.2.0`.** This applies to both challenge and data-only flows.
{% endhint %}

<figure><img src="https://236204706-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fg1pA9re6lCmtaiQAnvjh%2Fuploads%2FPIzyfzbgSp8ZOWUmQNjF%2F3DS%20Challenge%20flow%20diagram%20-%203%20light-min.png?alt=media&#x26;token=27061729-5562-4e45-b4f6-d7e45e59bc6d" alt=""><figcaption></figcaption></figure>

### **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` (<kbd>conditional</kbd>)
  * **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

{% hint style="info" %}
VGS does not currently return `messageVersion` in the `3ds-authenticate` or `3ds-check` responses. For PSPs that require the 3DS version to be provided explicitly in the authorization request, customers should **use `2.2.0`.** This applies to both challenge and data-only flows.
{% endhint %}