Issuin icon

Manage account holders

Learn how to manage account holders on your platform.

Here we explain how to manage your account holders and what they can do in your platform.

View account holders

To view account holder details, you can either make an API request or use your Balance Platform Customer Area. The following tabs explain both methods.

To view the account holders in your Balance Platform Customer Area:

  1. Select Accounts & balances > Account holders.

  2. 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.

View KYC summary and timeline

You can view information about the verification process for account holders in your issuing. This includes an overview of the current verification status for associated legal entities and a timeline of KYC-related events. You can use this information to help your users troubleshoot issues they experience during the onboarding process.

  1. In your Balance Platform Customer Area, go to Accounts & balances > Account holders.
  2. On the Account holders page, select Search at the top right corner to search by account holder ID, reference, legal entity ID or name.
  3. In the search window, select View account holder to open the Account holder details page.
  4. Select KYC timeline.

The KYC summary section shows the current status of the KYC checks separated by the type of check, for example Identity. If there are multiple legal entities linked to the account holder, the type of each legal entity is specified, for example Individual.

Here are possible values of the KYC verification status of the legal entity.

Verification status
 Description
Awaiting data The KYC information for the legal entity has not yet been submitted.
In review The KYC information for the legal entity is being reviewed by Adyen.
Verified The KYC verification checks for the legal entity have passed.
Unsuccessful The KYC verification checks for the legal entity have failed. For example, because of an invalid document or ID number.
Review the KYC Timeline for more information about the verification errors and recommended remediating actions. To be verified, all the errors must be resolved.
Rejected The legal entity has been rejected by Adyen. For example, because the organization is in a sanctions list.
This status is final and any errors cannot be resolved by updating data or uploading documents.

To view more detailed information about the order of the KYC checks and events that affected the verification process, look at the KYC timeline. You can filter events by the type of check, legal entity ID, and legal entity name. The timeline also includes any verification errors and the corresponding remediating action codes.

View KYC documents

To access the KYC documents tab, you must have the following roles assigned to you:

  • View KYC documents
  • Download KYC documents

Consider the privacy implications before granting these roles to any platform user.

Based on your role, you may view only or view and download the documents that account holders have uploaded during their onboarding process for verification checks.

  1. In your Balance Platform Customer Area, go to Accounts & balances > Account holders.
  2. On the Account holders page, select Search at the top right corner to search by account holder ID, reference, legal entity ID or name.
  3. In the search window, select View account holder to open the Account holder details page.
  4. Select KYC documents.

You can use this information to help your users resolve verification errors they experience during the onboarding process, such as expired documents or a mismatch between the legal and organization names.

Apply filters by document type, file name, and associated legal entity ID to get the information you need.

View capabilities

View an account holder's capabilities and their verification status in your Balance Platform Customer Area or by making a GET /accountHolders/{id} request. The following tabs explain both methods.

To complete the following steps, you must have the Manage account holder capabilities user role.

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

  1. Perform one of the following:

    • Go to 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.

  2. On the Account holder details page:

    • Whether the capabilities are allowed

    • Their verification status

Request a capability

Some capabilities are automatically requested when you create an account holder However, your account holders may need additional capabilities if, for example, your business expands its financial product offering. In these cases, you must request the additional capabilities.

The following tabs show how to request a capability.

To complete the following steps, you must have the Manage account holder capabilities user role.

To request a capability in your Balance Platform Customer Area:

  1. Perform one of the following:

    • Go to 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.

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

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

  4. Select Submit.

  5. On the confirmation window, select Submit request.

The capability request is sent to Adyen for approval.

Enable or disable a capability

To allow or prevent an account holder from using a capability, update the capability in your Balance Platform Customer Area or request a PATCH /accountHolders/{id}. The following tabs explain both methods.

To complete the following steps, you must have the Manage account holder capabilities user role.

To enable or disable capabilities in your Balance Platform Customer Area:

  1. Perform one of the following:

    • Go to 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.

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

  3. In the Enabled column:

    • Select the corresponding checkbox to enable the capability.

    • Clear the corresponding checkbox to disable the capability.

  4. Select Save.

  5. On the confirmation window, select Save changes.

Your changes will show in the page after a few seconds.

Update an account holder

After you create an account holder resource, you might need to update the resource at a later time. For example, an account holder that has several balance accounts might want to change their primary balance account.

To update an account holder, make a PATCH /accountHolders/{id} request.

The example below shows how you can change the primary balance account of an account holder by sending the primaryBalanceAccount field.

Permanently deactivate account holders and their balance accounts

When an account holder discontinues their business, you can permanently deactivate them from your issuing.

In some scenarios, you might also want to close a balance account but keep the account holder active. For example, an account holder that has separate balance accounts for their businesses might want to only close one of their businesses.

To close balance accounts and account holders:

  1. Check if they have zero balance in their balance accounts. You can only close empty balance accounts, so if there are funds left, transfer any remaining balance.
  2. Close balance accounts by updating each balance account and setting the status to Closed. Start with those that are not the primary balance account. You can only close a primary balance account if the account holder's other balance accounts are already closed.
  3. Finally, permanently deactivate the account holder by updating the account holder and setting the status to Closed.