Search docs

Are you looking for test card numbers?

Would you like to contact support?

Start searching Adyen's documentation...

  Documentation

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.

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

In case the issuer does not support 3D Secure 2, we will initiate a 3D Secure 1 fallback by default, indicated by a RedirectShopper resultCode response. To handle this scenario, implement our 3D Secure 1 authentication-only integration fallback.

If you do not want to automatically fall back to 3D Secure 1, contact Support Team. However, note that if you are implementing 3D Secure for PSD2, 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 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. Install one of our Libraries to connect with the Adyen APIs. For more information on these steps, refer to Get started with Adyen.
  4. 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 did not enrol your merchant ID (MID) with card schemes through Adyen (for example, you enrolled for 3D Secure 2 through a different acquirer or PSP), skip this step and proceed to include additional acquirer-related data instead.

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

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

You'll receive a response containing:

In case the issuer does not support 3D Secure 2, we will initiate a 3D Secure 1 fallback by default, indicated by a RedirectShopper resultCode. 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"
}

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 authenticationOnly parameter.

  • authenticationOnlytrue
Request
{
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "threeDS2RequestData":{
      "threeDSCompInd":"Y",
      "authenticationOnly": true
   },
   "threeDS2Token":"BQABAQBPCQZ98WKh3v7qGnBlUMGClVzDolIjs8w/8L64WIAqaOGZipbZod7n+E=..."
}
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.

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

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

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 did not enrol your merchant ID (MID) with card schemes through Adyen (for example, you enrolled for 3D Secure 2 through a different acquirer or PSP), skip this step and proceed to include additional acquirer-related data instead.

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

  • 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://pal-test.adyen.com/pal/servlet/Payment/v46/authorise \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
    "amount":{  
    "currency":"EUR",
    "value":1500
    },
    "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
    "reference":"YOUR_ORDER_NUMBER",
    "threeDS2RequestData":{  
      "deviceChannel":"app",
      "authenticationOnly": true
    },
    "card":{  
      "cvc":"737",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "holderName":"Card Holder",
      "number":"4212345678901245"
    }
  }'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR X-API-KEY"

response = adyen.authorise({
  "amount" => {
    "currency" => "EUR",
    "value" => 1500
  },
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT",
  "reference" => "YOUR_ORDER_NUMBER",
  "threeDS2RequestData" => {
    "deviceChannel" => "app",
    "authenticationOnly" => "true",
  },
  "card" => {
    "cvc" => "737",
    "expiryMonth" => "10",
    "expiryYear" => "2020",
    "holderName" => "Card Holder",
    "number" => "4212345678901245"
  }
})
// Set your X-API-KEY with the API key from the Customer Area.
Config config = new Config();
config.setApiKey("Your X-API-KEY"));
Client client = new Client(config);

Checkout checkout = new Checkout(client);
AuthoriseRequest authoriseRequest = new AuthoriseRequest();
Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(1500L);
authoriseRequest.setAmount(amount);
authoriseRequest.setReference("YOUR_ORDER_NUMBER");
authoriseRequest.setThreeDS2RequestData(new HashMap<String, String>());
authoriseRequest.putThreeDS2RequestData("deviceChannel", "app");
authoriseRequest.putThreeDS2RequestData("authenticationOnly", "true");
authoriseRequest.setCard(new HashMap<String, String>());
authoriseRequest.putCardItem("cvc", "737");
authoriseRequest.putCardItem("expiryMonth", "10");
authoriseRequest.putCardItem("expiryYear", "2020");
authoriseRequest.putCardItem("holderName", "Card Holder");
authoriseRequest.putCardItem("number", "4212345678901245");
authoriseRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
authoriseResponse response = checkout.authorise(authoriseRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR X-API-KEY");
$service = new \Adyen\Service\Authorise($client);

$params = array(
  "amount" => array(
    "currency" => "EUR",
    "value" => 1500
  ),
  "reference" => "YOUR_ORDER_NUMBER",
  "threeDS2RequestData" => array(
    "deviceChannel" => "app",
    "authenticationOnly" => "true"
  ),
  "card" => array(
    "cvc" => "737",
    "expiryMonth" => "10",
    "expiryYear" => "2020",
    "holderName" => "Card Holder",
    "number" => "4212345678901245"
  ),
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->authorise($params);
#Set your X-API-KEY with the API key from the Customer Area.
ady = Adyen.Adyen()
client = ady.client
client.xapikey = "YOUR X-API-KEY"

request = {}
request['amount'] = {
  "value": "1500", 
  "currency": "EUR"
}
request['threeDS2RequestData] = {
  "deviceChannel" = "app",
  "authenticationOnly" = "true"
}
request['reference'] = "YOUR_ORDER_NUMBER"
request['card'] = {                                    
  "cvc": "737",
  "expiryMonth": "10",
  "expiryYear": "2020",
  "holderName": "Card Holder",
  "number": "4212345678901245"
}
request['merchantAccount'] = "YOUR_MERCHANT_ACCOUNT"
result = self.ady.checkout.authorise(request)
// Set your X-API-KEY with the API key from the Customer Area.
var client = new Client ("YOUR-X-API-KEY", Environment.Test);
var checkout = new Checkout(client);

var amount = new Model.Checkout.Amount("EUR", 1500);
var details = new Model.Checkout.DefaultCardDetails{
  Cvc = "737",
  ExpiryMonth = "10",
  ExpiryYear = "2020",
  HolderName= "Card Holder",
  Number = "4212345678901245"
};
var threeds2requestdata = new Model.Checkout.threeDS2RequestData{
  deviceChannel = "app",
  authenticationOnly= "true"
};
var authoriseRequest = new Model.Checkout.AuthoriseRequest
{
  Reference = "YOUR_ORDER_NUMBER",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  Card = details,
  ThreeDS2RequestData = threeds2requestdata
};

var paymentResponse = checkout.Authorise(authoriseRequest); 
Response

You'll receive a response containing:

In case the issuer does not support 3D Secure 2, we will initiate a 3D Secure 1 fallback by default, indicated by a RedirectShopper resultCode. 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": "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 authenticationOnly parameter.

  • authenticationOnlytrue
Request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2RequestData": {
        "deviceChannel": "app",
        "authenticationOnly": true,
        "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==.."
}
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"
}

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 did not enrol your merchant ID (MID) with card schemes through Adyen (for example, you enrolled for 3D Secure 2 through a different acquirer or PSP), skip this step and proceed to include additional acquirer-related data instead.

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

  • 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://pal-test.adyen.com/pal/servlet/Payment/v46/authorise \
-H "X-API-key: [Your API Key here]" \
-H "Content-Type: application/json" \
-d '{
    "amount":{  
    "currency":"EUR",
    "value":1500
    },
    "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
    "reference":"YOUR_ORDER_NUMBER",
    "threeDS2RequestData":{  
      "deviceChannel":"app",
      "authenticationOnly": true
    },
    "card":{  
      "cvc":"737",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "holderName":"Card Holder",
      "number":"4212345678901245"
    }
  }'
# Set your X-API-KEY with the API key from the Customer Area.
adyen = Adyen::Client.new
adyen.api_key = "YOUR X-API-KEY"

response = adyen.authorise({
  "amount" => {
    "currency" => "EUR",
    "value" => 1500
  },
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT",
  "reference" => "YOUR_ORDER_NUMBER",
  "threeDS2RequestData" => {
    "deviceChannel" => "app",
    "authenticationOnly" => "true",
  },
  "card" => {
    "cvc" => "737",
    "expiryMonth" => "10",
    "expiryYear" => "2020",
    "holderName" => "Card Holder",
    "number" => "4212345678901245"
  }
})
// Set your X-API-KEY with the API key from the Customer Area.
Config config = new Config();
config.setApiKey("Your X-API-KEY"));
Client client = new Client(config);

Checkout checkout = new Checkout(client);
AuthoriseRequest authoriseRequest = new AuthoriseRequest();
Amount amount = new Amount();
amount.setCurrency("EUR");
amount.setValue(1500L);
authoriseRequest.setAmount(amount);
authoriseRequest.setReference("YOUR_ORDER_NUMBER");
authoriseRequest.setThreeDS2RequestData(new HashMap<String, String>());
authoriseRequest.putThreeDS2RequestData("deviceChannel", "app");
authoriseRequest.putThreeDS2RequestData("authenticationOnly", "true");
authoriseRequest.setCard(new HashMap<String, String>());
authoriseRequest.putCardItem("cvc", "737");
authoriseRequest.putCardItem("expiryMonth", "10");
authoriseRequest.putCardItem("expiryYear", "2020");
authoriseRequest.putCardItem("holderName", "Card Holder");
authoriseRequest.putCardItem("number", "4212345678901245");
authoriseRequest.setMerchantAccount("YOUR_MERCHANT_ACCOUNT");
authoriseResponse response = checkout.authorise(authoriseRequest);
// Set your X-API-KEY with the API key from the Customer Area.
$client = new \Adyen\Client();
$client->setXApiKey("YOUR X-API-KEY");
$service = new \Adyen\Service\Authorise($client);

$params = array(
  "amount" => array(
    "currency" => "EUR",
    "value" => 1500
  ),
  "reference" => "YOUR_ORDER_NUMBER",
  "threeDS2RequestData" => array(
    "deviceChannel" => "app",
    "authenticationOnly" => "true"
  ),
  "card" => array(
    "cvc" => "737",
    "expiryMonth" => "10",
    "expiryYear" => "2020",
    "holderName" => "Card Holder",
    "number" => "4212345678901245"
  ),
  "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
);
$result = $service->authorise($params);
#Set your X-API-KEY with the API key from the Customer Area.
ady = Adyen.Adyen()
client = ady.client
client.xapikey = "YOUR X-API-KEY"

request = {}
request['amount'] = {
  "value": "1500", 
  "currency": "EUR"
}
request['threeDS2RequestData] = {
  "deviceChannel" = "app",
  "authenticationOnly" = "true"
}
request['reference'] = "YOUR_ORDER_NUMBER"
request['card'] = {                                    
  "cvc": "737",
  "expiryMonth": "10",
  "expiryYear": "2020",
  "holderName": "Card Holder",
  "number": "4212345678901245"
}
request['merchantAccount'] = "YOUR_MERCHANT_ACCOUNT"
result = self.ady.checkout.authorise(request)
// Set your X-API-KEY with the API key from the Customer Area.
var client = new Client ("YOUR-X-API-KEY", Environment.Test);
var checkout = new Checkout(client);

var amount = new Model.Checkout.Amount("EUR", 1500);
var details = new Model.Checkout.DefaultCardDetails{
  Cvc = "737",
  ExpiryMonth = "10",
  ExpiryYear = "2020",
  HolderName= "Card Holder",
  Number = "4212345678901245"
};
var threeds2requestdata = new Model.Checkout.threeDS2RequestData{
  deviceChannel = "app",
  authenticationOnly= "true"
};
var authoriseRequest = new Model.Checkout.AuthoriseRequest
{
  Reference = "YOUR_ORDER_NUMBER",
  Amount = amount,
  MerchantAccount = "YOUR_MERCHANT_ACCOUNT",
  Card = details,
  ThreeDS2RequestData = threeds2requestdata
};

var paymentResponse = checkout.Authorise(authoriseRequest); 
Response

You'll receive a response containing:

  • resultCodeIdentifyShopper
In case the issuer does not support 3D Secure 2, we will initiate a 3D Secure 1 fallback by default, indicated by a RedirectShopper resultCode. See 3D Secure fallback for more information.

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 authenticationOnly parameter.

  • authenticationOnlytrue
Request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2RequestData": {
        "deviceChannel": "app",
        "authenticationOnly": true,
        "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==.."
}
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"
}

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

You'll need the following parameters to process the payment authorisation with another PSP or acquirer.

  • transStatus from device fingerprinting: This is the returned in the /authorise3ds2 response when you submit the encrypted device fingerprint for apps or the device fingerprinting result for the browser.
  • transStatus from challenge flow: If the transaction goes into a challenge flow, get this value returned in the /authorise3ds2response when you submit the challenge result. 
  • authenticationValue: This is returned in the /authorise3ds2response either in the frictionless flow after you complete device fingerprinting procedure or in the challenge flow.
  • threeDSServerTransID:  This is returned in the /authorise3ds2 response either in the frictionless flow after you complete device fingerprinting procedure or in the challenge flow.
  • eci: This is returned in the/authorise3ds2 response either in the frictionless flow after you complete device fingerprinting procedure or in a challenge flow.
  • messageVersion: This is returned in an /authorise or a /authorise3ds2 indicating a ChallengeShopper flow. The value should be 2.1.0.

Optional: Provide additional acquirer-related data

If you did not enrol your merchant ID (MID) with card schemes through Adyen (for example, you enrolled for 3D Secure 2 through a different acquirer or PSP), 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: The acquiring BIN enrolled for 3D Secure 2. This string should match the value that you will use in the authorisation.
  • acquirerMerchantID: The authorisation MID enrolled for 3D Secure 2. This string should match the value that you will use in the authoriSation.
  • merchantName: 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. Unique requestor ID assigned by the Directory Server when you enrol for 3D Secure 2.
  • threeDSRequestorName: Required for Visa. 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 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 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",
    "authenticationOnly": true,
    "acquirerBIN": "YOUR_ACQUIRER_BIN",
    "acquirerMerchantID": "YOUR_ACQUIRER_MERCHANT_ID",
    "merchantName": "YOUR_MERCHANT_NAME",
    "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":"en",
    "colorDepth":24,
    "screenHeight":723,
    "screenWidth":1536,
    "timeZoneOffset":0,
    "javaEnabled":false
  },
  "card":{  
    "cvc":"737",
    "expiryMonth":"10",
    "expiryYear":"2020",
    "holderName":"Card Holder",
    "number":"4212345678901245"
  }
}
Response

You'll receive a response containing:

In case the issuer does not support 3D Secure 2, we will initiate a 3D Secure 1 fallback by default, indicated by a RedirectShopper resultCode. 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 after completing the authentication flow you decide to proceed with payment authorisation with Adyen, you can still continue with a payment authorisation. Follow the steps below for a browser-based or an app-based flow.

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

  • transStatus: In 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 Adyen in order to complete the authentication process. In an app-based integration, this is the value generated by the SDK.
  • threeds2.threeDS2Token
  • threeDS2RequestData.authenticationOnlyfalse
Request
{
    "merchantAccount": "YOUR_MERCHANT_ACCOUNT",
    "threeDS2Result": {
        "transStatus": "Y"
    },
    "threeDS2RequestData":{
      "authenticationOnly": 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' rules. This means that you can no longer use the authentication data after it expires.

  • For Visa, cryptograms are valid for 1 year.
  • For Mastercard, cryptograms are valid for 30 days. Starting from 2020, Mastercard will support non-expiring cryptograms but the expiry will depend on the issuing bank's implementation.

Testing 3D Secure 2

Use the following test cards along with the amounts in the next table to test 3D Secure 2 authentication scenarios.

Card Type Card Number Expiry Month Expiry Year Security Code (CVC/CVV) When to use this card
Visa 4212 3456 7890 1245 10 2020 737 To test any 3D Secure 2 authentication scenario for Visa.
Mastercard 5212 3456 7890 1242 10 2020 737 To test any 3D Secure 2 authentication scenario for Mastercard.
Visa 4212 3456 7891 0006 10 2020 737 To test scenario where there is no threeDSMethodURL in a browser-based integration flow.

Specific authentication scenario

Amount Authentication scenario
12002 Frictionless
12100 Basic text authentication
12110 Basic single select
12120 Basic multi select
12130 Basic out-of-band (OOB) authentication
12140 HTML OOB authentication
12150 App single select then text authentication

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

  • For mobile, use password: 1234
  • For web, use password: password