Set up your server to authenticate 3D Secure 2.0 payments using the advanced flow with either the iOS or Android SDK.
To have more control over the 3D Secure 2.0 flow, use the advanced flow with the In-app SDK for iOS or Android. This allows you to:
- Collect the specific scheme public keys ahead of the transaction that they are going to be used for.
- Reduce the frequency of calls your backend server needs to make to Adyen. By caching the scheme public keys, you will be able to collect one and use multiple times the public keys used to encrypt the device fingerprint collected in the shopper device.
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 in-app flow follows these steps:
- Your server makes an API call, and receives a scheme public key required to encrypt the device data in the in-app SDK. You cache this key for future use.
- When a shopper submits a payment for this scheme, the SDK collects and encrypts the device data with the scheme key and passes the result to your application. Your application will then send it to your server.
- Your server submits a payment request with the device data:
- If approved, authentication is completed and the payment is authorised.
- If not approved, the in-app 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.
To authenticate 3D Secure 2.0 payments, you'll also need to integrate an in-app SDK specific for your ecosystem (iOS or Android).
Step 1: Cache authentication keys
/get3dsAvailability request, providing a
cardNumber from a BIN range you want to cache. For example, using
4111111111111111 will fetch the
threeDSMethodURL for all cards in the 4111 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 item.
Step 2: Fingerprint shopper device
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
sdkEncData that the SDK has generated for you.
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. In this case you'll also receive a
threeDS2Token, which you'll use to authenticate for this transaction.
- 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.
Step 4: Authenticate the shopper
Present a request for additional authentication to the shopper through the in-app SDK. After this authentication Adyen will receive the results of the shopper authentication with their issuer. For more information, see the iOS 3DS SDK or the Android 3DS SDK.
Step 5 (optional): Retrieve authentication details
/retrieve3ds2Resultto retrieve the ECI and AV values.
Step 6: Complete the payment
If you receive
ChallengeShopper, the in-app 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 received Authorised as the