Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

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

  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.

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.

3DS Status Check

The VGS 3DS Status Check endpoint provides the most up-to-date status of a transaction’s 3DS authentication and device-fingerprinting flow. Use 3ds-check as the primary source of truth for determining the checkout outcome, including after a challenge is completed. Webhook delivery times are not guaranteed and may exceed the allowable time limit.

The endpoint will return HTTP 200 whenever a 3DS result is available for the supplied xid or merchant_transaction_id, including:

  • Frictionless results for challenge flows

  • Pending challenges with status CHALLENGE_REQUIRED

  • Available Data-Only/Data Share results

The endpoint will continue to return HTTP 404 when the supplied identifiers are incorrect or when no authentication result is available. Use the response event and status fields to determine the latest transaction status and outcome.

  • 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

    Using 3ds-check for completed challenges

    • Once the user completes the challenge and returns to the configured redirect_url, call 3ds-check to retrieve the final authentication result.

    • 3ds-check is the recommended and primary approach for completed challenges. Do not wait for a webhook before continuing the checkout flow.

    Handling abandoned challenges

    • Challenge flows involve human interaction, such as entering an OTP or approving a push notification. Because of this, issuers typically keep the challenge session open for 10 to 15 minutes to allow the user time to complete it.

    • If the user closes the challenge window or abandons the transaction, the issuer may not send a final timeout or failure result until the issuer-side session expires. 3ds-check may return HTTP 200 with status: CHALLENGE_REQUIRED while the challenge remains pending, or HTTP 404 when no authentication result is available. Do not use the HTTP status code alone to determine the transaction outcome; inspect the response event and status fields.

    • Recommended approach:

      • Use 3ds-check as the primary way to retrieve the current and final 3DS status.

      • If you are rendering the returned challenge HTML in your own frontend container, implement a frontend listener to detect whether the user manually closes the challenge modal or iframe. If they do, you can immediately treat the transaction as canceled on your end without waiting for the checkout timeout or issuer-side timeout.

      • Keep your own checkout timeout based on your UX needs. For example, if your current timeout is 5 minutes, it is fine to keep that as-is. It does not need to match the issuer’s 10 to 15 minute timeout.

      • If your checkout session expires before the user returns through redirect_url, make one final call to 3ds-check.

      • If 3ds-check returns HTTP 200, use the response event and status fields to determine whether the authentication is complete, pending, approved, or unsuccessful. A CHALLENGE_REQUIRED status means the challenge is still pending.

      • If 3ds-check returns HTTP 404, no authentication result is currently available. You may treat the transaction as expired based on your own checkout timeout, cancel the order, and release the cart or inventory.

      • For Out-of-Band (OOB) flows, the cardholder may complete authentication in their banking app and not return to the browser. Once VGS receives the issuer result, it is available through 3ds-check . In this case, call 3ds-check while the checkout session remains active and once more before treating the session as expired or unsuccessful.

      • Do not rely solely on webhooks for 3DS results. Webhook delivery times are not guaranteed and may exceed the allowable time limit. Use 3ds-check as the primary way to retrieve the current and final status.

    Best practice

    • Use 3ds-check as the primary source of truth for 3DS status and checkout completion.

    • Call 3ds-check after the redirect for completed challenges and once more before your checkout session expires.

    • Use your own checkout timeout to handle sessions that are abandoned or remain unresolved.

    Additional note

    • When you see significantly later completion signals, those cases are typically due to the user abandoning the challenge, closing the challenge window, or taking longer to complete the issuer challenge. This is why implementing 3ds-check is the recommended approach for handling these scenarios reliably.

Non-Payment Authentication (NPA) and Card-Add Flows

VGS 3DS currently supports standard Payment Authentication (PA) flows only. EMV 3DS 2.2 defines Non-Payment Authentication (NPA / messageCategory: 02) specifically for card-add and card-on-file enrollment use cases, but VGS does not currently expose NPA-specific indicators. NPA support is on the roadmap.

In the meantime, if you need to perform card verification or card-on-file enrollment that satisfies PSD2 SCA requirements, you can use the VGS PA flow as follows:

  • Initiate the /3ds-authenticate call by passing a nominal verification amount in the purchase_info object — for example, amount: 0 or amount: 1.00 with the corresponding currency code (for example, 978 for EUR).

  • The issuer will treat this as a standard payment authentication and may step up the user if additional verification is required. VGS will return a CAVV and ECI, which can then be passed into the verification authorization request sent to your PSP or acquirer.

  • Because this runs through the standard PA flow, it uses standard Risk-Based Authentication (RBA). You will not be able to explicitly pass NPA-specific indicators such as "Add Card" or "Mandate Challenge." However, the resulting CAVV and ECI can be used as Strong Customer Authentication (SCA) evidence during card verification and card-on-file enrollment flows.

  • Although the request is processed as a Payment Authentication rather than an NPA transaction, the returned authentication data can be used to satisfy PSD2 SCA requirements for card verification and card-on-file enrollment use cases.

Note: The CAVV generated during a PA flow is tied to that specific authentication event. If the customer later returns to make a new active purchase (CIT), a separate payment authentication should be performed for that transaction.

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.

Previous3DS
Next3DS Authentication

Last updated