Advanced flow with the Web SDK

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:

  1. 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. 
  2. When a shopper submits a payment from this BIN range, the SDK fingerprints their device and passes the result to your server.
  3. Your server submits a payment request with the cached key and the device fingerprint:
    1. If approved, authentication is completed and the payment is authorised.
    2. 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.

To authenticate 3D Secure 2.0 payments, you'll also need to integrate the Web SDK. For more information, see   Web SDK integration.

Step 1: Cache authentication keys

Submit a /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.

Request

{
   "merchantAccount":"TestMerchant",
   "cardNumber":"4212345678901245"
}

Response

If this BIN range is enrolled in 3D Secure 1.0, the threeDS1Supported parameter will be returned as true.

If this BIN range is enrolled in 3D Secure 2.0, the response will include:

  • The threeDS2Supported parameter set to true.
  • The dsPublicKeys array 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.
  • The threeDS2CardRangeDetails array containing card ranges, including the 3DS protocol version supported by the card issuer. An item might contain a threeDSMethodURL if configured for the card range. Use the threeDSMethodURL to trigger device fingerprinting using the Web SDK.
{  
  "dsPublicKeys":[  
    {  
      "brand":"visa",
      "directoryServerId":"A000000003",
      "publicKey":"eyJrdHkiOiJSU0.....Eb0dyY2JbOV80NncifQ=="
    }
  ],
  "threeDS1Supported": true,
  "threeDS2Supported": true,
  "threeDS2CardRangeDetails":[  
    {  
      "brandCode":"visa",
      "endRange":"42123456",
      "startRange":"42123456",
      "threeDS2Version":"2.1.0",
      "threeDSMethodURL":"https://pal-test.adyen.com/threeds2simulator/acs/startMethod.shtml"
    }
  ]
}

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 N.

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 threeDS2RequestData.

Request

{
   "amount":{
      "currency":"EUR",
      "value":1500
   },
   "reference":"TEST",
   "merchantAccount":"TestMerchant",
   "card":{
      "cvc":"737",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "holderName":"Card Holder",
      "number":"4212345678901245"
   },
   "threeDS2RequestData":{
      "deviceChannel":"browser",
      "threeDSCompInd":"Y",
      "threeDSRequestorID":"Fiets",
      "notificationURL":"https:\/\/localhost:8080\/fake\/threedsrequestorurl",
      "threeDSServerTransID":"c9200190-5ffe-11e8-954f-26e6f38ae710"
   },
  "browserInfo":{  
    "userAgent":"Mozilla\/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/70.0.3538.110 Safari\/537.36",
    "acceptHeader":"text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8",
    "language":"en_US",
    "colorDepth":24,
    "screenHeight":723,
    "screenWidth":1536,
    "timeZoneOffset":0,
    "javaEnabled":false
  }
}

Response

You'll receive a response containing a resultCode:

  • 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.

{
   "additionalData":{
      "threeds2.threeDS2ResponseData.dsReferenceNumber":"ADYEN-DS-SIMULATOR",
      "threeds2.threeDS2ResponseData.transStatus":"C",
      "threeds2.threeDS2ResponseData.acsChallengeMandated":"Y",
      "threeds2.threeDS2ResponseData.acsURL":"http:\/\/localhost:8080\/threeds2simulator\/services\/ThreeDS2Simulator\/v1\/handle\/eb9c6eb3-57b3-400d-bf2f-4e72bd69dcec",
      "threeds2.threeDS2ResponseData.threeDSServerTransID":"c9200190-5ffe-11e8-954f-26e6f38ae710",
      "threeds2.threeDS2ResponseData.authenticationType":"01",
      "threeds2.threeDS2ResponseData.dsTransID":"73aab3ce-eb39-49e8-8e9b-46fbf8a472f1",
      "threeds2.threeDS2ResponseData.messageVersion":"2.1.0",
      "threeds2.threeDS2Token":"— - BINARY DATA - -",
      "threeds2.threeDS2ResponseData.acsTransID":"eb9c6eb3-57b3-400d-bf2f-4e72bd69dcec",
      "threeds2.threeDS2ResponseData.acsReferenceNumber":"ADYEN-ACS-SIMULATOR"
   },
   "pspReference":"9935272408535455",
   "resultCode":"ChallengeShopper"
}

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

Optionally, if you are not aiming to pursue an authorisation with Adyen, from this point you can retrieve the authentication details from Adyen. For this, submit a request to  /retrieve3ds2Result to retrieve the ECI and AV values.

Request

{
   "merchantAccount":"TestMerchant",
   "pspReference":"9935272408535455"
}

Response

{   
  "threeDS2Result":{ 
    "transStatus":"Y",
    "authenticationValue":"3q2+78r+ur7erb7vyv66vv8deha8=",
    "eci":"07",
    "threeDSServerTransID":"73aab3ce-eb39-49e8-8e9b-46fb77a472f1"
  }
}

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.

Request

{
   "merchantAccount":"TestMerchant",
   "threeDS2Result":{
      "transStatus":"Y"
   },
   "threeDS2Token":"- - BINARY DATA - -"
}

Response

If the Challenge was successful you'll receive Authorised as the resultCode.

{
   "additionalData":{
      "cvcResult":"1 Matches",
      "authCode":"46125",
      "avsResult":"4 AVS not supported for this card type",
      "avsResultRaw":"4",
      "cvcResultRaw":"M",
      "refusalReasonRaw":"AUTHORISED",
      "acquirerCode":"TestPmmAcquirer",
      "acquirerReference":"8PPSD0S76PE"
   },
   "pspReference":"9935272408535455",
   "resultCode":"Authorised",
   "authCode":"46125"
}