3D Secure (3DS)
For a fully optimized 3DS flow:
Call the 3ds-initialize endpoint, which returns an iframe to collect device fingerprinting information.
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 when the purchase is made, which will synchronously return the authentication result.
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
Request successful, but initialization was not complete. Proceed with authentication request.
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": "2025-12-03T04:32:10.797Z",
"tds_method_content": "<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
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: 384
{
"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
}
}
}
}{
"data": {
"attributes": {
"card_id": "CRDecqZp3xRgXU3TFmtcDdzQs",
"created_at": "2025-09-26T15:30:45Z",
"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"
}
}
}
}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:45Z",
"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