Init 3DS API - Smart Payments 3DS Execution
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:
- 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.
- After the credit card details are passed to the merchant server, the merchant should send the API request to Forter.
- 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 13 days ago