# 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.
## Initialize 3DS authentication
> Initial call to check if device fingerprinting is needed for subsequent\
> 3DS authentication.
```json
{"openapi":"3.1.0","info":{"title":"VGS Card Management Platform (CMP) API","version":"doc version 2.2.9 | API version 1.0.0"},"tags":[{"name":"3D Secure (3DS)","description":"For a fully optimized 3DS flow:\n1. 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.\n2. 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.\n3. Submit the form contained in the iframe, this will start the device fingerprinting process.\n4. 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.\n5. 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.\n"}],"servers":[{"url":"https://sandbox.vgsapi.com","description":"Sandbox environment server used for integration and testing. Uses network sandboxes in addition to mocked data sources.\n"},{"url":"https://vgsapi.com","description":"Live environment server used for production workloads.\n"}],"security":[{"bearerAuth":["3ds:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"auth-header":{"in":"header","name":"Authorization","description":"Bearer token for authentication.","schema":{"type":"string"},"required":true},"content-type":{"in":"header","name":"Content-Type","description":"Content type of a request to CMP","schema":{"type":"string","enum":["application/vnd.api+json"]},"required":true}},"schemas":{"ThreeDSInitializeRequest":{"type":"object","description":"The request body to initiate 3DS authentication for a card.","required":["data"],"properties":{"data":{"type":"object","properties":{"attributes":{"type":"object","required":["transaction_info"],"properties":{"transaction_info":{"type":"object","description":"Transaction information.","$ref":"#/components/schemas/TransactionInfoType"},"token_type":{"type":"string","description":"The type of token used. Defaults to PAN if not provided or if a network token isn’t available for the card.","default":"pan","enum":["pan","nt"]}}}}}}},"TransactionInfoType":{"type":"object","description":"Transaction Information for 3DS authentication requests","required":["xid","merchant_tx_id"],"properties":{"xid":{"type":"string","minLength":28,"maxLength":28,"description":"Unique transaction reference. It 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."},"merchant_transaction_id":{"type":"string","minLength":1,"maxLength":40,"description":"The merchant_transaction_id is a unique identifier (UUID) assigned to each transaction. Its primary relevance becomes clear in scenarios involving 3RI (Merchant-Initiated Transactions), where merchants need to reference a previously successful transaction using identifiers such as acs_transaction_id and ds_transaction_id. In such cases, while the XID may remain the same across the initial and subsequent 3RI transactions, the merchant_transaction_id must be unique for each transaction.\nFor CIT (Customer-Initiated Transactions), both the XID and merchant_transaction_id can either be the same or different UUIDs — both approaches are acceptable."}}},"ThreeDSInitializeResponse":{"type":"object","description":"The response body for a successful 3DS initialization.","properties":{"data":{"type":"object","properties":{"attributes":{"type":"object","properties":{"card_id":{"type":"string","description":"Unique VGS identifier for the card"},"created_at":{"type":"string","format":"date-time"},"device_fingerprinting_html":{"type":"string","description":"An iframe which will perform device fingerprinting. This HTML content should be added to the front-end as soon as the content is received in the response from VGS. The iframe can be loaded as an invisible/background frame on the client side checkout page before the purchase is submitted so that the client doesn't have to wait for processing."},"transaction_info":{"type":"object","description":"Transaction information.","$ref":"#/components/schemas/TransactionInfoResponseType"}}}}}}},"TransactionInfoResponseType":{"type":"object","description":"Transaction Information for 3DS authentication requests","properties":{"xid":{"type":"string","description":"Unique transaction reference used across a series of transactions, copied from the request."},"merchant_transaction_id":{"type":"string","description":"The merchant_transaction_id is a unique identifier (UUID) assigned to each transaction. Its primary relevance becomes clear in scenarios involving 3RI (Merchant-Initiated Transactions), where merchants need to reference a previously successful transaction using identifiers such as acs_transaction_id and ds_transaction_id. In such cases, while the XID may remain the same across the initial and subsequent 3RI transactions, the merchant_transaction_id must be unique for each transaction.\nFor CIT (Customer-Initiated Transactions), both the XID and merchant_transaction_id can either be the same or different UUIDs — both approaches are acceptable."},"transaction_id":{"type":"string","description":"A 3DSS/MPI generated ID against each unique authentication transaction"}}},"ThreeDSErrorResponse":{"type":"object","description":"The response body for a failed 3DS request.","properties":{"data":{"type":"object","properties":{"message":{"type":"string","description":"Error received from upstream."},"card_id":{"type":"string","description":"Unique VGS identifier for the card"},"transaction_info":{"type":"object","description":"Transaction information.","$ref":"#/components/schemas/TransactionInfoType"}}},"meta":{"type":"object","title":"Meta","properties":{"observability":{"type":"object","properties":{"trace_id":{"type":"string"},"client_id":{"type":"string"},"vault_id":{"type":"string"},"account_id":{"type":"string"},"fingerprint":{"type":"string"}}}}}}},"ErrorResponse":{"properties":{"errors":{"items":{"properties":{"path":{"type":"string","title":"Path"},"summary":{"type":"string","title":"Summary"},"detail":{"type":"string","title":"Detail"},"error_code":{"type":"string","title":"Error Code"},"fingerprint":{"type":"string","title":"string"}},"type":"object","title":"Error"},"type":"array","title":"Errors","description":"A list of errors","required":["summary","detail","error_code"]},"meta":{"anyOf":[{"type":"object"}],"title":"Meta"},"links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}]},"type":"object"}],"title":"Links"},"included":{"anyOf":[{"items":{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"attributes":{"anyOf":[{"properties":{},"additionalProperties":true,"type":"object","title":"LubeAttributes","description":"Members of the LubeAttributes object (\"attributes\") represent information about the resource object in which it's defined.\n\n\nThe keys for Attributes MUST NOT be:\n\n\n relationships\n links\n id\n type\n"},{"type":"null"}]},"relationships":{"anyOf":[{"additionalProperties":{"properties":{"links":{"anyOf":[{"properties":{"self":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}],"title":"relationship link"},"related":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}],"title":"related resource link"}},"type":"object","title":"LubeRelationLink"},{"type":"null"}]},"data":{"anyOf":[{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"meta":{"type":"object","title":"meta"},"lid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lid"}},"type":"object","required":["id","type"],"title":"LubeResourceId","description":"JSON:API Resource Identifier"},{"items":{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"meta":{"type":"object","title":"meta"},"lid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lid"}},"type":"object","required":["id","type"],"title":"LubeResourceId","description":"JSON:API Resource Identifier"},"type":"array"},{"type":"null"}],"title":"Data"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Meta"}},"type":"object","title":"LubeRel","description":"JSON:API Relationship"},"type":"object"},{"type":"null"}],"title":"Relationships"},"links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Links"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Meta"}},"type":"object","required":["id","type"],"title":"LubeResource","description":"A single resource. The only JSON:API required field is type"},"type":"array"}],"title":"Included"},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"type":"object","title":"ErrorResponse"},"JsonApiVersion":{"properties":{"version":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Version","default":1.1},"ext":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Ext"}]},"profile":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Profile"}]},"meta":{"type":"object","title":"Meta"}},"title":"JsonApi"},"ErrorForbiddenResponse":{"properties":{"errors":{"items":{"properties":{"status":{"type":"integer","title":"Status"},"details":{"type":"string","title":"Details"},"title":{"type":"string","title":"Title"}},"type":"object","title":"Error"},"type":"array","title":"Errors","description":"A list of errors"},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"type":"object","title":"ErrorForbiddenResponse"}}},"paths":{"/cards/{card_id}/3ds-initialize":{"post":{"tags":["3D Secure (3DS)"],"summary":"Initialize 3DS authentication","description":"Initial call to check if device fingerprinting is needed for subsequent\n3DS authentication.\n","operationId":"threeds-initialize","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card ID"}},{"$ref":"#/components/parameters/auth-header"},{"$ref":"#/components/parameters/content-type"}],"requestBody":{"description":"3DS initialize request payload","required":true,"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeRequest"}}}},"responses":{"200":{"description":"Successful initialization","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeResponse"}}}},"206":{"description":"Request successful. No iframe/data in the response means initialization isn’t needed, and authentication can continue immediately.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSInitializeResponse"}}}},"400":{"description":"Invalid request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSErrorResponse"}}}},"401":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No credentials were provided, or the provided credentials were expired."},"403":{"content":{"application/vnd.api+json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/ErrorResponse"},{"$ref":"#/components/schemas/ErrorForbiddenResponse"}]}}},"description":"Valid credentials were provided, but they do not permit access to this resource."},"404":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found."},"422":{"description":"Unprocessable Entity. The request was well-formed but contained semantic errors.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSErrorResponse"}}}},"500":{"description":"An unexpected error occurred.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSErrorResponse"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Perform 3DS authentication
> 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.
```json
{"openapi":"3.1.0","info":{"title":"VGS Card Management Platform (CMP) API","version":"doc version 2.2.9 | API version 1.0.0"},"tags":[{"name":"3D Secure (3DS)","description":"For a fully optimized 3DS flow:\n1. 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.\n2. 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.\n3. Submit the form contained in the iframe, this will start the device fingerprinting process.\n4. 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.\n5. 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.\n"}],"servers":[{"url":"https://sandbox.vgsapi.com","description":"Sandbox environment server used for integration and testing. Uses network sandboxes in addition to mocked data sources.\n"},{"url":"https://vgsapi.com","description":"Live environment server used for production workloads.\n"}],"security":[{"bearerAuth":["3ds:write"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"accept-header":{"in":"header","name":"Accept","description":"Desired response media types.","required":true,"schema":{"type":"string"}},"accept-language-header":{"in":"header","name":"Accept-Language","description":"Language preference (IETF BCP47).","required":true,"schema":{"type":"string"}},"auth-header":{"in":"header","name":"Authorization","description":"Bearer token for authentication.","schema":{"type":"string"},"required":true},"content-type":{"in":"header","name":"Content-Type","description":"Content type of a request to CMP","schema":{"type":"string","enum":["application/vnd.api+json"]},"required":true}},"schemas":{"ThreeDSAuthenticateRequest":{"type":"object","description":"The request body for 3ds authentication for a card.","required":["data"],"properties":{"data":{"type":"object","properties":{"attributes":{"type":"object","required":["auth_type","purchase_info","transaction_info"],"properties":{"token_type":{"type":"string","description":"The type of token used. Defaults to PAN if not provided or if a network token isn’t available for the card.","default":"pan","enum":["pan","nt"]},"auth_type":{"type":"string","description":"The type of 3DS flow requested.","enum":["data-only","challenge"]},"redirect_url":{"type":"string","description":"The URL to redirect the user to once the challenge is completed. **Required** only for challenge flow."},"transaction_info":{"type":"object","description":"Transaction information.","$ref":"#/components/schemas/TransactionInfoType"},"purchase_info":{"type":"object","description":"Purchase information.","$ref":"#/components/schemas/PurchaseInfoType"},"browser_info":{"type":"object","description":"Browser information.","$ref":"#/components/schemas/BrowserInfoType"},"merchant_info":{"type":"object","description":"Merchant information.","$ref":"#/components/schemas/MerchantInfoType"}}}}}}},"TransactionInfoType":{"type":"object","description":"Transaction Information for 3DS authentication requests","required":["xid","merchant_tx_id"],"properties":{"xid":{"type":"string","minLength":28,"maxLength":28,"description":"Unique transaction reference. It 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."},"merchant_transaction_id":{"type":"string","minLength":1,"maxLength":40,"description":"The merchant_transaction_id is a unique identifier (UUID) assigned to each transaction. Its primary relevance becomes clear in scenarios involving 3RI (Merchant-Initiated Transactions), where merchants need to reference a previously successful transaction using identifiers such as acs_transaction_id and ds_transaction_id. In such cases, while the XID may remain the same across the initial and subsequent 3RI transactions, the merchant_transaction_id must be unique for each transaction.\nFor CIT (Customer-Initiated Transactions), both the XID and merchant_transaction_id can either be the same or different UUIDs — both approaches are acceptable."}}},"PurchaseInfoType":{"type":"object","description":"Details about the transaction.","required":["purchase_currency","purchase_amount"],"properties":{"currency_code":{"type":"string","description":"ISO 4217 alpha 3 currency code for the transaction"},"amount":{"type":"number","multipleOf":0.01,"format":"double","description":"Transaction amount"}}},"BrowserInfoType":{"type":"object","description":"Device and browser information. These fields are required for browser-based requests.","required":["java_enabled","javascript_enabled","color_depth","screen_width","screen_height","tz"],"properties":{"java_enabled":{"type":"string","description":"Flag indicating whether the browser has java enabled, must be strings \"true\" or \"false\""},"javascript_enabled":{"type":"string","description":"Flag indicating whether the browser has javascript enabled must be strings \"true\" or \"false\""},"color_depth":{"type":"integer","description":"Bit depth of screen color palette"},"screen_width":{"type":"integer","description":"Screen width in pixels"},"screen_height":{"type":"integer","description":"Screen height in pixels"},"tz":{"type":"integer","description":"Time zone offset in minutes"}}},"MerchantInfoType":{"type":"object","description":"Merchant info for PSP mode auth request","required":["acquirer_bin","acquirer_country_code","acquirer_merchant_id","name","category_code","country_code","website_url"],"properties":{"acquirer_bin":{"type":"string","description":"Acquiring institution identification code (BIN). Numeric, length 1-11. Overrides default profile if present.","minLength":1,"maxLength":11},"acquirer_country_code":{"type":"string","description":"The code of the country where the acquiring institution is located (in accordance with ISO 3166-1 alpha 3-letter country code).","minLength":3,"maxLength":3},"acquirer_requestor_name":{"type":"string","description":"Name of the 3DS Requestor (Merchant). Length 1-40 characters. Required for AMEX/Discover requests.","minLength":1,"maxLength":40},"acquirer_requestor_id":{"type":"string","description":"Unique identifier assigned to the 3DS Requestor by the DS or Scheme. Length 1-35 characters. Required for AMEX/Discover requests.","minLength":1,"maxLength":35},"acquirer_merchant_id":{"type":"string","description":"Acquirer-assigned Merchant Identifier. Length 1-35 characters. Overrides default profile if present.","minLength":1,"maxLength":35},"name":{"type":"string","description":"Merchant Name to be displayed to the cardholder. Length 1-40 characters. Overrides default profile if present.","minLength":1,"maxLength":40},"category_code":{"type":"string","description":"Merchant Category Code (MCC). 4-digit numeric. Overrides default profile if present.","minLength":4,"maxLength":4},"country_code":{"type":"string","description":"Merchant Country Code. ISO 3166-1 alpha 3-letter code. Overrides default profile if present.","minLength":3,"maxLength":3},"website_url":{"type":"string","format":"uri","description":"Fully qualified URL of the 3DS Requestor website or customer care site. Max 2048 characters."}}},"ThreeDSAuthenticateResponse":{"type":"object","description":"*Successful Authentication*: Authentication is considered successful if the response contains one of the following statuses:\n- `APPROVED`: Indicates a successful authentication. The response will include a `cavv` and an `eci` value (typically 05, 06, or 07).\n- For Data-Only flows, `INFORMATIONAL_ONLY` is returned for `Visa` and includes a `cavv` with an `eci` value of \"07\", while `UNABLE_TO_AUTHENTICATE` (unavailable for standard authentication) is returned for `Mastercard` and includes a `cavv` with an `eci` value of \"04\".\n- `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`).\n\n*Failed Authentication*: Authentication is considered failed if the response contains one of the following statuses:\n- `DENIED`\n- `REJECTED`\n- `ATTEMPTS_PERFORMED`\n- `UNABLE_TO_AUTHENTICATE` (without `cavv`/`eci` in response):\nIn failure cases, the specific reason for the failure will typically be provided in the message field of the response.\n","properties":{"data":{"type":"object","properties":{"attributes":{"type":"object","properties":{"card_id":{"type":"string","description":"Unique VGS identifier for the card"},"created_at":{"type":"string","format":"date-time"},"message":{"type":"string","description":"Human readable description of the response\nVisa:\n- Success: \"Informational response only\"\n- Failure: A message such as \"Authentication Failed\" or an iReqDetail containing \"Visa DAF program not supported by the ACS\"\nMastercard:\n - Success: A message indicating the outcome of the frictionless response is returned\n - Failure: \"Authentication Failed\"\nAmex/Discover:\n - Success: A message indicating an authenticated transaction.\n - Failure: \"Authentication Failed\"\n"},"status":{"type":"string","description":"The EMV 3DS result code\n- APPROVED\n - Code: Y\n - Authentication Successful\n- DENIED\n - Code: N\n - Authentication Failed - DAF unsupported\n- UNABLE_TO_AUTHENTICATE\n - Code: U\n - Unable to Authenticate\n - Data Only Transactions (e.g., Mastercard messageCategory=80) → DS does not pass AReq data to the ACS, hence returns transStatus=U.\n - Card Range Not Updated → If the PAN is not part of the DS’s range, the DS may respond with transStatus=U.\n - Other Component Non-Communication → If any 3DS component (e.g., DS, ACS) doesn’t communicate with the next in chain, the result may be transStatus=U.\n- ATTEMPTS_PERFORMED\n - Code: A\n - Attempts Processing Only - Issuer fallback - Not commonly used\n- REJECTED\n - Code: R\n - Authentication Rejected - Rejected by ACS\n- INFORMATIONAL_ONLY\n Code: I\n Information-Only\n- CHALLENGE_REQUIRED\n - Code: C\n - Challenge Required - Step-up Challenge\n","enum":["APPROVED","DENIED","UNABLE_TO_AUTHENTICATE","ATTEMPTS_PERFORMED","REJECTED","INFORMATIONAL_ONLY","CHALLENGE_REQUIRED"]},"acs_info":{"type":"object","description":"Access Control Server (ACS) information. The auth response may sometimes return an empty acs_info field.","$ref":"#/components/schemas/ACSInfoType"},"cryptogram":{"type":"object","description":"Cryptogram information","$ref":"#/components/schemas/CryptogramType"},"transaction_info":{"type":"object","description":"Transaction information","$ref":"#/components/schemas/TransactionFullInfoResponseType"},"challenge_info":{"type":"object","description":"Challenge information","$ref":"#/components/schemas/ChallengeInfoType"}}}}}}},"ACSInfoType":{"type":"object","description":"Information about the Access Control Server (ACS).","properties":{"acs_reference_number":{"type":"string","description":"A reference number from the ACS for the transaction"},"acs_operator_id":{"type":"string","description":"Unique ACS identifies that is provided by payment scheme for the operator of the service."}}},"CryptogramType":{"type":"object","description":"Cryptogram information","properties":{"eci":{"type":"string","description":"An Electronic Commerce Indicator (ECI) is a code that indicates the type of electronic transaction and the result of authentication for a payment."},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value. Present on successful authentications and must be sent in the authorization."}}},"TransactionFullInfoResponseType":{"type":"object","description":"Transaction Information for 3DS authentication requests","properties":{"xid":{"type":"string","description":"Unique transaction reference used across a series of transactions, copied from the request."},"merchant_transaction_id":{"type":"string","description":"The merchant_transaction_id is a unique identifier (UUID) assigned to each transaction. Its primary relevance becomes clear in scenarios involving 3RI (Merchant-Initiated Transactions), where merchants need to reference a previously successful transaction using identifiers such as acs_transaction_id and ds_transaction_id. In such cases, while the XID may remain the same across the initial and subsequent 3RI transactions, the merchant_transaction_id must be unique for each transaction.\nFor CIT (Customer-Initiated Transactions), both the XID and merchant_transaction_id can either be the same or different UUIDs — both approaches are acceptable."},"transaction_id":{"type":"string","description":"A 3DSS/MPI generated ID against each unique authentication transaction"},"acs_transaction_id":{"type":"string","description":"The transaction ID generated by the Access Control Server (ACS)"},"ds_transaction_id":{"type":"string","description":"The transaction ID generated by the Directory Server"},"3ds_server_transaction_id":{"type":"string","description":"The transaction ID generated by the 3DS Server"}}},"ChallengeInfoType":{"type":"object","description":"Information about the challenge.","properties":{"challenge_req":{"type":"string","description":"The base64-encoded challenge request (CReq) that must be sent to the ACS."},"challenge_url":{"type":"string","description":"The URL of the ACS where the challenge will be sent."},"challenge_session_data":{"type":"string","description":"The base64-encoded session data that must be sent to the ACS for the challenge."},"challenge_form":{"type":"string","description":"An HTML form that can be directly rendered in the browser to initiate the challenge."}}},"ThreeDSErrorResponse":{"type":"object","description":"The response body for a failed 3DS request.","properties":{"data":{"type":"object","properties":{"message":{"type":"string","description":"Error received from upstream."},"card_id":{"type":"string","description":"Unique VGS identifier for the card"},"transaction_info":{"type":"object","description":"Transaction information.","$ref":"#/components/schemas/TransactionInfoType"}}},"meta":{"type":"object","title":"Meta","properties":{"observability":{"type":"object","properties":{"trace_id":{"type":"string"},"client_id":{"type":"string"},"vault_id":{"type":"string"},"account_id":{"type":"string"},"fingerprint":{"type":"string"}}}}}}},"ErrorResponse":{"properties":{"errors":{"items":{"properties":{"path":{"type":"string","title":"Path"},"summary":{"type":"string","title":"Summary"},"detail":{"type":"string","title":"Detail"},"error_code":{"type":"string","title":"Error Code"},"fingerprint":{"type":"string","title":"string"}},"type":"object","title":"Error"},"type":"array","title":"Errors","description":"A list of errors","required":["summary","detail","error_code"]},"meta":{"anyOf":[{"type":"object"}],"title":"Meta"},"links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}]},"type":"object"}],"title":"Links"},"included":{"anyOf":[{"items":{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"attributes":{"anyOf":[{"properties":{},"additionalProperties":true,"type":"object","title":"LubeAttributes","description":"Members of the LubeAttributes object (\"attributes\") represent information about the resource object in which it's defined.\n\n\nThe keys for Attributes MUST NOT be:\n\n\n relationships\n links\n id\n type\n"},{"type":"null"}]},"relationships":{"anyOf":[{"additionalProperties":{"properties":{"links":{"anyOf":[{"properties":{"self":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}],"title":"relationship link"},"related":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}],"title":"related resource link"}},"type":"object","title":"LubeRelationLink"},{"type":"null"}]},"data":{"anyOf":[{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"meta":{"type":"object","title":"meta"},"lid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lid"}},"type":"object","required":["id","type"],"title":"LubeResourceId","description":"JSON:API Resource Identifier"},{"items":{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"meta":{"type":"object","title":"meta"},"lid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lid"}},"type":"object","required":["id","type"],"title":"LubeResourceId","description":"JSON:API Resource Identifier"},"type":"array"},{"type":"null"}],"title":"Data"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Meta"}},"type":"object","title":"LubeRel","description":"JSON:API Relationship"},"type":"object"},{"type":"null"}],"title":"Relationships"},"links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Links"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Meta"}},"type":"object","required":["id","type"],"title":"LubeResource","description":"A single resource. The only JSON:API required field is type"},"type":"array"}],"title":"Included"},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"type":"object","title":"ErrorResponse"},"JsonApiVersion":{"properties":{"version":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Version","default":1.1},"ext":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Ext"}]},"profile":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Profile"}]},"meta":{"type":"object","title":"Meta"}},"title":"JsonApi"}}},"paths":{"/cards/{card_id}/3ds-authenticate":{"post":{"tags":["3D Secure (3DS)"],"summary":"Perform 3DS authentication","description":"Main call to perform authentication. Required for payment transactions.\n\nHow the 3DS Challenge Response Fields Are Used\nWhen a cardholder needs to complete a challenge during authentication there are two ways to handle the process:\n- *Use the prebuilt HTML form* (`challenge_form`):\n This form already contains all necessary elements, including the ACS URL, the CReq data, and the session data.\n You can return this form directly to the cardholder on your checkout page.\n It will display the correct UI, including the payment scheme logo and any loading spinners,\n and will automatically handle localization.\n- *Build your own redirect form using individual fields*:\n If you would prefer to generate your own HTML form for the challenge, include the following fields from the response:\n - `challenge_url`: The URL to which the cardholder should be redirected for the challenge\n - `challenge_request`: The CReq data that must be sent to the ACS, included as a hidden field in the form\n - `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.\nAfter the cardholder completes the challenge, they will be redirected to your `redirect_url`,\nand you will receive the final challenge result along with the `challenge_session_data` so you can reconcile it with the transaction.\n","operationId":"threeds-authenticate","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card ID"}},{"$ref":"#/components/parameters/accept-header"},{"$ref":"#/components/parameters/accept-language-header"},{"$ref":"#/components/parameters/auth-header"},{"$ref":"#/components/parameters/content-type"}],"requestBody":{"description":"3DS authenticate request payload","required":true,"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSAuthenticateRequest"}}}},"responses":{"200":{"description":"Successful authentication","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSAuthenticateResponse"}}}},"400":{"description":"Invalid request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSErrorResponse"}}}},"401":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No credentials were provided, or the provided credentials were expired."},"403":{"description":"Forbidden. The client does not have permission to perform this action, or the vault context could not be determined from the request.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found."},"422":{"description":"Unprocessable Entity. The request was well-formed but contained semantic errors.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSErrorResponse"}}}},"500":{"description":"An unexpected error occurred.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSErrorResponse"}}}},"503":{"description":"Service Unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Perform 3DS Status 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}\`
```json
{"openapi":"3.1.0","info":{"title":"VGS Card Management Platform (CMP) API","version":"doc version 2.2.9 | API version 1.0.0"},"tags":[{"name":"3D Secure (3DS)","description":"For a fully optimized 3DS flow:\n1. 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.\n2. 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.\n3. Submit the form contained in the iframe, this will start the device fingerprinting process.\n4. 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.\n5. 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.\n"}],"servers":[{"url":"https://sandbox.vgsapi.com","description":"Sandbox environment server used for integration and testing. Uses network sandboxes in addition to mocked data sources.\n"},{"url":"https://vgsapi.com","description":"Live environment server used for production workloads.\n"}],"security":[{"bearerAuth":["3ds:read"]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"auth-header":{"in":"header","name":"Authorization","description":"Bearer token for authentication.","schema":{"type":"string"},"required":true}},"schemas":{"ThreeDSCheckResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"attributes":{"type":"object","properties":{"details":{"$ref":"#/components/schemas/ThreeDSCheckDetails"},"event":{"type":"string","description":"The type of event that occurred."},"org_id":{"type":"string"},"tenant":{"type":"string"},"timestamp":{"type":"string","format":"date-time","description":"ISO 8601 timestamp of when the event occurred."}}}}}}},"ThreeDSCheckDetails":{"type":"object","properties":{"acs_operator_id":{"type":"string","description":"Unique identifier of the ACS operator assigned by the card scheme (e.g., Visa/Mastercard)."},"acs_reference_number":{"type":"string","description":"ACS reference number identifying the ACS product/version certified with the Directory Server."},"acs_transaction_id":{"type":"string","format":"uuid","description":"ACS transaction ID (`acsTransID`) for this EMV 3DS transaction."},"card_id":{"type":"string"},"cavv":{"type":"string","description":"Cardholder Authentication Verification Value produced by EMV 3DS; base64-encoded. Include in payment authorization. Also known as AEVV/UCAF for some networks."},"created_at":{"type":"string","format":"date-time","description":"ISO 8601 timestamp when CMP recorded the 3DS challenge result."},"ds_transaction_id":{"type":"string","format":"uuid","description":"Directory Server transaction ID (`dsTransID`)."},"eci":{"type":"string","description":"Electronic Commerce Indicator returned by the scheme (e.g., 05/06/07) and used during authorization."},"init_received":{"type":"boolean","description":"Indicates if the 3DS initialization callback was received for this transaction and webhook sent."},"merchant_transaction_id":{"type":"string","description":"Merchant-supplied transaction identifier used to correlate initialize/authenticate/check calls."},"message":{"type":"string","description":"Human-readable status or instructions from the ACS/3DS Server (e.g., challenge URL or outcome note)."},"status":{"type":"string","enum":["APPROVED","UNABLE_TO_AUTHENTICATE","DENIED","REJECTED","ATTEMPTS_PERFORMED"],"description":"Mapped EMV 3DS authentication outcome for this transaction."},"3ds_server_transaction_id":{"type":"string","format":"uuid","description":"3DS Server transaction ID (`threeDSServerTransID`)."},"tx_id":{"type":"string","description":"Provider transaction identifier used for internal tracking by the 3DS gateway/vendor."},"xid":{"type":"string","description":"Transaction reference (`XID`); base64-encoded (28 chars). Used by some schemes for correlation."}}},"ErrorResponse":{"properties":{"errors":{"items":{"properties":{"path":{"type":"string","title":"Path"},"summary":{"type":"string","title":"Summary"},"detail":{"type":"string","title":"Detail"},"error_code":{"type":"string","title":"Error Code"},"fingerprint":{"type":"string","title":"string"}},"type":"object","title":"Error"},"type":"array","title":"Errors","description":"A list of errors","required":["summary","detail","error_code"]},"meta":{"anyOf":[{"type":"object"}],"title":"Meta"},"links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}]},"type":"object"}],"title":"Links"},"included":{"anyOf":[{"items":{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"attributes":{"anyOf":[{"properties":{},"additionalProperties":true,"type":"object","title":"LubeAttributes","description":"Members of the LubeAttributes object (\"attributes\") represent information about the resource object in which it's defined.\n\n\nThe keys for Attributes MUST NOT be:\n\n\n relationships\n links\n id\n type\n"},{"type":"null"}]},"relationships":{"anyOf":[{"additionalProperties":{"properties":{"links":{"anyOf":[{"properties":{"self":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}],"title":"relationship link"},"related":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"null"}],"title":"related resource link"}},"type":"object","title":"LubeRelationLink"},{"type":"null"}]},"data":{"anyOf":[{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"meta":{"type":"object","title":"meta"},"lid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lid"}},"type":"object","required":["id","type"],"title":"LubeResourceId","description":"JSON:API Resource Identifier"},{"items":{"properties":{"id":{"type":"string","title":"id","description":"Resource ID"},"type":{"type":"string","title":"type","description":"Resource type"},"meta":{"type":"object","title":"meta"},"lid":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Lid"}},"type":"object","required":["id","type"],"title":"LubeResourceId","description":"JSON:API Resource Identifier"},"type":"array"},{"type":"null"}],"title":"Data"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Meta"}},"type":"object","title":"LubeRel","description":"JSON:API Relationship"},"type":"object"},{"type":"null"}],"title":"Relationships"},"links":{"anyOf":[{"additionalProperties":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"properties":{"href":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"href"},"rel":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link relation type"},"describedby":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link to a description of the link relation type\n"},"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link title"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"link media type"},"hreflang":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"link language"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"meta"}},"type":"object","title":"LubeLink","description":"JSON:API Link"},{"type":"string"},{"type":"null"}]},"type":"object"},{"type":"null"}],"title":"Links"},"meta":{"anyOf":[{"type":"object"},{"type":"null"}],"title":"Meta"}},"type":"object","required":["id","type"],"title":"LubeResource","description":"A single resource. The only JSON:API required field is type"},"type":"array"}],"title":"Included"},"jsonapi":{"$ref":"#/components/schemas/JsonApiVersion"}},"type":"object","title":"ErrorResponse"},"JsonApiVersion":{"properties":{"version":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Version","default":1.1},"ext":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Ext"}]},"profile":{"anyOf":[{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array"},{"type":"null","title":"Profile"}]},"meta":{"type":"object","title":"Meta"}},"title":"JsonApi"},"ThreeDSErrorResponse":{"type":"object","description":"The response body for a failed 3DS request.","properties":{"data":{"type":"object","properties":{"message":{"type":"string","description":"Error received from upstream."},"card_id":{"type":"string","description":"Unique VGS identifier for the card"},"transaction_info":{"type":"object","description":"Transaction information.","$ref":"#/components/schemas/TransactionInfoType"}}},"meta":{"type":"object","title":"Meta","properties":{"observability":{"type":"object","properties":{"trace_id":{"type":"string"},"client_id":{"type":"string"},"vault_id":{"type":"string"},"account_id":{"type":"string"},"fingerprint":{"type":"string"}}}}}}},"TransactionInfoType":{"type":"object","description":"Transaction Information for 3DS authentication requests","required":["xid","merchant_tx_id"],"properties":{"xid":{"type":"string","minLength":28,"maxLength":28,"description":"Unique transaction reference. It 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."},"merchant_transaction_id":{"type":"string","minLength":1,"maxLength":40,"description":"The merchant_transaction_id is a unique identifier (UUID) assigned to each transaction. Its primary relevance becomes clear in scenarios involving 3RI (Merchant-Initiated Transactions), where merchants need to reference a previously successful transaction using identifiers such as acs_transaction_id and ds_transaction_id. In such cases, while the XID may remain the same across the initial and subsequent 3RI transactions, the merchant_transaction_id must be unique for each transaction.\nFor CIT (Customer-Initiated Transactions), both the XID and merchant_transaction_id can either be the same or different UUIDs — both approaches are acceptable."}}}}},"paths":{"/cards/{card_id}/3ds-check":{"get":{"tags":["3D Secure (3DS)"],"summary":"Perform 3DS Status Check","description":"Check the 3DS authentication status of a card. \n\n**Endpoint to Check Initialize Device Fingerprint Status**: `GET /cards/{card_id}/3ds-check?init_received=true&xid={xid}&merchant_transaction_id={merchant_transaction_id}` \n\n**Endpoint to Check Authentication Status**: `GET /cards/{card_id}/3ds-check?xid={xid}&merchant_transaction_id={merchant_transaction_id}`\n","operationId":"threeds-check","parameters":[{"name":"card_id","in":"path","required":true,"schema":{"type":"string","title":"Card ID","description":"Unique identifier for the card being authenticated."}},{"name":"merchant_transaction_id","in":"query","required":true,"description":"Generated by the merchant. Must be a unique identifier assigned to each transaction.","schema":{"type":"string"}},{"name":"xid","in":"query","required":true,"schema":{"type":"string","minLength":28,"maxLength":28,"description":"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."}},{"name":"init_received","in":"query","required":false,"allowEmptyValue":true,"description":"Boolean flag controlling which status is returned:\n- 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.\n- **initReceived=false** or not provided: Returns authentication status after the challenge questionnaire/html is submitted by the user in the 3DS challenge flow.\n","schema":{"type":"boolean","default":false}},{"$ref":"#/components/parameters/auth-header"}],"responses":{"200":{"description":"Successful check","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSCheckResponse"}}}},"400":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The request was invalid."},"401":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"No credentials were provided, or the provided credentials were expired."},"403":{"description":"Forbidden. The client does not have permission to perform this action, or the vault context could not be determined from the request.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"Resource not found."},"422":{"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"description":"The server was unable to process the request because it contains invalid data."},"500":{"description":"An unexpected error occurred.","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ThreeDSErrorResponse"}}}},"503":{"description":"Service Unavailable. The downstream network is temporarily unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
{% openapi-webhook spec="card-management-api" name="threeds-challenge" method="post" %}
[Broken link](https://docs.verygoodsecurity.com/cmp/developer-resources/api/broken-reference)
{% endopenapi-webhook %}
{% openapi-webhook spec="card-management-api" name="threeds-callback" method="post" %}
[Broken link](https://docs.verygoodsecurity.com/cmp/developer-resources/api/broken-reference)
{% endopenapi-webhook %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.verygoodsecurity.com/cmp/developer-resources/api/3d-secure-3ds.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.