Search Overlay

3D Secure 2 Integration

What's 3D Secure 2

3D Secure 2 provides seamless ways to authenticate customers. It incorporates support for biometric and token validation and streamlines the checkout experience using “frictionless” authentication.

You can find more details about 3D Secure 2 here.

Enabling 3D Secure 2 in Paysafe Checkout

Usually, when merchants are making direct 3D Secure 2 API integration, the following steps should be implemented:

  • Step 1: Collect Device Fingerprint ID
  • Step 2: Authenticate Customer
  • Step 3: Complete Issuer Challenge (Conditional)

Paysafe Checkout does this on behalf of the merchants in the background, so minimal work is required for integrating 3D Secure 2. Integration is done by passing an additional parameter (named "useThreeDSecureVersion2"), and a 3D Secure 2 enabled FMA.

Once 3D Secure 2 is integrated, all the communication with the 3D Secure 2 API and SDK are handled in the background, and the merchants receive a token ready for Card Authorization.

To make use of the "frictionless" transactions with 3D Secure 2, passing additional parameters to the API is essential. In the case of 3D Secure 2 integration through Paysafe Checkout, pass these additional fields to the setup function of Checkout:

  1. threeDS
  2. billing address
  3. shipping address

More information about "frictionless" transactions is available here.

Liability Shift Matrix

Paysafe Checkout interprets the responses from the 3D Secure 2 API and returns either a single-use token (SUT) containing the payment instrument + authentication information or an error to the merchant.

The token is issued when a challenge (or a frictionless authentication) is completed successfully by the customer. If the Authentication has failed, an error is returned.

When the merchants receive the SUT, they can look up its content and consult with Liability Shift matrix to determine whether to proceed with the Card Authorization request.

How it Works for the Customers

Internally Paysafe Checkout uses the 3D Secure API js SDK to handle the device fingerprinting and the customer challenge, just as the merchants use it.

From the customer's perspective, it will look the same in both cases:

  • When the merchants handle the 3D Secure 2
  • When Paysafe Checkout handles the 3D Secure 2


For a brief demonstration of Paysafe Checkout, use the button below to open it then enter a test card number (for example, 4000 0000 0000 1000), a valid, future expiry date, a random three-digit CVV, random cardholder name and then click Pay.

To simulate different scenarios with 3D Secure 2 please check the card numbers described here

A successful tokenization attempt will result in the token appearing in the cURL example below, which shows how you can make a token lookup request (try this out in a Unix/Cygwin terminal to see the API response). If you have python installed, we recommend that you add the following to the end of the cURL request to format the JSON response clearly | python -mjson.tool

curl -X POST \
-u test_vniezsai:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-Type: application/json' \
-d ' {
} '

To view the above example in CodePen, click here.