Authentication-only integration

In a 3D Secure 2 authentication-only flow, you perform the 3D Secure 2 authentication independently of the payment authorisation flow. When performing an authentication-only flow:

1. Submit a payment authentication request.
   The transaction can go through either a frictionless or a challenge authentication flow.
2. Perform the required authentication flow.
3. Get the 3D Secure 2 authenticated data.
4. Use the authenticated data to authorise the payment either with Adyen, or with another PSP or acquirer.

Some issuers are not yet ready to support 3D Secure 2, or have better authorization rates for 3D Secure 1. 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. This means that you should make sure that your integration can also handle a 3D Secure 1 redirect authentication.

If you do not want to automatically fall back to 3D Secure 1, contact our Support Team. However, note that if you are implementing 3D Secure for PSD2 compliance, not having a fallback implementation might negatively affect your authorization rates since SCA is required for authorization in some markets. See PSD2 SCA compliance guide for more information.

Before you begin

Before starting your integration:

1. Sign up for an Adyen test account at https://www.adyen.com/signup. 
2. Get your API Key. Save a copy, because you'll need it for API calls you make to the Adyen payments platform.
3. Build your own payment form, or use one of our client-side solutions for collecting card details.
4. Read our 3D Secure 2 integration guide.

Submit a payment authentication request

Make a /payments request, specifying:

Parameter name	Required	Description
paymentMethod		Object that contains the shopper's card information from your front end or client app. For higher authentication rates, we strongly recommend that you include the shopper's name in the holderName) field.
channel		Specify platform that you are using. Set to web, iOS, or Android.
threeDSAuthenticationOnly		Set to true.
additionalData.allow3DS2		Set to true. Indicates that your integration can handle native 3D Secure 2 authentication.
browserInfo		Object that contains information about the shopper's browser. Full object is required for channel web. For mobile integrations (channel iOS and Android), the userAgent and acceptHeader fields are required to indicate that your integration can handle 3D Secure 1 redirect authentication in case the transaction is is routed to 3D Secure 1. If your mobile integration is unable to generate this information, you can send the same data as in the code samples below.
returnUrl		In case of a 3D Secure 1 flow, this is the URL where the shopper will be redirected back to after completing 3D Secure 1 authentication. This URL can have a maximum of 1024 characters.
origin		Required for channel web. The URL of the page where you are loading the 3D Secure 2 Component from. The origin should not include subdirectories and a trailing slash. You can also get this by opening the browser console and calling window.location.origin. The origin can be a maximum of 80 characters.
shopperIP		The shopper's IP address. Required for channel web.
billingAddress		The cardholder's billing address.
shopperEmail		The cardholder's email address.

For higher authentication rates, we strongly recommend that you also include:

• Acquirer-related data. A mismatch of acquirer data between the authentication and authorisation requests can be a reason for issuing banks to refuse the transaction.
• Additional shopper information. Sending this data increases the likelihood of achieving a frictionless flow.

A sample request for channel: web using raw card data:

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

If the /payments response includes resultCode: AuthenticationNotRequired, this means that the transaction does not require 3D Secure authentication. You can proceed to authorise the payment with Adyen, or another PSP or acquirer. To know why authentication was skipped, check the authenticationNotRequiredReason parameter.

If the /payments response includes an action object, proceed to perform the required authentication flow.

Perform the authentication flow

If the /payments response contains an action object, the transaction will need to go through one of the 3D Secure authentication flows. Perform the required authentication flow using one of our client-side solutions.

Whenever you make a /payments/details request to submit the authentication results, also include:

• threeDSAuthenticationOnly: true

Sample /payments/details request to submit the device fingerprint:

{
  "details": {
    "threeds2.fingerprint": "eyJ0aHJlZURTQ29tcEluZCI6ICJZIn0="
  },
  "threeDSAuthenticationOnly": true,
  "paymentData": "Ab02b4c0!BQABAgCwjcD2GXFGrtIIpAzMyAVv4hnnVfN..."
}

You'll receive a response containing:

• resultCode: If the authentication process has finished, you receive AuthenticationFinished.
• threeDS2Result.transStatus: Indicates the result of the authentication. The value Y means that authentication was successful. If you get another value, see the list of possible values to learn what it means.

{
  "pspReference": "851576148477921K",
  "resultCode": "AuthenticationFinished",
  "merchantReference": "YOUR_ORDER_NUMBER",
  "paymentData": "Ab02b4c0!BQABAgA...==",
  "threeDS2Result": {
    "authenticationValue": "QURZRU4gM0RTMiBURVNUIENBVlY=",
    "dsTransID": "a3b86754-444d-46ca-95a2-ada351d3f42c",
    "eci": "05",
    "messageVersion": "2.1.0",
    "threeDSServerTransID": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
    "transStatus": "Y"
  }
}

Get the 3D Secure 2 authenticated data

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

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.

In your /getAuthenticationResult request, specify:

• merchantAccount: The merchant account that was used to process the authentication.
• pspReference: The pspReference from the /payments/details response.

{
  "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
  "pspReference": "851576148477921K"
}

The /getAuthenticationResult response contains the required authentication data:

{
  "threeDS2Result": {
    "authenticationValue": "QURZRU4gM0RTMiBURVNUIENBVlY=",
    "dsTransID": "a3b86754-444d-46ca-95a2-ada351d3f42c",
    "eci": "05",
    "messageVersion": "2.1.0",
    "threeDSServerTransID": "6edcc246-23ee-4e94-ac5d-8ae620bea7d9",
    "transStatus": "Y"
  }
}

Optional: Provide additional acquirer-related data

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

If you are unable to get these details from your acquirer, contact our 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 using 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 by making a /payments call containing the required 3D Secure 2 fields, the acquirer fields listed previously, and the threeDSAuthenticationOnly parameter.

• threeDSAuthenticationOnly: true

Request with additional acquirer-related information

curl https://checkout-test.adyen.com/v66/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
  },
  "threeDSAuthenticationOnly": true,
  "threeDS2RequestData": {
    "acquirerBIN": "YOUR_ACQUIRER_BIN",
    "acquirerMerchantID": "YOUR_ACQUIRER_MERCHANT_ID",
    "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"
}'

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 even though you started with an authentication-only request.

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

• threeDSAuthenticationOnly: false
• 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.

curl https://checkout-test.adyen.com/v66/payments/details \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
  "details": {
    "threeds2.challengeResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
  },
  "threeDSAuthenticationOnly": false,
  "paymentData": "PAYMENT_DATA"
}'

curl https://checkout-test.adyen.com/v66/payments/details \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
    "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.

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

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:

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

App-based integration

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

Other scenarios

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:

See also