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 the  Checkout API API. If you are using the Direct API endpoint, refer to 3D Secure 2 Classic 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.

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, because you'll need it for API calls you make to the Adyen payments platform.
  2. Build your own payment form, or use one of our client-side solutions for collecting card details.
  3. Read our 3D Secure 2 integration guide.

Ways to trigger 3D Secure Authentication-only flow

There are two different triggers for 3D Secure Authentication-only flow. You can choose one of the options for your integration:

Submit a payment authentication request

Make a /payments request, specifying:

Parameter name Required Description
paymentMethod -white_check_mark- 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 -white_check_mark- Specify platform that you are using. Set to web, iOS, or Android.
authenticationData.authenticationOnly -white_check_mark- Set to true. Indicates that the transaction went through Authentication-only flow.
authenticationData.threeDSRequestData.nativeThreeDS -white_check_mark- Set to preferred. Indicates that your payment page can handle 3D Secure 2 transactions natively.
browserInfo -white_check_mark- 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 2 redirect authentication in case the transaction is routed to redirect flow. If your mobile integration is unable to generate this information, you can send the same data as in the code samples below.
    returnUrl -white_check_mark- In case of a 3D Secure 2 redirect flow, this is the URL where the shopper will be redirected back to after completing 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.
    authenticationData.attemptAuthentication Set to always. Perform 3D Secure authentication.

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

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

    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.

    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:

    • authenticationData.authenticationOnly: true

    For more information and detailed integration steps, refer to our 3D Secure 2 integration guides.

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

    You receive a response containing:

    If 3D Secure 2 redirect authentication is triggered instead, the result of the authentication is in additionalData.threeDAuthenticatedResponse.

    • resultCode: If the authentication process has finished, you receive AuthenticationFinished.
    • threeDS2Result.transStatus: Indicates the result of the authentication. The value Y means that authentication is successful. If you get another value, see the list of possible values to learn what it means.
    • threeDSPaymentData: You need this if you want to continue to authorise the payment.

    Get the 3D Secure 2 authenticated data

    After a successful authentication, you get 3D Secure 2 authentication data in the threeDS2Result object:

    Some issuers don't provide all fields; the Applies to column shows which issuers provide each field.

    Field Applies to
    authenticationValue All issuers
    dsTransID All issuers
    eci All issuers
    challengeCancel Cartes Bancaires
    challengeIndicator Cartes Bancaires
    exemptionIndicator Cartes Bancaires
    riskScore Cartes Bancaires
    transStatusReason Cartes Bancaires
    cavvAlgorithm Cartes Bancaires

    You can get this authentication data in the response of one of the following endpoints:

    If authentication is successful in the Perform the authentication flow step, you get a resultCode with the value of AuthenticationFinished in the /payments/details response.

    You can find the authentication data in this response.

    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 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 enroll 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 request containing the required 3D Secure 2 fields, the acquirer fields listed previously, and the authenticationData.authenticationOnly parameter.

    • authenticationData.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/v70/payments \
    -H "X-API-key: YOUR_API_KEY" \
    -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..."
        },
        "authenticationData": {
            "authenticationOnly":true,
            "threeDSRequestData": {
                "nativeThreeDS": "preferred"
            }
        },
        "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: Send a payment authorisation request with 3D Secure authentication data

    Make a POST  /payments request and include the required fields for the issuer.

    Field Issuers
    paymentMethod.type All issuers.
    For co-badged cards set to the scheme that authenticated the payment.
    mpiData.authenticationResponse All issuers
    mpiData.directoryResponse All issuers
    mpiData.cavv All issuers
    dsTransID All issuers
    mpiData.eci All issuers
    mpiData.threeDSVersion All issuers
    threeDS2RequestData.challengeIndicator Cartes Bancaires
    mpiData.cavvAlgorithm Cartes Bancaires
    mpiData.challengeCancel Cartes Bancaires
    mpiData.riskScore Cartes Bancaires
    additionalData.acquirerCode Cartes Bancaires.
    Set to "AdyenCartesBancaires".
    additionalData.scaExemption Cartes Bancaires
    shopperInteraction All issuers
    recurringProcessingModel All issuers

    Sample request

    Sample response

    You will receive an  Authorised resultCode if the payment authorization was successful. See  Result codes for a complete list of possible responses.

    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 95 days
    Visa 90 days

    When authentication isn't required

    You get an AuthenticationNotRequired result code in the /payments response when a transaction doesn't require 3D Secure authentication. If you get this code, you can proceed to authorise the payment with Adyen or any other PSP or acquirer.

    Check the authenticationNotRequiredReason value to learn why strong customer authentication (SCA) was not required.

    The list of possible values includes:

    Value Description
    MerchantInitiatedTransaction The payment is a subsequent transaction initiated by the merchant. The initial payment has gone through SCA and the shopper has agreed to subsequent merchant-initiated transactions.
    MOTO Mail order and telephone order (MOTO) transactions are not electronic payments. They don't require SCA.
    POS The point-of-sale payment is made with a secure payment terminal. SCA applies to online payments where the shopper is not present at a point-of-sale terminal.
    AcquirerNotInEEA The business is not located in the EEA, Monaco, or the UK.
    IssuerNotInEEA The issuer is not located in the EEA, Monaco, or the UK.
    NonFinancial Zero-value authorizations do not require SCA.
    No matching 3ds configuration Check the required parameters for your 3D Secure request to make sure they are correct.

    Testing 3D Secure 2

    To test how your integration handles different 3D Secure 2 authentication scenarios, you need to use a card number for the specific flow.

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

    • For native mobile integrations, use password: 1234
    • For web and mobile browser integrations, use password: password

    Depending on the authentication option, you can receive the following result codes:

    • RedirectShopper: you receive this result code if you are using the Redirect authentication flow.
    • IdentifyShopper: you receive this result code if you are using the Native authentication flow.
    • ChallengeShopper: you receive this result code after you submit the 3D Secure 2 device fingerprinting result in a Native authentication, unless you specify a frictionless flow.

    Depending on your integration, use the following test cards to simulate different authentication flows.

    Card Type Card Number Expiry Date Security Code (CVC/CVV/CID)
    American Express 3714 4963 5398 431 03/2030 7373
    Bancontact / Maestro 6703 4444 4444 4449 03/2030
    Bancontact / Visa 4871 0499 9999 9910 03/2030 737
    Cartes Bancaires / Visa Debit 4035 5014 2814 6300 03/2030 737
    Cartes Bancaires 4360 0000 0100 0005 03/2030 737
    China UnionPay (Credit) 6250 9470 0000 0014 03/2030 123
    China UnionPay (Debit) 6250 9460 0000 0016 03/2030 123
    Diners 3056 9309 0259 04 03/2030 737
    Discover 6011 1111 1111 1117 03/2030 737
    Maestro 5000 5500 0000 0029 03/2030 n/a
    Mastercard 5454 5454 5454 5454 03/2030 737
    Mastercard Credit 2222 4000 1000 0008 03/2030 737
    Visa 4917 6100 0000 0000 03/2030 737
    Visa Classic 4166 6766 6766 6746 03/2030 737

    Challenge without fingerprint

    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

    Fingerprint without challenge

    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

    Native authentication

    To test authentication scenarios for native mobile (app-based) integrations, 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 out-of-band (OOB) authentication
    5201 2861 5377 1465 03/2030 737 App single select then text authentication
    4917 6100 0000 0042 03/2030 737 Advanced: ACS sends an empty Challenge Response (CRes)
    4917 6100 0000 0067 03/2030 737 Advanced: Invalid content in the acsSignedContent field in Authentication Response (ARes)
    4917 6100 0000 0059 03/2030 737 Advanced: Challenge Response (CRes) timeout

    Technical error

    To test simulate an error due to a timeout during the 3D Secure 2 authentication on the issuer side, use the following test card:

    Card number Expiry Date Security Code (CVC/CVV/CID) Scenario
    5201 2829 9900 5515 03/2030 737 Depending on your configuration, the transaction might still proceed to a successful authorization.

    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

    See also