3DS Challenge Verify API - Smart Payments Execution
3DS Challenge Verify API Overview
The 3DS Challenge Verify API is sent to Forter to provide the challenge results after the challenge journey was completed on the merchant site (following a callback that the merchant receives directly from the ACS about completion).
The 3DS Challenge API request requires only the order id and challenge token that was received by the merchant in the callback from the ACS.
3DS Challenge Verify API Request
Once the buyer completes the 3DS challenge (step up authentication) on the merchant website, a client side challenge result token (CRes token) is generated. The token should be sent by the merchant to Forter via a server-side Challenge Verification API request. The Forter response will contain Forter's final trust assessment as well as the server-side issuer authentication result token values that need to be passed to the payment gateway authorization request. Please see the full 3DS Challenge Verify API Reference for all relevant fields and server-side actions.
Key Data points include:
- orderID - the unique identifier for the order in your system
- clientSideChallengeResultToken - The ThreeDS challenge result token, returned by Forter's JavaScript after the
getChallangeResult
callback has fired
{
"orderId": "2356fdse0rr489",
"clientSideChallengeResultToken": "eyJhY3NUcmFuc0lEIjoiNGQ5NzhiNTktNjU4NC00OWYzLTkwMDItOGM0YmI4ZGFlYTljIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0IiwibWVzc2FnZVZlcnNpb24iOiIyLjEuMCIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiNzdiYWY2YjctNzFjMS00M2Q0LThhOWQtNTg4ODZlNGE2OTJjIn0"
}
3DS Challenge Verify API Response
The 3DS Challenge API response will contain Forter's decision ("APPROVE", "DECLINE", "NOT_REVIEWED"
along with verification-specific data around the challenge request.
{
"forterDecision": "APPROVE",
"recommendation": "",
"verificationMethod": {
"verificationId": "345H3DEHGJ7512",
"correlationId": "HGJ7512345H3DE",
"type": "THREE_DS",
"verificationSpecificData": {
"ThreeDS": {
"encodedChallengeRequest": "eyJhY3NUcmFuc0lEIjoiMTEyY2RiNWItMGFlYy00MTY5LThjMWYtYWMyN2JlNjAxMjhhIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA0IiwibWVzc2FnZVZlcnNpb24iOiIyLjEuMCIsIm1lc3NhZ2VUeXBlIjoiQ1JlcSIsInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjoiZWRhM2MwMzYtZWMyYS00NmZkLTlmYWItNzBlZTgyYjJjNzQ5In0=",
"ACSUrl": "https:/ /acs-us-east-1.nd.nds-sandbox-issuer.com/api/v1/acs/browser_sdk_challenges",
"ECIValue": "02",
"version": "2.1.0",
"authenticationValue": "tSvPDt3PINNaoL+ERXdg0jVrmWc=",
"authenticationType": "01",
"transStatus": "Y",
"cavvAlgorithm": "3",
"cardEnrolled": true,
"acsTransID": "6fd30e89-8171-4cc3-b86e-3d59582af2f6",
"acsReferenceNumber": "ftr-internal-acs-approval",
"acsSignedContent": null,
"dsTransID": "38bbf46f-c023-4f4c-ae2c-35fb301632a5",
"threeDSServerTransID": "26d648a9-da8a-4f8b-a76d-094801d2fd45",
"messageCategory": "01",
"transStatusReason": "01",
"challengeCancel": "01",
"interactionCounter": "01",
"acsChallengeMandated": "Y",
"isFallback": true,
"threeDSecureMode": "sca",
"threeDSecureResult": "590040",
"threeDSecurePreference": "nopref",
"outOfScopeForPSD2": "ANONYMOUS_PREPAID_CARD",
"exemption": "TRANSACTION_RISK_ANALYSIS"
},
"phone": {
"phone": "15557654321",
"smsVerified": {
"sent": true,
"verificationStatus": "PENDING",
"timeSent": 1389567341,
"timeVerified": 1388560227
}
},
"email": {
"email": "[email protected]",
"emailRole": "ACCOUNT",
"emailVerification": {
"sent": true,
"verificationStatus": "PENDING",
"timeSent": 1389567341,
"timeVerified": 1388560227
},
"updateTimes": {
"creationTime": 1448549922,
"removalTime": 1448895522
}
}
},
"status": "IN_PROGRESS",
"statusCode": "100",
"statusMessage": "Verification code sent"
},
"decisionReason": "",
"orderId": "2356fdse0rr489",
"linkToEventInDashboard": "https://portal.forter.com/dashboard/:id"
}
Server Side Implementation
The example below provides a recommended Server-side implementation of the Forter 3DS Challenge Verify API (in JavaScript)
const response = await request.post({
url: 'https://api.forter-secure.com/v3/adaptive-auth/3ds/verify/[ID]', // where ID is the orderId
json: { cres }
});
res.send(response);
Client Side Integration
The code example below outlines Forter's recommended client-side approach for integrating the relevant challenge flow results as part of the 3DS Challenge Verify implementation (in JavaScript)
window.checkoutTools.tds.triggerChallengeIfNeeded(
threeDSResponse,
challengeContainer.current,
async (error, wasChallengePerformed, transStatus, cres) => {
if (error) {
// An error occurred
} else {
// Challenge flow completed
}
},
)
Updated 13 days ago