3DS Challenge
The 3DS Challenge is executed after the Pre Auth Order API
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
Outcome | Call to Action | Order 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 5 months ago