Init 3DS API - Smart Payments 3DS Execution

Suggest Edits

3DS Initialization Overview

The Init 3DS API is used to initialize the 3DS protocol. It should be called once the transaction credit card details are available. The call initiates the 3DS flow and provides the credit card details for the process.

Note: Make sure the full card details are available before making the call.

3DS Init API Request

The return value for the 3DS Init API provides the following:

  • A URL from the issuer - that enables the issuer ACS to collect device data on the merchant website via a hidden iframe as defined by the 3DS protocol.
  • threeDSServerTransID - that is required to be passed later on to Forter in the Order Validation API
  • correlation ID - that can be submitted to Forter as part of the Order Validation API later in case the merchant cannot provide the full Credit Card (PAN) number later for PCI compliance / other reason.
  • merchantCardToken - The credit card token used by the merchant when full PAN+ token was already sent to Forter

The 3DS initialization calls should not be sent directly from the client-side browser for security reasons (it should be a server-server API call from the merchant to Forter). The following steps should take place:

  1. Once full credit card details are available on the merchant's client side the client should make a call to the PCI compliant merchant server side.
  2. After the credit card details are passed to the merchant server, the merchant should send the API request to Forter.
  3. The API response should be passed back to the client side and 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. See the server side and the client side code sample below.

Please see the Init API Reference for full details.

📘

Full Credit Card Details

In case the merchant does not require standard PCI compliance and there is an option to pass the credit card information directly to Forter without sending it to the merchant server, please contact the Forter integration team.

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

3DS Init API Response

The API response should be passed back to the client side and 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. See the server side and the client side code sample below.

{
  "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"
}

Server Side API Implementation

Below is an example server-side implementation (in JavaScript) to demonstrate how the client side details should be retrieved. 

app.post('/init3DS', async (req, res) => {
   // Get the credit card details
   // it can be sent directly in the request body, or using some kind of ID and querying the payment gateway.
   const cc = req.body.cc;
   const response = await request.post({
       url: 'https://api.forter-secure.com/v3/adaptive-auth/3ds/init',
       json: {
           "orderId": "260000000861434",
           "fullCreditCard": cc
       },
       headers: {
           'authorization': '<Your Authentication Token>',
           'x-forter-siteid': '<Your Site ID>',
           'api-version': '<Your API Version>'
       }
   });
   res.send(response);
});

SDK Arguments

The following parameters should be included in the SDK argument:

  • The response from the Forter 3DS init API call.
  • A callback function receiving the reference 3DS transaction ID and an optional error.

Client Side Implementation

JavaScript Snippet
Forter will provide a JS snippet that merchants will need to copy and paste onto their checkout page (wherever the card entry iframe is located). The script should be pasted directly before the closing HTML tag.

Note that this should not override or conflict any other existing Forter JavaScript snippets already on the site.

CSP Integration (Content Security Policy)
In case the merchant website enforces a CSP, please make sure the following rules are whitelisted:

  • connect-src https://*.checkouttools.com
  • script-src https://*.checkouttools.com

Getting the init Response

Below is an example (in JavaScript) of how Forter recommends merchants retrieve the init response:

window.checkoutTools.tds.init3DS(response, (error, threeDSID) => {
if (error) {
       // An error occurred
   } else {
       // Initialization completed
       return threeDSID
   }
});

Updated 6 months ago