3D Secure 2 Integration
What's 3D Secure 2
3D Secure 2 provides seamless new ways to authenticate customers while addressing the shortcomings of the existing 3DS 1.0.2. It incorporates support for biometric and token validation and streamlines the Paysafe.js experience using “frictionless” authentication.
You can find more details about 3D Secure 2 here.
Enabling 3D Secure 2 in Paysafe.js
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.js 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.
3D Secure 2 API requires a cardholder name for the Authentication, so this parameter is mandatory and should be passed to the Paysafe.js. The cardholder's email, phone or cell phone is required for Visa products. See more about the holderName, email, phone and cellPhone parameters here.
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.js, pass these additional fields to the tokenize function of Paysafe.js:
- threeDS
- billing address
- shipping address
More information about "frictionless" transactions is available here.
Liability Shift Matrix
Paysafe.js 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.js 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.js handles the 3D Secure 2
Try in CodePen
You can see a brief demonstration of Paysafe.js with 3D Secure 2 in CodePen.
Enter a test card number (for example, 4000000000001091), a valid future expiry date, a random three digit CVV, and then click Pay.
The following cURL example 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 https://api.test.paysafe.com/customervault/v1/singleusetokens/search \
-u test_vniezsai:B-qa2-0-59564dfa-0-302c021426a55dde98dc2a052cccc1ddc8daa776a7a4fe2e0214080388fded986767abc445e58af123c01003cb8b \
-H 'Content-Type: application/json' \
-d ' {
"paymentToken" : "CARDS PAYMENT TOKEN RECEIVED FROM CLIENT BROWSER"
} '