Issuin icon

Register a mobile SCA device

Use our Authentication SDK to register an iOS or Android device for out-of-band authentication of payments.

To enable out-of-band (OOB) authentication for your users, you must register their device as an SCA device. The registration associates your user's device with their card.

You can register devices for SCA using Adyen's Authentication SDK. To do so:

  1. Check SCA eligibility.
  2. Initiate the device registration from your server.
  3. Register the device.
  4. Finalize the registration from your server.

The following sections explain how to perform all the steps to register a user's device for SCA.

Requirements

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
    Expand view
    Copy link to code block
    Copy code
    Copy code
    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
    Expand view
    Copy link to code block
    Copy code
    Copy code
    lifecycleScope.launch {
    val availabilityResult: AvailabilityResult = adyenAuthentication.checkAvailability()
    if (availabilityResult is AvailabilityResult.Available) {
    availabilityResult.sdkOutput
    }
    }

    The function returns an sdkOutput.

  3. Pass the sdkOutput to your server.

You will use the sdkOutput when initiating the registration.

Initiate device registration

Registering the device is a one-off procedure. You can only register one device per payment instrument. If you register a new device for a card that already has a registered device, the previous device will be deregistered.

To start the device registration, make a POST /registeredDevices request from your server.

In the request, specify the following:

Request parameter Required Description
paymentInstrumentId yes The unique identifier of the card you want to register the device for.
name no The name of the SCA device that you are registering. You can use it to help your users identify the device. If you do not specify a name, Adyen automatically generates one.
strongCustomerAuthentication.sdkOutput yes Base64-encoded blob of data created in the previous step.
Initiate device registration
Expand view
Copy link to code block
Copy code
Copy code
curl https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices \
-H 'x-api-key: ADYEN_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, BSDR00000000000000000000001 is "Cardholder's iPhone". You can use this pair later to show the details, for example, when deregistering the device if the user doesn't specify a device name during registration.

Initiate device registration response
Expand view
Copy link to code block
Copy code
Copy code
{
"id": "BSDR00000000000000000000001",
"paymentInstrumentId": "PI00000000000000000000001",
"sdkInput": "eyJjaGFsbGVuZ2UiOiJiVlV6ZW5wek0waFNlQzFvVjBGSGRVaDNaVXc1UVE9PSJ9",
"success": true
}

Authenticate cardholder

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

Register the device

To register the device with the Authentication SDK:

  1. Authenticate the user by performing two-factor authentication (2FA).

  2. Trigger the SDK to start the device registration and pass sdkInput from step 2.

    Register device with SCA SDK
    Expand view
    Copy link to code block
    Copy code
    Copy code
    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.

  3. Pass sdkOutput to your server.

Finalize registration

To finalize the device registration:

  1. Make a PATCH /registeredDevices/{id} request from your server. Specify the following parameters:

    Parameter Parameter type Description
    id Path The unique identifier of the SCA device. You obtain this id after you initiate the device registration.
    paymentInstrumentId Body The unique identifier of the card you want to register the device for.
    strongCustomerAuthentication.sdkOutput Body Base64-encoded blob of data created in the previous step.
    Finalize device registration
    Expand view
    Copy link to code block
    Copy code
    Copy code
    curl https://balanceplatform-api-test.adyen.com/bcl/v2/registeredDevices/{id} \
    -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \
    -H 'content-type: application/json' \
    -X PATCH \
    -d '{
    "paymentInstrumentId": "PI00000000000000000000001",
    "strongCustomerAuthentication" : {
    "sdkOutput": "eyJhdHRlc3RhdGlvbk9iamVjdCI6Im8yTm1iWF..."
    }
    }'
  2. Verify that the response contains success true.

The registration is now complete. The user can start authenticating themselves for future operations using your app.

Next steps

Authenticate your users before authorizing operations.