V2 Flows

Once the initialize API has been called, the response will indicate which flow to begin.

Please note, if the merchant’s 3DS Provider is Cardinal, Flow C is irrelevant and can be disregarded.

Flow A: 3Ds complete

If the response contains ECI and CAVV values, the 3DS step is complete and the merchant can proceed to call the SALE api with these values.

See V2 Add 3DS fields in Sale API (Flows A, B, C)

Flow B: challenge required

If the threeDSProviderResponse has a status of ACS_REQUIRED (or alternatively, check for the challengeRequired property), redirect to the url provided in the redirectUrl property.

The user will land on a 3DS challenge page. After authenticating, the user will be redirected back to the merchantRedirectUrl which was provided by the merchant in the initialisation API request body.

From there, the merchant can extract the transID and use it to call the result API to get the result of the 3DS challenge, and retrieve the eci and cavv values required for the sale operation.

See:

V2 ACS challenge (Flows B, C)

V2 3DS Result API (Flows B, C)

V2 Add 3DS fields in Sale API (Flows A, B, C)

Flow C: device data collection required

If the initialization response has a status of INITIALIZED, it indicates that the merchant must perform device data collection inside a hidden iframe on the page.

The merchant must use the redirectUrl to setup a hidden iframe, and listen for a Post Message Event. If successful, proceed to call the Auth API.

The Auth API response will indicate 2 possible flows - Flow A and Flow B described above. The response structure and properties are exactly the same as the initialization response.

See:

V2 Create Device Data Collection Iframe (Flow C)

V2 3DS Auth API (Flow C)

Example logic for flows

Here is a minimal example of the logic that would be used to determine which flow to begin:

// START 3DS Flow
const response = await initialize(); 
if (response.responseCode !== '3DS_1000') return handleError(response);
else if (response.threeDSProviderResponse.eci && response.threeDSProviderResponse.cavv) // Flow A - 3DS complete
    sale(response.threeDSProviderResponse);
else if (response.threeDSProviderResponse.status === 'ACS_REQUIRED') // Flow B - challenge required
    redirectToChallengePage(response);
else if (response.threeDSProviderResponse.status === 'INITIALIZED') // Flow C - device data collection required
    deviceDataCollection(response);