Server integration

Set up your server to authenticate 3D Secure 2.0 payments.


The process for submitting a 3D Secure 2.0 payment is similar to a regular card payment. To authenticate 3D Secure 2.0 payments, you'll also need to integrate an SDK (Web, iOS, or Android).

Test card numbers

Use the following test cards for 3D Secure 2.0:

4212 3456 7890 1245
5212 3456 7890 1242

You'll need to set up your server to:

  1. Submit 3D Secure 2.0 authentication request.
  2. Submit 3D Secure 2.0 authentication data to the issuer.
  3. Continue with payment authorisation.

For more information on the 3D Secure 2.0 API, check out API Reference.

To reduce the number of API calls you need to make, you can optionally cache the data needed for 3D Secure 2.0 authentication. In this case, authentication will follow a slightly different flow (see Advanced flow with the Web SDK and Advanced flow with the in-app SDK).

Step 1: Submit 3D Secure 2.0 authentication request

Initiate the authentication by making an /authorise call to request 3D Secure 2.0 authentication for the payment. Include the required threeDS2RequestData, as well as

  • deviceChannel – Use app if the payment is being initiated in an app, or browser for browser.
  • notificationURL – The URL the shopper is redirected to after the Challenge. This is the URL of your payment page. 

In addition to the regular parameters you provide to Adyen, you can send all the parameters identified in the following list. All these parameters can be also provided when submitting authentication data for the issuer, but not after.

We advise you provide all the parameters you have to increase the likelihood of a frictionless flow and a higher authorisation rate.

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
   },
   "merchantAccount":"TestMerchant",
   "reference":"TEST",
   "threeDS2RequestData":{
      "deviceChannel":"browser",
      "notificationURL":"https:\/\/localhost:8080\/fake\/notificationurl"
   },
   "browserInfo":{
      "userAgent":"Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9) Gecko/2008052912 Firefox/3.0",
      "acceptHeader":"text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
   },
   "card":{
      "cvc":"737",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "holderName":"Card Holder",
      "number":"4212345678901245"
   }
}

Response

We'll check whether the card is enrolled in the 3D Secure 2.0 scheme. If enrolled, you'll receive IdentifyShopper as the resultCode. You'll also receive a threeDS2Token and threeDSMethodURL, which you'll use to authenticate for this transaction.

{
   "additionalData":{
      "threeds2.threeDS2Token":"— - BINARY DATA - -",
      "threeds2.threeDSServerTransID":"c9200190-5ffe-11e8-954f-26e6f38ae710",
      "threeds2.threeDSMethodURL":"https:\/\/issuer-iframe.url\/"
   },
   "pspReference":"9935272408535455",
   "resultCode":"IdentifyShopper"
}

Step 2: Fingerprint shopper device

Then initialize the SDK to fingerprint the shopper's device. For more information, refer to the corresponding documentation:

Step 3: Submit 3D Secure 2.0 authentication data to the issuer

Initiate 3D Secure 2.0 authentication with an /authorise3ds2 API request. Pass the threeDS2Token value, as well as the threeDSCompInd generated by the SDK.

In addition to the regular parameters you provide to Adyen, you can send all the parameters identified in the following list. All these parameters can be also provided when submitting authentication data for the issuer, but not after.

We advise you provide all the parameters you have to increase the likelihood of a frictionless flow and a higher authorization rate.

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

{
   "merchantAccount":"TestMerchant",
   "threeDS2RequestData":{
      "threeDSCompInd":"Y"
   },
   "threeDS2Token":"— - BINARY DATA - -"
}

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. This state serves as an indicator to proceed with the delivery of goods and services. 
  • ChallengeShopper – The issuer has requested further verification of 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).

For a complete list of resultCode values, see /authorise3ds2 response parameters.

{
   "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-2677777ae710",
      "threeds2.threeDS2ResponseData.authenticationType":"01",
      "threeds2.threeDS2ResponseData.dsTransID":"73aab3ce-eb39-49e8-8e9b-46fb77a472f1",
      "threeds2.threeDS2ResponseData.messageVersion":"2.1.0",
      "threeds2.threeDS2Token":"— - BINARY DATA - -",
      "threeds2.threeDS2ResponseData.acsTransID":"eb9c6eb3-57b3-400d-bf2f-4e72b779dcec",
      "threeds2.threeDS2ResponseData.acsReferenceNumber":"ADYEN-ACS-SIMULATOR"
   },
   "pspReference":"9935272408577755",
   "resultCode":"ChallengeShopper"
}

Step 4: Authenticate the shopper

Then you need to present a request for additional authentication to the shopper. After this authentication Adyen will receive the results of the shopper authentication with their issuer.

For more information, see Web SDK integrationiOS SDK integration, or Android 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

{
   "additionalData":{
      "threeds2.threeDS2ResponseData.transStatus":"Y",
      "threeds2.threeDS2ResponseData.authenticationValue":"- - BINARY DATA - -",
      "threeds2.threeDS2ResponseData.eci":"05"
   }
}

Step 6: Payment completion

If you receive ChallengeShopper, the 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, including the transStatus generated by the SDK, and the threeDS2Token that you received earlier.

Request

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

Response

You'll receive Authorised as the resultCode if the payment was successful.

{
   "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"
}

Next steps

Set up Web SDK

Proceed with Web SDK integration.

link

Set up Android SDK

Use the Android SDK for your mobile app.

link

Set up iOS SDK

Use the iOS SDK for your mobile app.

link