Adyen-for-platform icon

Manage devices registered for SCA

View or deregister devices used for Strong Customer Authentication (SCA).

After you registered devices for Strong Customer Authentication (SCA), you can use our API to:

  • Get a list of registered devices
  • Associate payment instruments to a registered device
  • Deregister a device from a specific business account

    • Requirements

    Ensure that your API credential has the following role:

    • Bank SCA Webservice Role

    Get a list of registered devices

    After the device is registered, you use the API to get information about the SCA device connected to a specific business account such as the device ID, the name of the device, and the type of the device. This information can be helpful for building user interfaces or for checking the payment instrument's devices before associating more.

    To get a paginated list of the SCA devices registered for a specific business account:

    1. Make a GET /registeredDevices request. You can limit the amount of returned data by including the following query parameters:

      Query parameter Required Description
      paymentInstrumentId -white_check_mark- Limits the returned list to SCA devices registered for this business account.
      pageSize The number of items on a page. Default: 20. Maximum: 100.
      pageNumber The index of the page to retrieve. The index of the first page is 0 (zero). Default: 0.

      The following example shows a GET /registeredDevices request for the paymentInstrumentId PI00000000000000000000001.

    2. In the response, note the following parameters:

      Response parameter Description
      data An array that contains a list of registered SCA devices and their corresponding details.
      data.id The unique identifier of the registered SCA device.
      data.name The name of the SCA device. You can show this name to your user to help them identify the device.
      data.paymentInstrumentId The unique identifier of the business account for which the SCA device is registered.
      data.type ios, android, browser

    Associate business accounts to a registered device

    After you register a device, you can connect additional payment instruments to the device using the Configuration API. This enables a single device to handle authentication for multiple payment instruments. You can associate up to five payment instruments to a device per /registeredDevices/{deviceId}/associations API request. Each payment instrument can only be linked to one device.

    To add payment instruments to a registered device:

    1. From your server, initiate the association by making a POST /registeredDevices/{deviceId}/associations request with the user's device ID as a path parameter. In the request body, specify up to five payment instrument IDs in the ids array.

      The response contains a Base64-encoded string, which our Authentication SDKs uses to authenticate the requested association. You do not need to decode or validate this string.

    2. Pass the resulting sdkInput to your client.

    3. On your client, initialize the SDK and call the authenticate() method using the sdkInput from your server as an argument.

      The authenticate() method prompts the user to respond to a challenge, for example, Touch ID, Face ID, or the device password.

    4. Pass the authentication result to your server.

    5. On your server, finalize the association by making a PATCH /registeredDevices/{deviceId}/associations request using the device ID as a path parameter. In the request body, specify the following:

      Parameter Required Description
      ids -white_check_mark- An array of the payment instrument IDs that you want to associate. These IDs must be the same that you sent in the POST request in step 1.
      strongCustomerAuthentication.sdkOutput -white_check_mark- The data returned from the client-side authenticate() method.
      type -white_check_mark- The type of resource that you are associating with the SCA device.
      Possible value: PaymentInstrument

      If the association is successful, the API responds with a list of payment instrument IDs. To verify the association, get a list of registered devices for each of the payment instruments.

    Troubleshooting device association

    The following examples show some common issues you may encounter during the association process.

    The "Device limit reached, please delete a device and try again" error detail means that one or more of the payment instrument IDs in the POST /registeredDevices/{deviceId}/associations call is already linked to a device.

    Solution

    To avoid this error, all payment instrument IDs passed in the POST /registeredDevices/{deviceId}/associations call need to be deregistered.

    1. Get a list of registered devices.
    2. If the payment instrument has a device in its data array, deregister the device.

    After you have deregistered all of the payment instruments, retry the POST /registeredDevices/{deviceId}/associations request.

    The 422 "Challenge not found" error usually occurs when the client device ID for the challenge does not match the device ID in the PATCH /registeredDevices/{deviceId}/associations request.

    When a client authenticates using the Adyen SCA library, the library produces an sdkOuput that is specific to the client device. If you send an sdkOutput that does not correspond to the device that you want to associate, then you get a "Challenge not found" error.

    Solution

    Ensure that the device ID used in the initial POST /registeredDevices/{deviceId}/associations request matches the one used in the PATCH /registeredDevices/{deviceId}/associations request. As long as the IDs match between the POST and the PATCH, the "Challenge not found" error will be prevented.

    The client-side authenticate() method failed because the user canceled the challenge. This is similar to other client-side errors that can occur. These are standard errors for Webauthn. Go to Web IDL standard for a list of possible exception error names.

    Solution

    To avoid this error, tell your user before the authentication process begins that they are about to be asked to authenticate.

    To handle this error, return the user to the previous step and ask them to retry. You can reuse the same sdkInput when you retry authenticate() in the same session.

    Deregister a device from a business account

    You can deregister an SCA device from a business account by making a DELETE  /registeredDevices/{id} request. You can do this when, for example:

    • Your user will no longer use a registered device.
    • A registered device has been compromised.

    If the SCA device is associated with multiple business accounts, you must make a request for each business account.

    To deregister an SCA device from a business account:

    1. Get the ID of the device that you want to deregister.

    2. Make a DELETE  /registeredDevices/{id} request and include the following parameters:

      Parameter Type Required Description
      id Path -white_check_mark- The unique identifier of the SCA device that you want to deregister.
      paymentInstrumentId Query -white_check_mark- The unique identifier of the business account from which you want to deregister the device.

      The following example shows a request to deregister an SCA device with id BSDR00000000000000000000000001 from the paymentInstrumentId PI00000000000000000000001.

    3. Verify that you receive a 204 HTTP response with no content. This indicates that the request succeeded.