# 3DS Data Sharing

### 3DS Data Sharing 

Data sharing is an optimized 3D Secure authentication flow that can determine a successful or failed outcome **without requiring the cardholder to complete an interactive challenge**. It consists of two distinct phases:

1. **Initialization** for device fingerprinting.
2. **Data-only Request** submitted via the Authentication endpoint.
3. **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.

3DS Data Sharing (data-only authentication) is currently supported for **Visa and Mastercard** transactions.

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%2FoWJBT2MBqRlNiOud3mhq%2F3DS%20Initialize%20flow%20diagram%20-%201%20light-min.png?alt=media&#x26;token=1f1521f9-6bfd-4d18-91cf-664f8a1e7de6" alt=""><figcaption></figcaption></figure>

### Authentication (Data Sharing Request)

This is triggered when the cardholder confirms the payment, typically involving the Merchant Frontend passing data to the Merchant Backend for the final API call.

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 crucially, set the authentication type to `auth_type: "data-only"`.
   * [Frictionless API Spec](https://docs.verygoodsecurity.com/cmp/developer-resources/api/3d-secure-3ds).
3. **Receive and Process Final Result:**
   * **Action:** The **Merchant Backend** receives the synchronous **Final Auth Result** from VGS.
   * **Key Data Received:** Since this is a data-only flow, the response is immediate. It contains the crucial authentication `status`, the cryptographic value (`cryptogram`), and `transaction_info`.
4. **Authorize Payment (Proceed with Transaction):**
   * **Action:** The **Merchant Backend** uses the received `status` to make the final risk decision. If the authentication was successful (frictionless flow achieved), the backend must immediately 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%2FtSMmhmEuCBN1RHzcgNb4%2F3DS%20Data-Only%20flow%20diagram%20-%202%20light-min.png?alt=media&#x26;token=fe188c0e-fa35-463c-90ca-0377a06bf57c" 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 %}