Manage account holders

To get account holders, use the following endpoints:

• GET balancePlatforms/{id}/accountHolders: Get a list of the account holders in your marketplace. This endpoint returns a paginated list of account holders.
• GET /accountHolders/{id}: Get the details of an account holder, including their capabilities.
• GET /accountHolders/{id}/balanceAccounts: Get a list of the balance accounts of an account holder. This endpoint returns a paginated list of balance accounts.

To view the account holders in your Customer Area:

1. In the navigation menu, select the merchant account linked to your balance platform.

2. Select Platforms > Accounts & balances > Account holders.

3. In the account holder table, select an Account holder ID to open the Account holder details page.

The Account holder details page shows information such as:

• The status of the account holder
• Their balance accounts and available balances
• Their associated legal entities
• The ID and type of their uploaded document
• Their capabilities

Filter and search

In the Account holders page, you can find specific account holders by using the filter and search features.

Set a filter by using the buttons on the filter bar, located on top of the account holder table. For example, you can filter account holders based on their capabilities and the capability statuses.

Also, you can search for an account holder by using their name or ID. You can limit the scope of search results by applying filters before searching.

To search for an account holder:

1. In the Account holders page, select Search.
2. On the dropdown menu, select Account holder.
3. In the text field, enter account holder's data, such as:
   • ID
   • Reference
   • Name
   • Legal entity ID

The search window now shows any corresponding account holders.

Liable account holder

The liable account holder is the account holder related to your company's legal entity. You can view the details of the liable account holder in the Account holders page. To do this, select View liable account holder.

When you make a GET /accountHolders/{id} request, refer to the following response parameters in the capabilities object:

• allowed: Boolean that indicates whether the capability is allowed.
• verificationStatus: The status of the checks. The possible values are invalid, pending, rejected, or valid.
• problems array: When this array is not empty, this means that there are errors that you need to address. Refer to verification error codes for a list of verification errors.

To view the capabilities of an account holder in your Customer Area:

1. In the navigation menu, select the merchant account linked to your balance platform.

2. Perform one of the following:

   • Go to Platforms > Accounts & balances > Account holders and select an account holder ID from the table.

   • Search for an account holder by selecting Search. As a parameter, you can use the account holder ID, account holder reference, or the ID of the linked legal entity.

3. On the Account holder details page:

   • Whether the capabilities are allowed

   • Their verification status

Default capabilities are automatically requested when you create an account holder. However, if you need to request a specific capability, you must update the account holder and include the capabilities map.

In your PATCH /accountHolders/{id} request, set the capability that you are requesting as the key, and specify the following fields in the object:

• requested: Set this to true.
• requestedLevel: Set a capability level if required.

Here is an example of how to update an existing account holder to request the receivePayment capability. If you're requesting for multiple capabilities, add another set of key-value object.

You receive a response informing you that the capability has been requested and the verification status is pending.

To request a capability in your Customer Area:

1. In the navigation menu, select the merchant account linked to your balance platform.

2. Perform one of the following:

   • Go to Platforms > Accounts & balances > Account holders and select an account holder ID from the table.

   • Search for an account holder by selecting Search. As a parameter, you can use the account holder ID, account holder reference, or the ID of the linked legal entity.

3. On the Account holder details page, select + Request new capability in the Capabilities section.

4. From the dropdown menu, select a capability and, if applicable, its level.

5. Select Submit.

6. On the confirmation window, select Submit request.

The capability request is sent to Adyen for approval.

To disable a capability, make a PATCH /accountHolders/{id} request to update the capability. Set the enabled field to false.

To enable or disable capabilities in your Customer Area:

1. In the navigation menu, select the merchant account linked to your balance platform.

2. Perform one of the following:

   • Go to Platforms > Accounts & balances > Account holders and select an account holder ID from the table.

   • Search for an account holder by selecting Search. As a parameter, you can use the account holder ID, account holder reference, or the ID of the linked legal entity.

3. On the Account holder details page, select Edit in the Capabilities section.

4. In the Enabled column:

   • Select the corresponding checkbox to enable the capability.

   • Clear the corresponding checkbox to disable the capability.

5. Select Save.

6. On the confirmation window, select Save changes.