Step 4: ACS challenge and receive challenge result

This step is only required if the response from the 3DS Auth API (Step 3) indicates the challengeRequired property is true. Inside this response will be another redirectUrl property.

There are two options:

Use an ACS challenge iframe
Perform a full browser redirect to ACS challenge page (If a merchantRedirectUrl was provided in the 3DS Init Call in Step 1)

Option 1: Use an ACS challenge iframe

If a merchantRedirectUrl was not supplied, create an iframe to contain the ACS challenge.

Set up iframe html

Use the redirectUrl as the src property. This is what the iframe might look like:

<iframe
    src={redirectUrl}
    title="ACS"
    style="width: 100%; height: 100vh"
></iframe>

Note the iframe width and height

The default size of the challenge iframe will be full screen. However, if the acsWindowSize property was specified in the 3DS init call (Step 1), then the iframe must have the same width and height as the acsWindowSize provided.

Example of the ACS challenge iframe

Create a POST message event Listener

The merchant site needs to know when the challenge is complete, and can proceed to call the 3DS Result. API. This done via a window.postMessage from the iframe.

Create an event listener on the page to receive this event. For security purposes, be sure to check the origin of the message is from the Netvalve domain.

const handlePostEvent = (event) => {
  if (event.origin === 'https://gateway.uat.sandbox-netvalve.com') {
      const data = event.data;
      // Use the data to perform STEP 3 
  }
};

// Be sure to attach the listener
window.addEventListener('message', handlePostEvent, false);

Extract the message data

Inside the event.data is the following object. The expected status is ACS_COMPLETED

{
    result: 'SUCCESS',
    threeDsResponse: {
        status: 'ACS_COMPLETED',
        transID: 'abc,
        providerErrorMessage: ''
    };
};

Once the message is received, whether success or fail, proceed to call the Result API in Step 5.

Expected Properties and Values

result : 'SUCCESS' | 'ERROR' Use this for error handling. *Note - SUCCESS refers to the success of the 3DS initialization step. It does not mean 3DS values have been retrieved.

status : 'ACS_COMPLETED' | 'ERROR' | 'CALLBACK_PROCESSING_ERROR' | 'TIMEOUT'

transID is the required transaction ID for the 3DS Auth API in Step 3.

providerErrorMessage will contain the error message from the 3DS provider, if any.

Option 2: Perform a full browser redirect

Instead of placing the redirectUrl inside an iframe, the alternative is to perform a browser redirect to the Netvalve page, where the ACS challenge will be hosted.

Once the challenge is complete, the user will be redirected back to the merchant site.

The transID can be extracted from the URL parameters, appended to the merchant’s url. This is what the URL might look like:

Please note : A merchantRedirectUrl must have been initially supplied in Step 1.

Proceed to fetch result

GO TO STEP 5