Classic-integration icon

Authentication-only integration

Use Adyen as a standalone 3D Secure 2 provider. Perform only the 3D Secure 2 authentication with us and submit the payment authorisation later.

Adyen is no longer developing the Classic API integration

This page is for the Classic API (/authorise) integration, which we no longer accept new integrations with.

We strongly recommend switching to the newer 3D Secure authentication-only on Checkout API 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.

3D Secure 1 authentication-only fallback

It is possible that the authentication falls back to redirecting the shopper to the issuer's site. Therefore, we recommend that your integration also supports the redirect flow.

Before you begin

Before you begin to integrate, make sure you have followed the Get started with Adyen guide to:

  • Get an overview of the steps needed to accept live payments.
  • Create your test account.

After you have created your test account:

  1. Get your API Key. Save a copy as you'll need it for API calls you make to the Adyen payments platform.
  2. Install one of our Libraries to connect with the Adyen APIs. For more information on these steps, refer to Get started with Adyen.
  3. Read and understand the full guides for web-basediOS 3D Secure 2 SDK, or Android 3D Secure 2 SDK integration.

Web-based authentication only

In web-based authentication-only flow, you need to submit a payment authentication request. The response will indicate if the authentication follows a frictionless or challenge flow, depending on issuer logic.

Submit a payment authentication request

If you are planning to authorize your transaction with another acquirer after a successful authentication, we strongly recommend that you include additional acquirer-related data to avoid authorisation refusals. Issuing banks can refuse transactions if there is a mismatch of acquirer data between the authentication and authorisation requests.

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

  • threeDSAuthenticationOnlytrue

You can send additional parameters for better authorization rates, and to increase the chance of a frictionless flow. You do not have to send all the additional parameters. Send parameters that you know you can provide accurately, or that are mandatory in specific scenarios.

Request
{
  "amount":{
    "currency":"EUR",
    "value":1500
  },
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
  "reference":"TEST",
  "threeDS2RequestData":{
    "deviceChannel":"browser",
    "notificationURL":"https:\/\/www.example.com\/YOUR_3DS_NOTIFICATION_URL"
  },
  "threeDSAuthenticationOnly": 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":"en",
    "colorDepth":24,
    "screenHeight":723,
    "screenWidth":1536,
    "timeZoneOffset":0,
    "javaEnabled":false
  },
  "card":{
    "cvc":"737",
    "expiryMonth":"03",
    "expiryYear":"2030",
    "holderName":"Simon Hopper",
    "number":"4917610000000000"
  }
}
Response

You'll receive a response containing: 

  • resultCode: Perform the following depending on the result code you receive:

    • IdentifyShopper: Perform the corresponding 3D Secure device fingerprinting.
    • ChallengeShopper: Present the challenge flow. 
    • RedirectShopper: The payment is routed to 3D Secure 1, based on issuer performance.
    • AuthenticationNotRequired: You can already proceed to authorise the payment because the transaction does not require 3D Secure authentication. Check the authenticationNotRequiredReason parameter if you want to know why authentication was skipped.

      If after you receive the AuthenticationNotRequired result code you decide to continue the payment authorisation with Adyen, proceed to Authorise the payment with Adyen.

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

{
    "additionalData": {
        "threeds2.threeDSServerTransID": "f8062b92-66e9-4c5a-979a-f465e66a6e48",
        "threeds2.threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
        "threeds2.threeDSMethodURL": "https://pal-test.adyen.com/threeds2simulator/acs/threedsmethodURL.shtml"
    },
    "pspReference": "8835494629682519",
    "resultCode": "IdentifyShopper"
}

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

Get the 3D Secure 2 device fingerprint in a browser

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

In the step where you make a POST /authorise3ds2 request,  include the threeDSAuthenticationOnly parameter.

  • threeDSAuthenticationOnlytrue
Request
{
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "threeDS2RequestData":{
      "threeDSCompInd":"Y"
   },
   "threeDSAuthenticationOnly": true,
   "threeDS2Token":"BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=..."
}
Response

You'll receive a response containing a resultCode

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

{
   "additionalData" : {
      "threeds2.threeDS2Result.dsTransID": "780d3fab-c162-4f48-a249-a3ad...",
      "threeds2.threeDS2Result.eci" : "05",
      "threeds2.threeDS2Result.threeDSServerTransID" : "c4e59ceb-a382-4d6a-bc87-385d591fa09d",
      "threeds2.threeDS2Token" : "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
      "threeds2.threeDS2Result.authenticationValue" : "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
      "threeds2.threeDS2Result.transStatus" : "Y"
   },
   "pspReference" : "9935500720947721",
   "resultCode" : "AuthenticationFinished"
}

See our API reference to learn more about the response parameters and how the values map to 3D Secure specifications.

Present the challenge flow in a browser

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  request. Proceed to authorise the payment with Adyen instead.

After sending the challenge result with a POST /authorise3ds2 request and if the authentication was successful, you will get an AuthenticationFinished resultCode

Request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2Result": {
        "transStatus": "Y"
    },
    "threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=..."
}
Response
{
   "additionalData" : {
      "threeds2.threeDS2Result.dsTransID": "780d3fab-c162-4f48-a249-a3ad...",
      "threeds2.threeDS2Result.eci" : "05",
      "threeds2.threeDS2Result.threeDSServerTransID" : "c4e59ceb-a382-4d6a-bc87-385d591fa09d",
      "threeds2.threeDS2Token" : "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
      "threeds2.threeDS2Result.authenticationValue" : "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
      "threeds2.threeDS2Result.transStatus" : "Y"
   },
   "pspReference" : "9935500720947721",
   "resultCode" : "AuthenticationFinished"
}

See our API reference to learn more about the response parameters and how the values map to 3D Secure specifications.

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

Android 3D Secure 2 SDK authentication only

This section outlines the steps for implementing an authentication only flow on your Android app. First you will need to install our Android SDK, submit a payment authentication request, get the 3D Secure 2 device fingerprint, and present a challenge if required by the issuer.

Submit a payment authentication request

If you are planning to authorize your transaction with another acquirer after a successful authentication, we strongly recommend that you include additional acquirer-related data to avoid authorisation refusals. Issuing banks can refuse transactions if there is a mismatch of acquirer data between the authentication and authorisation requests.

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

  • threeDSAuthenticationOnlytrue

You can send additional parameters for better authorization rates, and to increase the chance of a frictionless flow. You do not have to send all the additional parameters. Send parameters that you know you can provide accurately, or that are mandatory in specific scenarios.

Request
Response

You'll receive a response containing: 

  • resultCode: Perform the following depending on the result code you receive:

    • IdentifyShopper: Perform the 3D Secure 2 device fingerprinting process.
    • RedirectShopper: The payment is routed to 3D Secure 1, based on issuer performance.
    • AuthenticationNotRequired: You can already proceed to authorise the payment because the transaction does not require 3D Secure authentication. Check the authenticationNotRequiredReason parameter if you want to know why authentication was skipped.

    If after you receive the AuthenticationNotRequired result code you decide to continue the payment authorisation with Adyen, proceed to Authorise the payment with Adyen.

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

{
    "additionalData": {
        "threeds2.threeDSServerTransID": "055fadfb-9fe4-4e70-99f0-9b8935bf1eb2",
        "threeds2.threeDS2DirectoryServerInformation.algorithm": "RSA",
        "threeds2.threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
        "threeds2.threeDS2DirectoryServerInformation.directoryServerId": "A000000003",
        "threeds2.threeDS2DirectoryServerInformation.publicKey": "eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsIm4iOiI4VFBxZkFQ==..."
    },
    "pspReference": "8835495304426403",
    "resultCode": "IdentifyShopper"
}

Get the 3D Secure 2 device fingerprint with an Android app

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

In the step where you make a POST /authorise3ds2 request,  include the threeDSAuthenticationOnly parameter.

  • threeDSAuthenticationOnlytrue
Request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2RequestData": {
        "deviceChannel": "app",
        "sdkAppID": "9063b12c-fcde-43c7-b28e-8d0af5520e8a",
        "sdkEncData": "<device-fingerprint>",
        "sdkEphemPubKey": {
            "crv": "P-256",
            "kty": "EC",
            "x": "LYImJkRzS92vogM6AUPCBhJ20VagSe8IL0Q9SdisUSo",
            "y": "Rav4sKHnLUIUHVdyR4dyV7G2_EeAnuCn_6621ZhqZYU"
        },
        "sdkReferenceNumber": "3DS_LOA_SDK_ADBV_739485_94783",
        "sdkTransID": "b60c9879-ac77-4918-a317-7b01c4317053"/8Q==.."
    "threeDSAuthenticationOnly": true
}
Response

You'll receive a response containing a resultCode:

For a complete list of resultCode values, see Result codes.

{
    "additionalData": {
        "threeds2.threeDS2ResponseData.acsSignedContent": "eyJhbGciOiJQUzI1NiIsIngPVEFOQmdrcWhraUc5dtw4I-RBJ8_OUt8yIZEsoc...",
        "threeds2.threeDS2ResponseData.transStatus": "C",
        "threeds2.threeDS2ResponseData.acsChallengeMandated": "Y",
        "threeds2.threeDS2ResponseData.acsURL": "https://pal-test.adyen.com/threeds2simulator/services/ThreeDS2Simulator/v1/handle/83e78317-e73f-4a6f-j738-7hj09p07n178",
        "threeds2.threeDS2ResponseData.threeDSServerTransID": "930h2k09-1986-4hl2-800a-c8d7783918bf",
        "threeds2.threeDS2ResponseData.authenticationType": "01",
        "threeds2.threeDS2ResponseData.messageVersion": "2.1.0",
        "threeds2.threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
        "threeds2.threeDS2ResponseData.acsTransID": "45e79886-e60c-4c6d-a962-7aa43d59b150",
        "threeds2.threeDS2ResponseData.acsReferenceNumber": "ADYEN-ACS-SIMULATOR"
    },
    "pspReference": "8825495326513370",
    "resultCode": "ChallengeShopper"
}

Present the challenge flow within your Android app

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  request. Proceed to authorise the payment with Adyen instead.

After sending the challenge result with a POST /authorise3ds2 request and If the authentication was successful, you will get a AuthenticationFinished resultCode

Request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2Result": {
        "transStatus": "Y"
    },
    "threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=..."
}
Response

You'll receive AuthenticationFinished as the resultCode if the transaction was successfully authenticated.

{
   "additionalData" : {
      "threeds2.threeDS2Result.dsTransID": "780d3fab-c162-4f48-a249-a3ad...",
      "threeds2.threeDS2Result.eci" : "05",
      "threeds2.threeDS2Result.threeDSServerTransID" : "c4e59ceb-a382-4d6a-bc87-385d591fa09d",
      "threeds2.threeDS2Token" : "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
      "threeds2.threeDS2Result.authenticationValue" : "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
      "threeds2.threeDS2Result.transStatus" : "Y"
   },
   "pspReference" : "9935500720947721",
   "resultCode" : "AuthenticationFinished"
}

See our API reference to learn more about the response parameters and how the values map to 3D Secure specifications.

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

iOS 3D Secure 2 SDK authentication only

This section outlines the steps for implementing an authentication only flow on your iOS app. First you will need to install our iOS SDK, submit a payment authentication request, get the 3D Secure 2 device fingerprint, and present a challenge if required by the issuer.

Submit a payment authentication request

If you are planning to authorize your transaction with another acquirer after a successful authentication, we strongly recommend that you include additional acquirer-related data to avoid authorisation refusals. Issuing banks can refuse transactions if there is a mismatch of acquirer data between the authentication and authorisation requests.

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

  • threeDSAuthenticationOnlytrue

You can send additional parameters for better authorization rates, and to increase the chance of a frictionless flow. You do not have to send all the additional parameters. Send parameters that you know you can provide accurately, or that are mandatory in specific scenarios.

Request
Response

You'll receive a response containing: 

  • resultCode: Perform the following depending on the result code you receive:

    • IdentifyShopper. Perform the 3D Secure 2 device fingerprinting process.
    • RedirectShopper: The payment is routed to 3D Secure 1, based on issuer performance.
    • AuthenticationNotRequired: You can already proceed to authorise the payment because the transaction does not require 3D Secure authentication. Check the authenticationNotRequiredReason parameter if you want to know why authentication was skipped.

    If after you receive the AuthenticationNotRequired result code you decide to continue the payment authorisation with Adyen, proceed to Authorise the payment with Adyen.

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

{
    "additionalData": {
        "threeds2.threeDSServerTransID": "055fadfb-9fe4-4e70-99f0-9b8935bf1eb2",
        "threeds2.threeDS2DirectoryServerInformation.algorithm": "RSA",
        "threeds2.threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
        "threeds2.threeDS2DirectoryServerInformation.directoryServerId": "A000000003",
        "threeds2.threeDS2DirectoryServerInformation.publicKey": "eyJrdHkiOiJSU0EiLCJlIjoiQVFBQiIsIm4iOiI4VFBxZkFQ==..."
    },
    "pspReference": "8835495304426403",
    "resultCode": "IdentifyShopper"
}

Get the 3D Secure 2 device fingerprint with an iOS app

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

In the step where you make a POST /authorise3ds2 request, include the threeDSAuthenticationOnly parameter.

  • threeDSAuthenticationOnlytrue
Request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2RequestData": {
        "deviceChannel": "app",
        "sdkAppID": "9063b12c-fcde-43c7-b28e-8d0af5520e8a",
        "sdkEncData": "<device-fingerprint>",
        "sdkEphemPubKey": {
            "crv": "P-256",
            "kty": "EC",
            "x": "LYImJkRzS92vogM6AUPCBhJ20VagSe8IL0Q9SdisUSo",
            "y": "Rav4sKHnLUIUHVdyR4dyV7G2_EeAnuCn_6621ZhqZYU"
            }
        },
        "sdkReferenceNumber": "3DS_LOA_SDK_ADBV_739485_94783",
        "sdkTransID": "b60c9879-ac77-4918-a317-7b01c4317053/8Q==..",
    "threeDSAuthenticationOnly": true
}
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. Perform the Challenge flow.

For a complete list of resultCode values, see Result codes.

{
    "additionalData": {
        "threeds2.threeDS2ResponseData.acsSignedContent": "eyJhbGciOiJQUzI1NiIsIngPVEFOQmdrcWhraUc5dtw4I-RBJ8_OUt8yIZEsoc...",
        "threeds2.threeDS2ResponseData.transStatus": "C",
        "threeds2.threeDS2ResponseData.acsChallengeMandated": "Y",
        "threeds2.threeDS2ResponseData.acsURL": "https://pal-test.adyen.com/threeds2simulator/services/ThreeDS2Simulator/v1/handle/83e78317-e73f-4a6f-j738-7hj09p07n178",
        "threeds2.threeDS2ResponseData.threeDSServerTransID": "930h2k09-1986-4hl2-800a-c8d7783918bf",
        "threeds2.threeDS2ResponseData.authenticationType": "01",
        "threeds2.threeDS2ResponseData.messageVersion": "2.1.0",
        "threeds2.threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
        "threeds2.threeDS2ResponseData.acsTransID": "45e79886-e60c-4c6d-a962-7aa43d59b150",
        "threeds2.threeDS2ResponseData.acsReferenceNumber": "ADYEN-ACS-SIMULATOR"
    },
    "pspReference": "8825495326513370",
    "resultCode": "ChallengeShopper"
}

Present the challenge flow in your iOS app

If your server receives 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 /authorise3ds2 request. Proceed to authorise the payment with Adyen instead.

After sending the challenge result with a POST /authorise3ds2 request and If the authentication was successful, you will get an AuthenticationFinished resultCode

Request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2Result": {
        "transStatus": "Y"
    },
    "threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=..."
}
Response

You'll receive AuthenticationFinished as the resultCode if the transaction was successfully authenticated.

{
   "additionalData" : {
      "threeds2.threeDS2Result.dsTransID": "780d3fab-c162-4f48-a249-a3ad...",
      "threeds2.threeDS2Result.eci" : "05",
      "threeds2.threeDS2Result.threeDSServerTransID" : "c4e59ceb-a382-4d6a-bc87-385d591fa09d",
      "threeds2.threeDS2Token" : "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
      "threeds2.threeDS2Result.authenticationValue" : "3q2+78r+ur7erb7vyv66vv\/\/\/\/8=",
      "threeds2.threeDS2Result.transStatus" : "Y"
   },
   "pspReference" : "9935500720947721",
   "resultCode" : "AuthenticationFinished"
}

See our API reference to learn more about the response parameters and how the values map to 3D Secure specifications.

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

Get the 3D Secure 2 authenticated data

To authorise a payment with 3D Secure 2 authentication, you need the following data:

Field Description
authenticationValue The value for the 3D Secure 2 authentication session. The returned value is a Base64-encoded 20- or 21-byte array.
dsTransID The unique transaction identifier assigned by the Directory Server to identify a single transaction.
eci The Electronic Commerce Indicator returned from the schemes for the 3D Secure 2 payment session.

You can get this data from the last API response with AuthenticationFinished resultCode.

Alternatively, you can get the authentication data by using our /getAuthenticationResult endpoint.

If you want to use the /getAuthenticationResult endpoint, contact our Support Team. This feature requires additional configuration on Adyen's end.

In your /getAuthenticationResult request, specify:

The /getAuthenticationResult response contains the required authentication data:

See our API reference to learn more about the response parameters and how the values map to 3D Secure specifications.

Optional: Provide additional acquirer-related data

Perform this step only if you are planning to authorize your transaction with another acquirer after a successful authentication. We strongly recommend that you include the additional acquirer-related data described below to avoid authorisations refusals from the issuing bank as a result of a mismatch of acquirer data between authentication and authorisation.

Get the following information from your acquirer. These information are part of the 3D Secure 2 enrollment process between your acquirer and card schemes.

If you are unable to get these values from your acquirer, contact Support Team.

  • acquirerBIN: Supported from API v49 and later. The acquiring BIN enrolled for 3D Secure 2. This string should match the value that you will use in the authorisation.

    If you are building a test integration, you can use the string 123456 in place of an actual acquirerBIN.

  • acquirerMerchantID: Supported from API v49 and later. The authorisation MID enrolled for 3D Secure 2. This string should match the value that you will use in the authorisation.

    If you are building a test integration, you can use the string 123456 in place of an actual acquirerMerchantID.

  • merchantName:Supported from API v49 and later. The merchant name that the issuer presents to the shopper if they get a challenge. We recommend to use the same value that you will use in the authorisation. Maximum length is 40 characters.

  • mcc: Supported from API v49 and later. The four-digit Merchant Category Code registered with the scheme for the same acquirerMerchantID sent in the request.

  • threeDSRequestorID: Required for Visa and Mastercard. Unique requestor ID assigned by the Directory Server when you enrol for 3D Secure 2.

  • threeDSRequestorName: Required for Visa and Mastercard. Unique requestor name assigned by the Directory Server when you enrol for 3D Secure 2.

Submit an authentication request with a /authorise call containing the required 3D Secure 2 fields, the acquirer fields listed previously, and the threeDSAuthenticationOnly parameter:

  • threeDSAuthenticationOnly: true

You can send additional parameters for better authorization rates, and to increase the chance of a frictionless flow. You do not have to send all the additional parameters. Send parameters that you know you can provide accurately, or that are mandatory in specific scenarios.

Request for web-based 3D Secure 2 authentication with additional acquirer-related data


{
  "amount":{
    "currency":"EUR",
    "value":1500
  },
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
  "reference":"TEST",
  "threeDS2RequestData":{
    "deviceChannel":"browser",
    "notificationURL":"https:\/\/www.example.com\/YOUR_3DS_NOTIFICATION_URL",
    "acquirerBIN": "YOUR_ACQUIRER_BIN",
    "acquirerMerchantID": "YOUR_ACQUIRER_MERCHANT_ID",
    "merchantName": "YOUR_MERCHANT_NAME",
    "mcc": "YOUR_MCC",
    "threeDSRequestorID": "YOUR_3DS_REQUESTOR_ID",
    "threeDSRequestorName": "YOUR_3DS_REQUESTOR_NAME"
  },
  "threeDSAuthenticationOnly": 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":"en",
    "colorDepth":24,
    "screenHeight":723,
    "screenWidth":1536,
    "timeZoneOffset":0,
    "javaEnabled":false
  },
  "card":{
    "cvc":"737",
    "expiryMonth":"03",
    "expiryYear":"2030",
    "holderName":"Simon Hopper",
    "number":"4917610000000000"
  }
}
Response

You'll receive a response containing:

To optimize authorization rates, Adyen's Authentication Engine routes each payment to either the 3D Secure 2 or the 3D Secure 1 flow, based on issuer performance. See 3D Secure fallback for more information.

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

{
    "additionalData": {
        "threeds2.threeDSServerTransID": "f8062b92-66e9-4c5a-979a-f465e66a6e48",
        "threeds2.threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=...",
        "threeds2.threeDSMethodURL": "https://pal-test.adyen.com/threeds2simulator/acs/threedsmethodURL.shtml"
    },
    "pspReference": "8835494629682519",
    "resultCode": "IdentifyShopper"
}

Optional: Authorise the payment with Adyen

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

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

  • threeDSAuthenticationOnlyfalse
  • threeDS2Token: The threeDS2Token from the /authorise response if you received the AuthenticationNotRequired result code, or from the /authorise3ds2 response if you received the AuthenticationFinished result code.
  • transStatus: Include this if you received the AuthenticationFinished result code.

    • For a browser-based integration, this is the transStatus from the base64url decoded CRes. If you did not receive a result to the threeDSNotificationURL within 10 minutes, assume that something went wrong or the shopper aborted the transaction. In this case, send transStatus: U to complete the authentication process.
    • For an app-based integration, this is the value generated by the SDK.
Sample request after completing an authentication
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2Result": {
        "transStatus": "Y"
    },
    "threeDSAuthenticationOnly": false,
    "threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=..."
}
Sample request if authentication was not required for the transaction
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDSAuthenticationOnly": false,
    "threeDS2Token": "BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=..."
}
Response

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

{
    "additionalData": {
        "liabilityShift": "true",
        "authCode": "44402",
        "avsResult": "4 AVS not supported for this card type",
        "threeDOffered": "true",
        "refusalReasonRaw": "AUTHORISED",
        "authorisationMid": "1000",
        "acquirerAccountCode": "TestPmmAcquirerAccount",
        "cvcResult": "1 Matches",
        "avsResultRaw": "4",
        "threeDAuthenticated": "true",
        "cvcResultRaw": "M",
        "acquirerCode": "TestPmmAcquirer",
        "acquirerReference": "7CASOGMCCB4"
    },
    "pspReference": "8825495331860022",
    "resultCode": "Authorised",
    "authCode": "44402"
}

Authentication data expiry

Authentication data and cryptograms expire depending on card schemes. This means that you can no longer use the authentication data after it expires.

Card scheme Cryptogram validity
Amex 45 days
CUP 90 days
Mastercard 30 days. Starting from 2020, Mastercard will support non-expiring cryptograms
but the expiry will depend on the issuing bank's implementation.
Visa 1 year

Testing 3D Secure 2

Before going live, use the following card numbers and credentials to test your integration.

We recommend testing each Card Type.

To test how your integration handles different 3D Secure 2 authentication scenarios, use our test card numbers.

All our test cards use the following expiry dates and security codes:

Expiry Date CVC/CVV CID
03/2030 737 7373

When prompted for 3D Secure 2 text challenges, use the following credentials:

  • For mobile, use password: 1234
  • For web, use password: password
Card Type Card Number
Cartes Bancaires 4035 5014 2814 6300
Maestro 1 5000 5500 0000 0029
Mastercard 5454 5454 5454 5454
Visa 4917 6100 0000 0000

1 This card doesn't require a CVC.

When you make a payment request with these cards, you'll receive the following result codes depending on your integration:

  • RedirectShopper: You'll receive this result code if you are using the Redirect authentication.
  • IdentifyShopper: You'll receive this result code if you are using the Native authentication.
  • ChallengeShopper: You might get this result code after you submit the 3D Secure 2 device fingerprinting result in a Native authentication, indicating a challenge flow.

To test the web-based flow where the device fingerprinting step is skipped (because the issuer's ACS has not configured a threeDSMethodURL), and you get a ChallengeShopper resultCode immediately after submitting the payment request, use the following card:

Card Type Card Number
Visa 4212 3456 7891 0006

To test the frictionless flow, specify in your payment request:

  • amount.value: 12002

App-based integration

To test different authentication scenarios for app-based integration, use the following test cards:

Card number Authentication scenario
5201 2855 6567 2311 Basic text authentication
5201 2874 9905 2008 Basic single select
5201 2815 9233 1633 Basic multi select
5201 2888 2269 6974 Basic out-of-band (OOB) authentication
5201 2895 0084 3268 HTML OOB authentication
5201 2861 5377 1465 App single select then text authentication

Other scenarios

Card number Scenario
4199 3500 0000 0002 The card is not enrolled for 3D Secure transactions,
5201 2829 9900 5515 There was a technical error.