Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em português
Issuin icon

Using out-of-band authentication SDK

Learn how to implement our SDK for out-of-band (OOB) authentication.

This feature is in the development phase. Some of the APIs, documentation, and processes may change as the feature evolves. If you have any feedback, reach out to your Adyen contact.

Out-of-band authentication is a type of two-factor authentication that requires a secondary verification method through a separate communication channel. With out-of-band authentication, you can direct the transaction authentication requests to your secure application on an eligible cardholder's device. For example, a mobile phone.

To use the out-of-band authentication flow with your Adyen-issued cards in the European Economic Area (EEA), you need to register the cardholder's device and subsequently authenticate the transactions on this device.

We provide a client-side Authentication SDK that uses the possession factor through device binding, and either knowledge or the inherence factor, depending on the cardholder's device access configuration.

With Adyen's Authentication SDK, you can:

  • Check if the cardholder's device is eligible for Strong Customer Authentication (SCA).
  • Register your cardholder's mobile device to create device binding.
  • Authenticate your cardholder's online card transactions with 3D Secure.

The Authentication SDK integration also works with Adyen's Business Accounts to authenticate funds transfer and transaction lookup.

System requirements

We provide the client-side Authentication SDK in the following languages:

  • Kotlin or Java for Android applications
  • Swift for iOS applications

Before you start implementing the SDK, make sure that your system follows the requirements.

  • Your application targets minimum Android API level 21 or later.
  • The authentication feature works on devices running on Android API level 26 and later.
  • The authentication feature requires Google Play Services on the cardholder's device.

To ensure the correct support type for 3D Secure on the card program, contact our Support Team.

Installation

To install the Authentication SDK:

  1. Add the following line to your build.gradle file.
    implementation "com.adyen.authentication:android-authentication:0.1.0"

Register device

Before starting the device registration, make sure that the operating system on the cardholder's device supports SCA.

Step 1. Check SCA eligibility

This functionality requires additional configuration from Adyen. To enable it, contact our Support Team.
To check if the Android device is eligible for SCA:
  1. Initiate the AdyenAuthentication class in your Activity or Fragment.
    Initiate authentication
    private lateinit var adyenAuthentication: AdyenAuthentication
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        adyenAuthentication = AdyenAuthentication(this)
    }
  2. Check if SCA is available on the device.
    Check SCA eligibility
    lifecycleScope.launch {
        val availabilityResult: AvailabilityResult = adyenAuthentication.checkAvailability()
        if (availabilityResult is AvailabilityResult.Available) {
            availabilityResult.sdkOutput
        }
    }
    The output contains sdkOutput that you will use when initiating the registration.
  3. Pass sdkOutput to your server. We suggest that you store sdkOutput for further usage, in case you need to start the registration process again.

Step 2. Initiate device registration


Registering the device is a one-off procedure. You can only register one device per cardholder.

To start the device registration:

  1. From your server, make a POST /registeredDevices request. To make this request, your API credential needs the following role:
    • Bank SCA Webservice Role
    Reach out to you Adyen contact to set it up for you. In the request, specify the following:
    Parameter Description
    paymentInstrumentId The unique identifier of the payment instrument you want to register the device for.
    strongCustomerAuthentication.sdkOutput Base64-encoded blob of data created in the previous step.
    Initiate device registration
    curl https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices \
    -H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
    -H "content-type: application/json" \
    -X POST \
    -d '{
        "paymentInstrumentId": "PI00000000000000000000001",
        "strongCustomerAuthentication" : {
            "sdkOutput": "eyJjaGFubmVsIjoiYXBwIiwib3BlcmF0aW5nU3lzdGV..."
        }
    }'
    The response returns: We suggest that you create and store a mapping between the registered device id and the human-readable account holder name. For example, RD00000000000000000000001 is "Cardholder's iPhone". You can use this pair later to show the details, for example, when unbinding the device.
    Initiate device registration response
    {
        "id": "RD00000000000000000000001",
        "paymentInstrumentId": "PI00000000000000000000001",
        "sdkInput": "eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNlQzFvVjBGSGRVaDNaVXc1UVE9PSJ9",
        "success": true
    }

Step 3. Authenticate cardholder

In your client app, perform cardholder authentication. PSD2 requires you to perform two-factor authentication (2FA) as an extra security step during the login process.

Step 4. Register the device

After you successfully authenticate your cardholder:

  1. Trigger the SDK to start the device registration and pass sdkInput from step 2.
    Register device with SCA SDK
    lifecycleScope.launch {
      val registrationResult: AuthenticationResult = adyenAuthentication.register("sdkInput")
      when (registrationResult) {
          is AuthenticationResult.RegistrationSuccessful -> {
              registrationResult.sdkOutput
          }
          is AuthenticationResult.Canceled -> {
              // cardholder canceled the flow
          }
          is AuthenticationResult.Error -> {
              // Unexpected error
              registrationResult.errorMessage
          }
          is AuthenticationResult.AuthenticationError -> {
              // FIDO API Error
              registrationResult.authenticationError
          }
      }
    }
    After the successful registration, the SDK generates a Base64-encoded sdkOutput data blob.
  2. Pass sdkOutput to your server.

Step 5. Finalize registration

To finalize the device registration:

  1. From your server, make a PATCH /registeredDevices/{id} request, specifying the device id in the path and the following parameters in the request body:
    Parameter Description
    paymentInstrumentId The unique identifier of the payment instrument you want to register the device for.
    strongCustomerAuthentication.sdkOutput Base64-encoded blob of data created in the previous step.
    Finalize device registration
    curl https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices/{id} \
    -H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
    -H "content-type: application/json" \
    -X PATCH \
    -d '{
      "paymentInstrumentId": "PI00000000000000000000001",
      "strongCustomerAuthentication" : {
          "sdkOutput": "eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..."
      }
    }'
    The response contains success true.

The registration is now complete. The cardholder can start authenticating future transactions using your app.

Authenticate cardholder

Each time your cardholder makes a transaction that requires 3D Secure, you need to authenticate them.

Step 1. Set up a webhook endpoint

Your integration must be able to receive and process notifications for authentication requests.

  1. Create an endpoint on your server that:

    • Can receive a JSON object.
    • Has an open TCP port for HTTPS traffic on port 443, 8443, or 8843.
    • Can handle basic authentication.
  2. Send the endpoint URL to your Adyen contact.

To learn more about setting up webhooks, see Set up notification webhooks.

Step 2. Accept authentication webhooks

When the cardholder makes a transaction that requires authentication, we send a webhook to your server. Your server must respond to the webhook within 10 seconds. Otherwise, the authentication process will fail. The webhook contains the following parameters:

In the request header:

Parameter Description
sdkInput Base64-encoded blob of data to be passed to the SDK in the next step.

In the request body:

Parameter Description
id A unique reference of the 3D Secure challenge.
paymentInstrumentId The unique identifier of the payment instrument. Use this field to direct the authentication request to the correct cardholder.
purchase An object containing the details of the purchase.
Authentication webhook
{
  "id": "778a7bd0-0f08-4d0b-b6ec-76c3a47f775c",
  "paymentInstrumentId": "PI3227J223222B5F3FXD4B5MJ",
  "purchase": {
    "date": "2022-06-22T08:00:00.000000+02:00",
    "merchantName": "Merchant",
    "originalAmount": {
      "value": "1000",
      "currency": "EUR"
    }
  }
}

To ensure that your server has accepted the notification, we require you to acknowledge every notification with an HTTP 200 response containing the following:

{
   "authenticationDecision": {
      "status": "proceed"
   }
}

If we don't receive the response message within 10 seconds or receive status set to refused, the authentication process will stop.

For more information about webhook setup and best practices, see Set up notification webhooks.

Step 3. Authenticate cardholder

Your application must display the data from the previous step to the cardholder during the authentication. We recommend that you implement a push notification and use the data from the webhook notification to inform the cardholder about the details of the transaction they are authenticating for.

After being prompted on the merchant interface, the cardholder proceeds to the application.

Authenticate your cardholder using the SDK. To do so:

  1. Trigger the SDK to start cardholder authentication and pass the sdkInput value from the previous step.

    Authenticate cardholder using the SDK
    lifecycleScope.launch {
      if (adyenAuthentication.hasCredential("sdkInput")) {
          // Authenticate existing credential
          val authenticationResult: AuthenticationResult = adyenAuthentication.authenticate("sdkInput")
          when (authenticationResult) {
              is AuthenticationResult.AuthenticationSuccessful -> {
                  authenticationResult.sdkOutput
              }
              is AuthenticationResult.Canceled -> {
                  // cardholder cancelled the authentication flow
              }
              is AuthenticationResult.Error -> {
                  // Unexpected error
                  authenticationResult.errorMessage
              }
              is AuthenticationResult.AuthenticationError -> {
                  // FIDO API Error
                  authenticationResult.authenticationError
              }
          }
      } else {
          // None of the existing credentials exist in this device
      }
    }

    If successful, the result is a Base64-encoded sdkOutput data blob.

    In case of any error that occurs at this stage, return to the check SCA eligibility step and perform the registration steps again.

  2. Pass sdkOutput to your server.

Step 4. Finalize authentication

To finalize the successful authentication:

  1. From your server, make a PATCH /challenges request, specifying the following parameters:

    In the path:

    Parameter Description
    id The challengeReference value from the notification in Step 2.

    In the request header:

    Parameter Description
    WWW-Authenticate Set SCA realm to Challenge. Set auth-param1 with the Base64-encoded value of sdkOutput from cardholder authentication.

    In the request body:

    Parameter Description
    completed Set to true.
    Finalize authentication
    curl https://balanceplatform-api-live.adyen.com/acs/v1/challenges/{id} \
    -H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
    -H "content-type: application/json" \
    -H "WWW-Authenticate: SCA realm="Challenge" auth-param1="eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNlQzF..."" \
    -X PATCH \
    -d '{
      "completed": true
    }'

    If successful, the response contains the id of the challenge and challengeCompleted: true.

    {
        "id": "778a7bd0-0f08-4d0b-b6ec-76c3a47f775c",
        "challengeCompleted": true
    }

Próximas etapas

Learn about the payment stages and authorisation in particular.