Integration Guides

3DS Challenge

The 3DS Challenge is executed after the Pre Auth Order API

Suggest Edits

3DS Challenge Overview

In some cases, a challenge may be required by the bank as part of the 3DS authentication process. Only when Forter returns VERIFICATION_REQUIRED_3DS_CHALLENGE in the recommendation field is a challenge requested by the bank, and you need to follow the next steps.

The challenge flow begins by displaying a challenge window in the checkout page, which renders the ACSUrl received in the Order Response inside an IFrame.

Once the buyer completes the challenge within the window, the challenge window sends the buyer's input to the bank's ACS and receives a clientChallengeResultToken (CRes) in return.

Once the CRes is received, the Forter 3DS Challenge Verify API is called from the merchant's server with the CRes. The Verify response includes the fraud decision (which may differ from the decision in the Order response) along with the final 3DS outcome (Successful 3DS or Unsuccessful 3DS).

Step 1 - Server Side: Implement an endpoint for calling Forter Verify API

Verify Request

To call the Forter 3DS Verify API in this endpoint, please provide the same orderId which was used in the Order Request, and the clientSideChallengeResultToken received from your client side (see next step).

Example of Order Request

{
  "orderId": "2356fdse0rr489",
  "clientSideChallengeResultToken": "eyJhY3NUcmFuc0lEIjoiNGQ5NzhiNTktNjU4NC00OWYzLTkwMDItOGM0YmI4ZGFlYTljIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0IiwibWVzc2FnZVZlcnNpb24iOiIyLjEuMCIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiNzdiYWY2YjctNzFjMS00M2Q0LThhOWQtNTg4ODZlNGE2OTJjIn0"
}

Verify Response

OutcomeCall to ActionOrder Response Fields
Forter Approved & 3DS was executed successfully

Borderline transaction which was APPROVED by Forter only following successful 3DS

OR

PSD2 transaction which was APPROVED by Forter, 3DS was executed in order to comply PSD2 and Challenge succeeded		Authorize with 3DS results"forterDecision": "APPROVE"
"verificationMethod": { "status": "AUTHENTICATED"}

In order to simulate such Verify Response, use card number 5111220000000009 when calling the Init API, and PIN Code 1234 in the challenge window

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "ATTEMPTED"}
Forter Approved & 3DS was executed unsuccessfully

PSD2 transaction which was APPROVED by Forter, 3DS was executed in order to comply PSD2 regulation and Challenge failed		Do not Authorize"forterDecision": "APPROVE"
"verificationMethod": { "status": "NOT_AUTHENTICATED"}

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "NOT_AUTHENTICATED_BANK_REJECT"}

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "NOT_AUTHENTICATED_TECHNICAL_ISSUE"}

OR

"forterDecision": "APPROVE" "verificationMethod": { "status": "NETWORK_ERROR"}

In order to simulate such Verify Response, use card number 5200000000004447 when calling the Init API, and PIN Code 1234 in the challenge window
Forter Declined & 3DS was executed unsuccessfully

Borderline transaction which was DECLINED by Forter following unsuccessful 3DS Challenge		Do not Authorize"forterDecision": "DECLINE"
"verificationMethod": { "status": "NOT_AUTHENTICATED"}

In order to test such response, use card number 5111220000000009 in the accountOwner object within the API request, and PIN Code 4567 in the challenge window

OR

"forterDecision": "DECLINE" "verificationMethod": { "status": "NOT_AUTHENTICATED_BANK_REJECT"}

In order to simulate such Verify Response, use card number 5200000000002227 when calling the Init API, and PIN Code 1234 in the challenge window

OR

"forterDecision": "DECLINE" "verificationMethod": { "status": "NOT_AUTHENTICATED_TECHNICAL_ISSUE"}

In order to simulate such Verify Response, use card number 5200000000003332 when calling the Init API, and PIN Code 1234 in the challenge window

OR

"forterDecision": "DECLINE" "verificationMethod": { "status": "NETWORK_ERROR"}

Step 2 - Client Side: Display 3DS Challenge window, and call your Server Side

Use the 'checkoutTools triggerChallengeIfNeeded' function and the response from calling the Order API as an input to automatically trigger a challenge in the provided container and obtain the clientSideChallengeResultToken. You can then send this token in the call to your server-side endpoint from step 1.

Example of displaying a challenge in the checkout page

    window.checkoutTools.tds.triggerChallengeIfNeeded(
        3DSResults.data?.verificationMethod?.verificationSpecificData?.ThreeDS,
        challengeContainer, // e.g. document.getElementById('div-where-you-want-the-challenge-to-render')
        async (error, wasChallengePerformed, transStatus, clientSideChallengeResultToken) => {
            if (error) {
                console.error("Error while trying to verify.", error);
            } 
            else if (wasChallengePerformed) {
                // Call your server side to call Forter Verify API (See next example)
            } 
            else {
                // No need for a challenge. Obtain the 3DS results from 3DSResults variable and forward to the payment processor
            }
        });
}

Example of calling the the server side with the obtained CRes

const verifyRes = await axios.post("/api/verify_3ds", {clientSideChallengeResultToken}); console.log(
                    `Forter decision after 3DS challenge: ${verifyRes.data.forterDecision}.`,
                    `Status: ${verifyRes.data.verificationMethod.status}`
 )
// Send the results of the 3DS process in verifyRes to the payment processor

Updated 6 months ago