3DS Initialization

3DS Initialization Overview

The 3DS Initialization API initiates the 3DS flow with Forter's 3DS service.

The request should be sent with the credit card details for the transaction as soon as they become available.

If you have vaulted cards and the full card number is not exposed on the checkout page, please check with your Tokenization vendor regarding the availability of a Detokenization Proxy service. This service enables you to make a request to a 3rd party (such as Forter 3DS Initialization API) with a Token included in the request. The request is then routed through the proxy, where the token is replaced with the corresponding card data.

The response includes a correlationId and threeDSServerTransID to enable tracking of future calls, as well as a methodURL that should be rendered on the checkout page using Forter 3DS SDK. The methodURL loads JavaScript code that collects device fingerprints and sends them directly to the Bank's ACS.

• ACS -  Access Control Server is a tool used by issuing banks to confirm the identity of the cardholder using the 3DS protocol

Step 1 - Server Side: Implement an endpoint for calling the Forter 3DS Initialization API

3DS Initialization Request

To authenticate with Forter's service, use basic authentication and provide the Site ID and Secret Key, provided by Forter.

To call the 3DS Initialization API in this endpoint, please provide the Card Data (Full card number, Cardholder Name, Expiration Month & Year) and the unique id of the Order.

Example for 3DS Initialization Request

{
  "fullCreditCard": "2424242424242424",
  "nameOnCard": "John R. H. Smith",
  "orderId": "2356fdse0rr489",
  "expirationMonth": "03",
  "expirationYear": "2018"
}

Example of calling Forter 3DS Initialization API written in Node.js using Fastify.

const app = require('fastify')({
    logger: true
})
const axios = require("axios");


// Site-related fields
const SITE_ID = "${siteId}"
const SECRET_KEY = "<secret_key>"
const API_VERSION = "<api_version>"


// Order ID generated by the merchant. 
const SOME_ORDER_ID = "260000000861434";


const forterHttpClient = axios.create({
    baseURL: 'https://api.forter-secure.com/v3',
    timeout: 10000,
    headers: {
        'x-forter-siteid': SITE_ID,
        'api-version': API_VERSION
    },
    auth: {
        username: SECRET_KEY,
    }
});

app.post('/api/init_3ds', async (request) => {
    const {fullCreditCard} = request.body;
    const response = await forterHttpClient.post('/adaptive-auth/3ds/init',
        {
            fullCreditCard
        }
    );
    return response.data;
})

3DS Initialization Response

Example for 3DS Initialization Response:

{
  "threeDSServerTransID": "26d648a9-da8a-4f8b-a76d-094801d2fd45",
  "dsIdentifier": "A000000004",
  "methodURL": "https://acs-us-east-1.sandbox-issuer.com/api/v1/acs/3ds_method",
  "version": "2.1",
  "correlationId": "HGJ7512345H3DE"
}

To test your integration and simulate 3DS Initialization response, use the card number 5222220000000005 in the request.

Step 2 - Client Side: Call your Server Side

The endpoint you implemented on your server side in Step 1 should be called from your client side once the transaction credit card details are available, and the response should be passed back to the client side, where the merchant client-side response handler should trigger the Forter callback function checkouttools.tds.init3DS using the JSON received in the response as the callback.

Example of calling your server side once the transaction credit card details are available, and trigger the Forter callback function checkouttools.tds.init3DS using the JSON received in the response as the callback:

const onCreditCardChange = async (fullCreditCard) => {
    //TODO: implement isCardNuberValid function
    if (!isCardNuberValid(fullCreditCard)) {
        return;
    }
    const res = await axios.post("/api/init_3ds", {
        fullCreditCard
    });
    await window.checkoutTools.tds.init3DS(res.data, async (error, threeDSServerTransID) => {
        if (error) {
            console.error("Error inside init3DS", error);
        } 
        else {
            // Save threeDSServerTransID for later order API call
        }
    });
}