3DS

3DS Testing

This guide explains how to simulate 3D Secure (3DS) initialize and authentication flows for testing purposes. You can test different synchronous responses, including challenge flows, frictionless flows, and various HTTP error scenarios.

This simulation is performed by using static, predefined cardID values within the request URL. Each static cardID is configured to return a specific 3DS status or error response, allowing you to test how your application handles each scenario.

Test Setup

Base URL: https://gw-01-sandbox.vgsapi.com/3ds-mocks

To simulate these 3DS responses, you only need to send a POST request to the correct endpoint path, embedding the test cardID into the URL.

• No Service Account or JWT Token is required. These test endpoints are open and do not require authentication.

• You must include the Content-Type: application/vnd.api+json header in your requests.

3DS Initialize API

The 3DS Initialize API (/cards/{cardID}/3ds-initialize) simulates the first step of the 3DS process. This is the synchronous request that returns the iframe (required for device-fingerprinting) that the merchant needs to embed on their frontend to proceed with the authentication.

You can test various scenarios by providing the corresponding cardID as part of the URL path.

Example Request URL: POST https://gw-01-sandbox.vgsapi.com/3ds-mocks/cards/CRAbcDefGhijKlmNoPqrStuVw/3ds-initialize

Example CURL:

curl -X POST "https://gw-01-sandbox.vgsapi.com/3ds-mocks/cards/CRAbcDefGhijKlmNoPqrStuVw/3ds-initialize" \
-H "Content-Type: application/vnd.api+json"

CRAbcDefGhijKlmNoPqrStuVw	200 OK	Returns the synchronous response with the iframe/data needed to proceed with authentication.
CRnOiFrAmEqDxRgXU3TFmtcD	206 OK	Returns a synchronous response without iframe/data, confirming that initialization is not required and the authentication process can proceed immediately.
CRaZcXeVtBrNnMpLoKjIhUgYt	400 Bad Request	Simulates a 400 error from the initialize endpoint.
CRdFhJkLmNoPqRsTuVwXyZ012	401 Unauthorized	Simulates a 401 error from the initialize endpoint.
CRpOiUytRewQAzXswEdcRfVtB	403 Forbidden	Simulates a 403 error from the initialize endpoint.
CRuYtRewQAzWsXeDcRfVtGbYh	404 Not Found	Simulates a 404 error from the initialize endpoint.
CRiKoLpMnBvCxZaQsWeRdTfYg	422 Unprocessable Entity	Simulates a 422 error from the initialize endpoint.
CRzXaScVbNmLkJhgFdSaQwErT	500 Internal Server Error	Simulates a 500 error from the initialize endpoint.
CRbNtMvCxZlKjHgFdSaQwErTy	503 Service Unavailable	Simulates a 503 error from the initialize endpoint.

3DS Authenticate API

The 3DS Authenticate API (/cards/{cardID}/3ds-authenticate) simulates the final authentication response.

• For frictionless flows, this will be the synchronous response.

• For challenge flows, this response will be sent in the asynchronous webhook notification.

You can test various authentication outcomes and error scenarios by providing the corresponding cardID as part of the URL path.

Example Request URL: POST https://gw-01-sandbox.vgsapi.com/3ds-mocks/health/cards/CRAbcDefGhijKlmNoPqrStuVw/3ds-authenticate

Example CURL:

curl -X POST "https://gw-01-sandbox.vgsapi.com/3ds-mocks/cards/CRcHaLlEnGeReQdXU3TFmtcD/3ds-authenticate"
-H "Content-Type: application/vnd.api+json"

Test cardIDs and Expected Responses

CRAbcDefGhijKlmNoPqrStuVw	200 OK	AUTHENTICATED	Simulates a successful authentication (final auth response).
CRcHaLlEnGeReQdXU3TFmtcD	200 OK	CHALLENGE_REQUIRED	Simulates a response that includes the prebuilt HTML form (challenge_form) to directly render the challenge or build your own form using challenge_url, challenge_request, and challenge_session_data.
CRXyZ0123456789abcDEfGhij	200 OK	INFORMATIONAL_ONLY	Simulates an informational-only status for a frictionless auth result.
CRMnOpQrStUvWxYzABCdefGhi	200 OK	REJECTED	Simulates a rejected status for the auth result.
CRQrStUvWxYz0123456789AbC	200 OK	UNABLE_TO_AUTHENTICATE	Simulates an unable to authenticate status for the auth result.
CRDecqZp3xRgXU3TFmtcDdzQs	200 OK	DENIED	Simulates a denied status for the auth result.
CRaZcXeVtBrNnMpLoKjIhUgYt	400 Bad Request	N/A (Error Response)	Simulates a 400 error from the authenticate endpoint.
CRdFhJkLmNoPqRsTuVwXyZ012	401 Unauthorized	N/A (Error Response)	Simulates a 401 error from the authenticate endpoint.
CRpOiUytRewQAzXswEdcRfVtB	403 Forbidden	N/A (Error Response)	Simulates a 403 error from the authenticate endpoint.
CRuYtRewQAzWsXeDcRfVtGbYh	404 Not Found	N/A (Error Response)	Simulates a 404 error from the authenticate endpoint.
CRiKoLpMnBvCxZaQsWeRdTfYg	422 Unprocessable Entity	N/A (Error Response)	Simulates a 422 error from the authenticate endpoint.
CRzXaScVbNmLkJhgFdSaQwErT	500 Internal Server Error	N/A (Error Response)	Simulates a 500 error from the authenticate endpoint.
CRbNtMvCxZlKjHgFdSaQwErTy	503 Service Unavailable	N/A (Error Response)	Simulates a 503 error from the authenticate endpoint.