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
   }
 },
)