search

3D Secure (3DS)

For a fully optimized 3DS flow:

  1. Call the 3ds-initialize endpoint, which may return an iframe for device fingerprinting. If no iframe is returned, initialization isn’t required and authentication can proceed immediately.

  2. Render the iframe on the front end as soon as it’s received from VGS. It can also be loaded as an invisible or background frame while the cardholder waits, so the client doesn’t pause for processing.

  3. Submit the form contained in the iframe, this will start the device fingerprinting process.

  4. Start a 10-second timer after receiving the iframe from VGS, and wait until you either get the asynchronous device fingerprinting response from VGS or the timer expires—-whichever happens first—-before sending the authenticate request to VGS.

  5. Call the 3ds-authenticate endpoint at the time of purchase. It may return the final authentication result synchronously, or it may trigger a user challenge-—in which case the final result will be delivered via the configured webhook notification.

hashtag
Initialize 3DS authentication

post
/cards/{card_id}/3ds-initialize

Initial call to check if device fingerprinting is needed for subsequent 3DS authentication.

chevron-right
lockRequired scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
card_idstringRequiredExample: CRDecqZp3xRgXU3TFmtcDdzQs
Header parameters
AuthorizationstringRequired

Bearer token for authentication.

Example: Bearer <JWT_TOKEN>
Content-Typestring · enumRequired

Content type of a request to CMP

Example: application/vnd.api+jsonPossible values:
Body

The request body to initiate 3DS authentication for a card.

Responses
chevron-right
200

Successful initialization

application/vnd.api+json

The response body for a successful 3DS initialization.

post
/cards/{card_id}/3ds-initialize

hashtag
Perform 3DS authentication

post
/cards/{card_id}/3ds-authenticate

Main call to perform authentication. Required for payment transactions.

How the 3DS Challenge Response Fields Are Used When a cardholder needs to complete a challenge during authentication there are two ways to handle the process:

  • Use the prebuilt HTML form (challenge_form): This form already contains all necessary elements, including the ACS URL, the CReq data, and the session data. You can return this form directly to the cardholder on your checkout page. It will display the correct UI, including the payment scheme logo and any loading spinners, and will automatically handle localization.

  • Build your own redirect form using individual fields: If you would prefer to generate your own HTML form for the challenge, include the following fields from the response: - challenge_url: The URL to which the cardholder should be redirected for the challenge - challenge_request: The CReq data that must be sent to the ACS, included as a hidden field in the form - challenge_session_data: Include this as a hidden field if provided. It allows you to track the session and link it back to the specific transaction when the cardholder returns from the ACS. After the cardholder completes the challenge, they will be redirected to your redirect_url, and you will receive the final challenge result along with the challenge_session_data so you can reconcile it with the transaction.

chevron-right
lockRequired scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
card_idstringRequiredExample: CRDecqZp3xRgXU3TFmtcDdzQs
Header parameters
AcceptstringRequired

Desired response media types.

Accept-LanguagestringRequired

Language preference (IETF BCP47).

AuthorizationstringRequired

Bearer token for authentication.

Example: Bearer <JWT_TOKEN>
Content-Typestring · enumRequired

Content type of a request to CMP

Example: application/vnd.api+jsonPossible values:
Body

The request body for 3ds authentication for a card.

Responses
chevron-right
200

Successful authentication

application/vnd.api+json

Successful Authentication: Authentication is considered successful if the response contains one of the following statuses:

  • APPROVED: Indicates a successful authentication. The response will include a cavv and an eci value (typically 05, 06, or 07).
  • INFORMATIONAL_ONLY: Indicates a successful data-only/frictionless authentication (specifically for Visa Data-Only flows). The response will include a cavv and an eci value of "07".
  • CHALLENGE_REQUIRED: Indicates that the authentication requires user interaction. The response will contain the necessary challenge details (either challenge_html or challenge_form, challenge_session_data, and challenge_url).

Failed Authentication: Authentication is considered failed if the response contains one of the following statuses:

  • DENIED
  • REJECTED
  • ATTEMPTS_PERFORMED
  • UNABLE_TO_AUTHENTICATE In failure cases, the specific reason for the failure will typically be provided in the message field of the response.
post
/cards/{card_id}/3ds-authenticate

hashtag
Perform 3DS Status Check

get
/cards/{card_id}/3ds-check

Check the 3DS authentication status of a card.

Endpoint to Check Initialize Device Fingerprint Status: GET /cards/{card_id}/3ds-check?init_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}

chevron-right
lockRequired scopes
This endpoint requires the following scopes:
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
card_idstringRequired

Unique identifier for the card being authenticated.

Example: CRDecqZp3xRgXU3TFmtcDdzQs
Query parameters
merchant_transaction_idstringRequired

Generated by the merchant. Must be a unique identifier assigned to each transaction.

Example: f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8
xidstring · min: 28 · max: 28Required

Generated by the merchant. Can be the same across a series of transactions for a single user or recurring payments. Must be a base64-encoded sequence of 20 bytes.

Example: E6Kdhoz49St6A2uhf//tZFeXq8Q=
init_receivedbooleanOptional

Boolean flag controlling which status is returned:

  • Required with initReceived=true if you want to retrieve device fingerprinting initialization status. Invoke /3ds-check 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.
  • initReceived=false or not provided: Returns authentication status after the challenge questionnaire/html is submitted by the user in the 3DS challenge flow.
Default: false
Header parameters
AuthorizationstringRequired

Bearer token for authentication.

Example: Bearer <JWT_TOKEN>
Responses
chevron-right
200

Successful check

application/vnd.api+json
get
/cards/{card_id}/3ds-check

hashtag
3DS Challenge Webhook

Webhook to receive challenge results.

Payload

The webhook sent after completion of a challenge

eventstringOptional

Payload

hashtag
3DS Initialize – Device Fingerprinting Webhook

Webhook to be notified of when device fingerprinting was completed.

Payload

The webhook body return when device fingerprinting completes.

Payload

PreviousNetwork Token EventsNextCard Management V1 APIs (CALM)

Last updated