Account holder are the main API resource that represent users of your platform. It contains the legal entities and balance accounts of the user. The object also contains information about the user's capabilities. To manage account holders, use the Configuration API.
This page contains instructions for common account holder operations. These operations are part of a larger process which includes verification and onboarding steps.
Create an account holder
You can create account holders using the Configuration API. To create an account holder, you need to create a legal entity first.
-
Make a POST /accountHolders request using a legal entity ID. For sole proprietorships, this is the individual legal entity ID of the owner.
-
In the response, note the unique
id
of the newaccountHolder
resource as well as a capabilities object with the default capabilities. Save the response because you need it to:- Match the incoming webhooks using the
id
. - Create a balance account for the account holder.
- Update the account holder.
- Match the incoming webhooks using the
-
Listen to balancePlatform.accountHolder.updated webhooks. After Adyen has verified the new account holder, webhooks inform your integration of the resulting verification statuses of the account holder's capabilities. Webhooks contain the updated capabilitiy object with verification codes.
View account holders
To view account holder details, you can either use your Customer Area or make an API request.
Update an account holder
After you create an account holder resource, you may need to update it at a later time. For example, when an an account holder with multiple balance accounts wants 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. -
Receive the response with the updated account holder object.
Deactivate account holders
When an account holder discontinues their business, you can permanently deactivate them and their balance accounts from your platform.
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:
-
Check if they have zero balance in their balance accounts. You can only close empty balance accounts, so if there are funds left, you must pay out or transfer any remaining balance.
-
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. -
Finally, permanently deactivate the account holder by updating the account holder and setting the
status
to Closed.
View capabilities
View an account holder's capabilities and their verification status in your Customer Area or by making a GET /accountHolders/{id} request. The following tabs explain both methods.
Request a capability
Some capabilities are automatically requested when you create an account holder. However, your account holders may need additional capabilities. For example, if 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.
Enable or disable a capability
To allow or prevent an account holder from using a capability, update the capability in your Customer Area or request a PATCH /accountHolders/{id}. The following tabs explain both methods.
Manage KYC
The Know Your Customer (KYC) checks are part of the verification process that Adyen performs to make sure that account holders have provided accurate information about their businesses.
In your Customer Area you can access a KYC summary and a detailed timeline of the entire verification process. You can also view and download any documents that account holders have uploaded.
View KYC summary and timeline
You can view information about the verification process for account holders in your platform. 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.
To view KYC summary and timeline information in your Customer Area:
-
In the navigation menu, select the merchant account linked to your balance platform. Do one of the following:
- Go to 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.
- On the Account holder details page, 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.
Possible KYC verification statuses for a 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 View KYC documents and Download KYC documents roles. Consider the privacy implications before granting these roles to any 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.
In your Customer Area:
-
In the navigation menu, select the merchant account linked to your balance platform. Do one of the following:
- Go to 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.
- On the Account holder details page, 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.