Search

Are you looking for test card numbers?

Would you like to contact support?

Online-payment 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.

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

In a 3D Secure 2 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.

Step 1: 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 an authentication request with a POST /payments call containing the required 3D Secure 2 fields, recommended additional acquirer-related data, and the threeDS2RequestData.authenticationOnly parameter:

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

Request

curl https://checkout-test.adyen.com/v49/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",
    "number": "4917610000000000",
    "expiryMonth": "10",
    "expiryYear": "2020",
    "cvc": "737",
    "holderName": "S. Hopper"
  },
  "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
  },
  "channel": "web",
  "origin" : "https://your-company.com/",
  "returnUrl" : "https://your-company.com/checkout/",
  "merchantAccount":"YOUR_MERCHANT_ACCOUNT"
}'

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

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

Step 2: Get the 3D Secure 2 device fingerprint

If your server receives an IdentifyShopper resultCodeget the shopper's 3D Secure 2 device fingerprint. Otherwise, skip this step.

In the step where you submit the device fingerprinting result in a POST /payments/details request, include the threeDSAuthenticationOnly parameter.

  • threeDSAuthenticationOnlytrue

Request

{
  "details": {
    "threeds2.fingerprint": "eyJ0aHJlZURTQ29tcEluZCI6ICJZIn0="
  },
  "threeDSAuthenticationOnly": true,
  "paymentData": "PAYMENT_DATA..."
}

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.

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

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

Step 3: 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 and submit the results to Adyen.

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/details request. 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": "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"
   }
}

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.

Step 4: 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.

Optional: Provide additional acquirer-related data

If you are planning to authorize your transaction with another acquirer, we strongly recommend that you include additional acquirer-related data described below. This is to avoid authorisation 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.

  • 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.
  • 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.
  • 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 /payments call containing the required 3D Secure 2 fields, the acquirer fields listed previously, and the authenticationOnly parameter:

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

Request with additional acquirer-related information

curl https://checkout-test.adyen.com/v49/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,
    "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"
   },
  "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:

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

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

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 /payments/details request from your server and include the following parameters: 

  • threeDSAuthenticationOnlyfalse
  • details: Object that contains the 3D Secure authentication result. Include this if you received the AuthenticationFinished result code.
  • paymentData: The paymentData from the /payments response if you received the AuthenticationNotRequired result code, or from the /payments/details response if you received the AuthenticationFinished result code.

Sample request after completing an authentication

{
  "details": {
    "threeds2.challengeResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
  },
  "threeDSAuthenticationOnly": false,
  "paymentData": "PAYMENT_DATA"
}

Sample request if authentication was not required for the transaction

{
  "threeDSAuthenticationOnly": false,
  "paymentData": "PAYMENT_DATA"
}

Response

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

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

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

To test how your integration handles different 3D Secure 2 authentication scenarios, use our test card numbers.
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 Expiry Date Security Code (CVC/CVV/CID)
American Express 3714 4963 5398 431 03/2030 7373
Cartes Bancaires 4035 5014 2814 6300 03/2030 737
Diners 3056 9309 0259 04 03/2030 737
Discover 6011 1111 1111 1117 03/2030 737
JCB 3566 1111 1111 1113 03/2030 737
Mastercard 5454 5454 5454 5454 03/2030 737
UnionPay 6212 3456 7890 1232 03/2030 737
Visa 4917 6100 0000 0000 03/2030 737

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 will get this result code after you submit the 3D Secure 2 device fingerprinting result in a Native authentication, unless you specify a frictionless 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 Expiry Date Security Code (CVC/CVV/CID)
Visa 4212 3456 7891 0006 03/2030 737

To test the frictionless flow, in which you perform a fingerprint but no challenge, use the following test card number:

Card number Expiry Date Security Code (CVC/CVV/CID) Authentication scenario
5201 2815 0512 9736 03/2030 737 Fingerprint but no challenge

App-based integration

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

Card number Expiry Date Security Code (CVC/CVV/CID) Authentication scenario
5201 2855 6567 2311 03/2030 737 Basic text authentication
5201 2874 9905 2008 03/2030 737 Basic single select
5201 2815 9233 1633 03/2030 737 Basic multi select
5201 2888 2269 6974 03/2030 737 Basic out-of-band (OOB) authentication
5201 2895 0084 3268 03/2030 737 HTML OOB authentication
5201 2861 5377 1465 03/2030 737 App single select then text authentication

Other scenarios

Card number Expiry Date Security Code (CVC/CVV/CID) Scenario
4199 3500 0000 0002 03/2030 737 The card is not enrolled for 3D Secure transactions.
5201 2829 9900 5515 03/2030 737 There was a technical error.

Advanced scenarios

We recommend that you build your logic around the resultCode, but you can additionally use the following test cards to test scenarios involving different transStatus values:

Card number Scenario
5201 2815 0512 9736 Return ARes with transStatus=Y
5201 2812 6243 5268 Return ARes with transStatus=N
5201 2850 9382 3592 Return ARes with transStatus=A
5201 2828 2836 6351 Return ARes with transStatus=U
5201 2864 9681 6589 Return ARes with transStatus=R
5201 2846 7071 7533 Return ARes with transStatus=U and transStatusReason=06