3D Secure (3DS)
For a fully optimized 3DS flow:
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.
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.
Submit the form contained in the iframe, this will start the device fingerprinting process.
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.
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.
Initial call to check if device fingerprinting is needed for subsequent 3DS authentication.
CRDecqZp3xRgXU3TFmtcDdzQsBearer token for authentication.
Bearer <JWT_TOKEN>Content type of a request to CMP
application/vnd.api+jsonPossible values: The request body to initiate 3DS authentication for a card.
Successful initialization
The response body for a successful 3DS initialization.
Request successful. No iframe/data in the response means initialization isn’t needed, and authentication can continue immediately.
Invalid request
No credentials were provided, or the provided credentials were expired.
Valid credentials were provided, but they do not permit access to this resource.
Resource not found.
Unprocessable Entity. The request was well-formed but contained semantic errors.
An unexpected error occurred.
Service Unavailable
POST /cards/{card_id}/3ds-initialize HTTP/1.1
Host: sandbox.vgsapi.com
Authorization: text
Content-Type: application/vnd.api+json
Accept: */*
Content-Length: 167
{
"data": {
"attributes": {
"transaction_info": {
"xid": "E6Kdhoz49St6A2uhf//tZFeXq8Q=",
"merchant_transaction_id": "f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8"
},
"token_type": "pan"
}
}
}{
"data": {
"attributes": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"created_at": "2026-01-01T00:00:00.000Z",
"device_fingerprinting_html": "<iframe id='tdsMethodTgtFrame'...>...</iframe>",
"transaction_info": {
"xid": "E6Kdhoz49St6A2uhf//tZFeXq8Q=",
"merchant_transaction_id": "f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8",
"transaction_id": "41882051"
}
}
}
}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 yourredirect_url, and you will receive the final challenge result along with thechallenge_session_dataso you can reconcile it with the transaction.
CRDecqZp3xRgXU3TFmtcDdzQsDesired response media types.
Language preference (IETF BCP47).
Bearer token for authentication.
Bearer <JWT_TOKEN>Content type of a request to CMP
application/vnd.api+jsonPossible values: The request body for 3ds authentication for a card.
Successful authentication
Successful Authentication: Authentication is considered successful if the response contains one of the following statuses:
APPROVED: Indicates a successful authentication. The response will include acavvand anecivalue (typically 05, 06, or 07).- For Data-Only flows,
INFORMATIONAL_ONLYis returned forVisaand includes acavvwith anecivalue of "07", whileUNABLE_TO_AUTHENTICATE(unavailable for standard authentication) is returned forMastercardand includes acavvwith anecivalue of "04". CHALLENGE_REQUIRED: Indicates that the authentication requires user interaction. The response will contain the necessary challenge details (eitherchallenge_htmlorchallenge_form,challenge_session_data, andchallenge_url).
Failed Authentication: Authentication is considered failed if the response contains one of the following statuses:
DENIEDREJECTEDATTEMPTS_PERFORMEDUNABLE_TO_AUTHENTICATE(withoutcavv/eciin response): In failure cases, the specific reason for the failure will typically be provided in the message field of the response.
Invalid request
No credentials were provided, or the provided credentials were expired.
Forbidden. The client does not have permission to perform this action, or the vault context could not be determined from the request.
Resource not found.
Unprocessable Entity. The request was well-formed but contained semantic errors.
An unexpected error occurred.
Service Unavailable
POST /cards/{card_id}/3ds-authenticate HTTP/1.1
Host: sandbox.vgsapi.com
Authorization: text
Accept: text
Accept-Language: text
Content-Type: application/vnd.api+json
Content-Length: 666
{
"data": {
"attributes": {
"auth_type": "data-only",
"token_type": "pan",
"transaction_info": {
"xid": "E6Kdhoz49St6A2uhf//tZFeXq8Q=",
"merchant_transaction_id": "f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8"
},
"purchase_info": {
"currency_code": "USD",
"amount": 1002.25
},
"browser_info": {
"java_enabled": "false",
"javascript_enabled": "true",
"color_depth": 24,
"screen_height": 1080,
"screen_width": 1920,
"tz": -240
},
"merchant_info": {
"acquirer_bin": "444444",
"acquirer_requestor_id": "1000",
"acquirer_merchant_id": "1000",
"acquirer_country_code": "USA",
"acquirer_requestor_name": "CoffeeHouse",
"category_code": "4829",
"country_code": "CAN",
"name": "CoffeeHouse",
"website_url": "https://www.coffeehouse.com"
}
}
}
}{
"data": {
"attributes": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"created_at": "2025-09-26T15:30:45.123456Z",
"message": "Authentication successful",
"status": "APPROVED",
"acs_info": {
"acs_reference_number": "3DS_LOA_ACS_MOMD_020301_00793",
"acs_operator_id": "3DS_LOA_ACS_MOMD_020301_00793"
},
"cryptogram": {
"eci": 7,
"cavv": "A5EBA##################XBkY="
},
"transaction_info": {
"xid": "E6Kdhoz49St6A2uhf//tZFeXq8Q=",
"merchant_transaction_id": "f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8",
"transaction_id": 41882051,
"acs_transaction_id": "7786ae31-c7b5-4944-ae42-790b171873d2",
"ds_transaction_id": "ae434952-a73f-5099-8000-00000f3ee181",
"3ds_server_transaction_id": "38f0b42a-cdc8-5e2d-8000-0000027f11c3"
}
}
}
}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}
Unique identifier for the card being authenticated.
CRDecqZp3xRgXU3TFmtcDdzQsGenerated by the merchant. Must be a unique identifier assigned to each transaction.
f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8Generated 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.
E6Kdhoz49St6A2uhf//tZFeXq8Q=Boolean flag controlling which status is returned:
- Required with init_received=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.
- init_received=false or not provided: Returns authentication status after the challenge questionnaire/html is submitted by the user in the 3DS challenge flow.
falseBearer token for authentication.
Bearer <JWT_TOKEN>Successful check
The request was invalid.
No credentials were provided, or the provided credentials were expired.
Forbidden. The client does not have permission to perform this action, or the vault context could not be determined from the request.
Resource not found.
The server was unable to process the request because it contains invalid data.
An unexpected error occurred.
Service Unavailable. The downstream network is temporarily unavailable.
GET /cards/{card_id}/3ds-check?merchant_transaction_id=f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8&xid=E6Kdhoz49St6A2uhf%2F%2FtZFeXq8Q%3D HTTP/1.1
Host: sandbox.vgsapi.com
Authorization: text
Accept: */*
{
"data": {
"attributes": {
"details": {
"acs_operator_id": "3DS_LOA_ACS_MOMD_020301_00793",
"acs_reference_number": "3DS_LOA_ACS_MOMD_020301_00793",
"acs_transaction_id": "3f2fe7ae-0462-4149-a7df-0f8ad414358a",
"card_id": "CRDgUv34xTdhXvtvBeUe7mScj",
"created_at": "2026-01-28T16:20:40.734045112Z",
"ds_transaction_id": "463f2a0d-0425-5d8e-8000-00000fdcdebd",
"init_received": false,
"merchant_transaction_id": "tx-1769617232240",
"message": "Y-status/Challenge authentication via ACS: https://3ds-acs.test.modirum.com/mdpayacs/creq;token=366155411.1769617019.eKl2fWZYG5QVdkNy1kZ2p_v-y2PftD_PySeogkhXnNU",
"status": "APPROVED",
"tx_id": "45044861",
"xid": "UgG20AB6E6dceR1gDg8I8VtxoHk=",
"3ds_server_transaction_id": "cfb8c2e7-f57c-59b8-8000-000002af547d"
},
"event": "cmp_threeds.challenge_result",
"timestamp": "2026-01-28T16:20:40.734045112"
}
}
}Webhook to receive challenge results.
The webhook sent after completion of a challenge
Payload
{
"details": {
"acs_operator_id": "3DS_LOA_ACS_MOMD_020301_00793",
"acs_reference_number": "3DS_LOA_ACS_MOMD_020301_00793",
"acs_trans_id": "7786ae31-c7b5-4944-ae42-790b171873d2",
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"cavv": "A5EBA##################XBkY=",
"created_at": "2025-09-26T15:30:45.123456Z",
"ds_trans_id": "ae434952-a73f-5099-8000-00000f3ee181",
"eci": "07",
"merchant_tx_id": "f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8",
"message": "Y-status/Challenge authentication via ACS: https://3ds-acs.test.modirum.com/mdpayacs/creq;token=347554871.1746163021.QErHUhpJqYN",
"status": "APPROVED",
"tds_server_trans_id": "38f0b42a-cdc8-5e2d-8000-0000027f11c3",
"tx_id": "41882051",
"xid": "E6Kdhoz49St6A2uhf//tZFeXq8Q="
},
"event": "cmp_threeds.challenge_result",
"fingerprint": "758d558a91cc8f467a03b4493461361fc9750cf812168bd93ec30006db6d71e6",
"grouping": "every_single",
"id": "d4f5e8b1-3c4a-4e2b-9f4a-2e5d6c7b8a9b",
"integration_id": "INdNzxhJUz6afZvmKNwY8XRd",
"occurrence": 1,
"org_id": "ACj9SFZWEnwhUfi6bm2xRtDb",
"producer": {
"application_name": "cmp-3ds-grpc",
"application_protocol": "http"
},
"scope": "vault",
"summary": "A 3DS challenge result for card \"CRDecqZp3xRgXU3TFmtcDdzQs\" has been recorded in tenant tnt123",
"tenant": "tnt123",
"timestamp": "2025-09-26T15:30:45Z"
}Webhook to be notified of when device fingerprinting was completed.
The webhook body return when device fingerprinting completes.
Payload
{
"description": "3DS Device Fingerprint",
"details": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"merchant_transaction_id": "f1ec2b0b-bf68-4f2e-9ad5-a60fd04ebdf8",
"success": "true",
"transaction_id": "41882051",
"xid": "E6Kdhoz49St6A2uhf//tZFeXq8Q="
},
"event": "cmp_threeds.device_fingerprint",
"fingerprint": "b569afde707004040ce43752fde5d9896c9b8a311efefd2af53599bcf7a4ced4",
"grouping": "every_single",
"id": "b25ce6c8-3a70-451f-bb43-998e43e93bf4",
"integration_id": "IN5ZYviUefdrJrz8SjfywaDR",
"occurrence": 1,
"org_id": "ACbpeU1JkViuNKH5YGQaLFhU",
"producer": {
"application_name": "cmp-3ds-grpc",
"application_protocol": "http"
},
"scope": "vault",
"summary": "Device fingerprint for card id CRDhVGXaWBxcsRvbtn5vcCere in tenant tntydlndyqe, response was true",
"tenant": "tntydlndyqe",
"timestamp": "2025-11-26T21:26:55.179Z"
}Last updated