Set up your server to authenticate 3D Secure 2.0 payments using the advanced flow with the Web SDK.
To have more control over the 3D Secure 2.0 flow, use the advanced flow with the Web SDK. This allows you to:
- Define whether a given BIN supports 3D Secure 2.0 before you perform the initial call.
Reduce the frequency of calls your server needs to make, by caching the key used to authenticate a 3D Secure 2.0 payment. So instead of fetching a key for every transaction, you fetch a key (the
threeDSMethodURL) that you can use for a whole card BIN range, which you can use as needed.
Manage the use of device fingerprinting, with the option to not perform it at all.
This means that you can submit the 3D Secure 2.0 authentication and authorisation requests in a single API call. In some cases, the issuer may ask for additional verification from the cardholder, requiring you to make an additional API call.
How it works
Authenticating a 3D Secure 2.0 payment with the advanced web flow follows these steps:
- Your server makes an API call, and receives either a URL or a key required to authenticate 3D Secure 2.0 for card BIN ranges. You cache this. At this point, you can also use the 3D Secure 2.0 cached data to apply any other logic you may consider relevant. For example, not performing the initial fingerprinting, or not using 3D Secure 2.0 based on issuer availability.
- When a shopper submits a payment from this BIN range, the SDK fingerprints their device and passes the result to your server.
- Your server submits a payment request with the cached key and the device fingerprint:
- If approved, authentication is completed and the payment is authorised.
- If not approved, the Web SDK requests additional verification from the shopper to authenticate the payment. If verified successfully the payment is authorised.
You will also need to update your cache. We recommend doing this at least every 24 hours.
Step 1: Cache authentication keys
/get3dsAvailability request, providing a
cardNumber from a BIN range you want to cache. For example, using
4212345678901245 will fetch the
threeDSMethodURL for all cards in the 4212 XXXX XXXX XXXX BIN range.
Make a similar request for every card BIN range you want to cache.
If this BIN range is enrolled in 3D Secure 1.0, the
threeDS1Supported parameter will be returned as
If this BIN range is enrolled in 3D Secure 2.0, the response will include:
threeDS2Supportedparameter set to
dsPublicKeysarray containing a list of 3DS Directory Server public keys that you can use for in-app flow device fingerprint encryption. This array might contain multiple items if the BIN range is for a multi branded card.
threeDS2CardRangeDetailsarray containing card ranges, including the 3DS protocol version supported by the card issuer. An item might contain a
threeDSMethodURLif configured for the card range. Use the
threeDSMethodURLto trigger device fingerprinting using the Web SDK.
If a card is registered with multiple 3D Secure 2.0 schemes, the
threeDS2CardRangeDetails array might contain a
threeDSMethodURL for each scheme.
Step 2: Fingerprint shopper device
Initialize the Web SDK to fingerprint the shopper's device. If you are pre-fetching authentication keys, you need to generate your own unique identifier. For more information, see Web SDK integration.
If you are storing cards on file and want to provide a seamless experience to your shoppers even using authentication, perform the Web SDK fingerprint while the shopper is performing another action in your checkout.
Optionally, you can decide not to perform device fingerprinting. In this case, the value of
threeDSCompInd in your payment request (Step 3 below) has to be set to
Note that not performing device fingerprinting may increase the number of challenged transactions and potentially reduce the conversion.
Step 3: Submit 3D Secure 2.0 payment with cached keys
Submit a payment request to the
/authorise endpoint. Include all the details required for card authorisation, and the
threeDSCompInd that you received from the SDK.
If you only want to authenticate a 3D Secure 2.0 payment with Adyen and authorise it later, include the
authenticationOnly parameter within
You'll receive a response containing a
- Authorised – Indicates that the 3D Secure 2.0 authentication was frictionless, and the payment authorisation was successfully completed.
- ChallengeShopper – The issuer has requested additional authentication from the shopper.
- AuthenticationFinished – The authentication is now finished and you can now retrieve the ECI and AV value and submit them to another acquirer (when authenticationOnly was set to true). See Step 5.
You'll also receive a
threeDS2Token, which you'll use to authenticate for this transaction.
Step 4: Authenticate the shopper
Present a request for additional authentication to the shopper through the Web SDK. After this authentication Adyen will receive the results of the shopper authentication with their issuer. For more information, see Web SDK integration.
Step 5 (optional): Retrieve authentication details
/retrieve3ds2Resultto retrieve the ECI and AV values.
Step 6: Complete the payment
If you receive
ChallengeShopper, the Web SDK will present a request to the shopper, in order to verify that they are the cardholder.
Once the shopper has successfully completed the additional verification, authorise the 3D Secure 2.0 payment by making an
/authorise3ds2 request from your server. Send the
transStatus generated by the SDK and the
threeDS2Token that you received earlier.
If the Challenge was successful you'll receive Authorised as the