Authentication only integration

Learn how to perform 3D Secure 2 authentication, retrieve the authentication data, and submit a separate payment authorisation request. 

This page describes authentication only integration for /payments API. If you are using a classic integration, see 3D Secure 2 Classic integration.


In an authentication only flow, you perform the 3D Secure 2 authentication independent of the payment authorisation flow. The transaction can go through either a frictionless or a challenge authentication flow. If the 3D Secure authentication is successful, you will get the authentication data that you will need to authorise the payment with another PSP or acquirer.

If after the authentication you decide to process the payment with us, we also provide a way so that you can continue with the payment authorisation with Adyen.

Before you begin

Before you can start accepting 3D Secure 2 authenticated transactions on browsers or in-app, make sure that you:

  1. Sign up for an Adyen test account at https://www.adyen.com/signup
  2. Get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.

  3. Read and understand the full 3D Secure 2 API integration guide

Integration steps

  1. Collect the shopper's card details and proceed to submit an authentication request.
  2. Use the resultCode from the response to determine your next action. For example, you might need to get the 3D Secure 2 device fingerprint, or present a challenge to the shopper, or both.
  3. If the transaction was successfully authenticated, get the 3D Secure 2 authenticated data that you will need to authorise the payment with another PSP or acquirer. Alternatively, you can also proceed to authorise the transaction with Adyen.

To test your integration, see Testing 3D Secure 2 in 3DS2 Checkout API integration.

Submit a payment authentication request

Submit a payment request with a /payments call. In addition to the required 3D Secure 2 objects, include the authenticationOnly parameter.

  • authenticationOnlytrue

    In addition to the regular parameters you provide to Adyen, send additional parameters in the following list. We recommend that you provide all available information to increase the likelihood of achieving a frictionless flow and a higher authorisation rate.

Request

curl https://checkout-test.adyen.com/v41/payments \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "reference":"YOUR_ORDER_NUMBER",
  "paymentMethod":{
    "type":"scheme",
    "encryptedCardNumber":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryMonth":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedExpiryYear":"adyenjs_0_1_18$MT6ppy0FAMVMLH...",
    "encryptedSecurityCode":"adyenjs_0_1_18$MT6ppy0FAMVMLH..."
  },
  "additionalData" : {
     "allow3DS2" : true
  },
  "threeDS2RequestData": {
    "authenticationOnly": true
   },
  "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":"nl-NL",
    "colorDepth":24,
    "screenHeight":723,
    "screenWidth":1536,
    "timeZoneOffset":0,
    "javaEnabled": true,
    "acceptHeader": "text/html" //Retrieve this from your sever.
  },
  "origin" : "https://your-company.com/",
  "returnUrl" : "https://your-company.com/checkout/",
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'

Response

You'll receive a response containing:

In addition to the regular parameters you provide to Adyen, send additional parameters in the following list. We recommend that you provide all available information to increase the likelihood of achieving a frictionless flow and a higher authorisation rate.

For a complete list of resultCode values and the actions that you need to do, see Result codes.

Sample response with IdentifyShopper resultCode
{
  "resultCode": "IdentifyShopper",
  "authentication": {
    "threeds2.fingerprintToken": "eyJ0aH..."
  },
  "details": [
    {
      "key": "threeds2.fingerprint",
      "type": "text"
    }
  ],
  "paymentData": "Ab02b4c0!..."
}

For a complete list of resultCode values and the actions that you need to take, see Result codes.

Get the 3D Secure 2 device fingerprint

If your server receives an IdentifyShopper resultCodeget the shopper's 3D Secure 2 device fingerprint.

In the step where you make a POST /payments/details request, include the authenticationOnly parameter.

  • authenticationOnlytrue

Request

{
  "details": {
    "threeds2.fingerprint": "eyJ0aHJlZURTQ29tcEluZCI6ICJZIn0="
  },
    "threeDS2RequestData":{
      "authenticationOnly": true
   },
  "paymentData": "YOUR_PAYMENT_DATA..."
}

Response

You'll receive a response containing a resultCode

  • AuthenticationFinished –  The authentication has been completed. Proceed to Get the authentication data.

  • ChallengeShopper – The issuer has requested further verification of the shopper. See Challenge flow.

For a complete list of resultCode values and the actions that you need to take, see Result codes.

{
   "pspReference" : "9935519735144470",
   "resultCode" : "AuthenticationFinished",
   "threeDS2Result" : {
      "authenticationValue" : "REVBREJFRUZDQUZFQkFCRUZGRkY=",
      "dsTransID" : "32d1bf18-63b6-4028-8d9f-627038b75bd7",
      "eci" : "05",
      "threeDSServerTransID" : "a4817781-d668-4534-8bc2-b27c34cbfbe5",
      "transStatus" : "Y"
   }
}

Present a challenge 

If your server receives a ChallengeShopper resultCode, this means that the issuer would like to perform additional checks in order to verify that the shopper is indeed the cardholder. Present the challenge flow to the shopper.

If after performing the challenge you decide to continue the payment authorisation with Adyen, skip the step where you send the results in a POST /payments/detailsrequest. Proceed to Authorise the payment with Adyen instead.

In the step where you send the challenge result in a POST /payments/details request, you will get an AuthenticationFinished resultCode if the authentication was successful.

Request

{
  "details": {
    "threeds2.challengeResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
  },
  "paymentData": "YOUR_PAYMENT_DATA"
}

Response

{
   "pspReference" : "9935519735144470",
   "resultCode" : "AuthenticationFinished",
   "threeDS2Result" : {
      "authenticationValue" : "REVBREJFRUZDQUZFQkFCRUZGRkY=",
      "dsTransID" : "32d1bf18-63b6-4028-8d9f-627038b75bd7",
      "eci" : "05",
      "threeDSServerTransID" : "a4817781-d668-4534-8bc2-b27c34cbfbe5",
      "transStatus" : "Y"
   }
}

Proceed to Get authentication data for the fields that you will need to pass on to your PSP or acquirer.

Authorise the payment with Adyen

If after completing the challenge flow you decide to proceed with authorising the payment with Adyen, you can still switch and continue with a payment authorisation.

Make a POST /payments/details request from your server and include the following parameters: 

  • authenticationOnlyfalse

Request

{
  "details": {
    "threeds2.challengeResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
  },
  "threeDS2RequestData":{
      "authenticationOnly": false
   },
  "paymentData": "YOUR_PAYMENT_DATA"
}

Response

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

{
    "pspReference": "8825495331860022",
    "resultCode": "Authorised"
}

Get the 3D Secure 2 authenticated data

After the transaction is successfully authenticated, get the following parameters to process the payment authorisation with another PSP or acquirer:

  • transStatus returned in the first /payments/details response if the resultCode is AuthenticationFinished. If the transaction goes through the challenge flow, set this value to C.
  • transStatus returned in the second /payments/detailsresponse after you submit the challenge result.

  • authenticationValue: This is returned in a /payments/detailsresponse if the resultCode is AuthenticationFinished.

  • threeDSServerTransID:  This is returned in a /payments/detailsresponse if the resultCode is AuthenticationFinished.

  • eci: This is returned in a /payments/detailsresponse if the resultCode is AuthenticationFinished.

  • dsTransID: This is returned in a /payments/detailsresponse if the resultCode is AuthenticationFinished.
  • messageVersion: The value should be 2.1.0.

Testing 3D Secure 2

 Here are some resources for testing 3D Secure 2 transactions:

  • Use the following test cards for 3D Secure 2:
    • 4212 3456 7890 1245
    • 5212 3456 7890 1242
  • To test specific scenarios, use the following amounts in minor units:
Amount Authentication scenario
12002 Frictionless
12100 Basic text authentication
12110 Basic single select
12120 Basic multi select
12130 Basic OOB authentication
12140 Basic HTML
12141 HTML OOB authentication
12150 App single select then text
  • For text challenges in an app-based integration, use 1234 for the password
  • For text challenges in a browser-based integration, use password.