Here we explain how you can manage your account holders and what they can do in your platform.
View account holders
To view account holders details, you can either make an API request or use your Balance Platform Customer Area. The following tabs explain both methods.
To get account holders, use the following endpoints:
- GET /balancePlatforms/{id}/accountHolders: Get a list of the account holders in your platform. 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.
View legal entity details
To view the legal entity details of an account holder in your Balance Platform Customer Area, you can search for the account holder associated to the legal entity. As an alternative:
- Go to Accounts & balances > Account holders.
- In the account holder table, select an Account holder ID.
- In the Account holder details page, select Overview > Legal entity.
The Legal entity details of the main legal entity are shown. You can view bank account information for the main legal entity under Transfer instruments.
If the legal entity is an organization, the page also shows details about the associated legal entities under Entity associations.
If the legal entity is an individual or a sole proprietorship, their personally identifiable information (PII) is redacted. Personally identifiable information includes their:
- Name
- Address (except for the country)
- Date of birth
- Email address
- Phone number
- IBAN or bank account number
To view this information in its unredacted state, you must have either the BalancePlatform Merchant Admin or View PII Data on balance platform user role.
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.
- Log in to your Balance Platform Customer Area.
- Go to Accounts & balances > Account holders.
- In the account holder table, select Search to search by account holder ID, reference, legal entity ID or name.
- In the search window, select View account holder to open 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.
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.
Request a capability
Default capabilities are automatically requested when you create an account holder. However, your account holders might 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.
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 this to the desired capability level.
Here is an example of how you would update an existing account holder to request the withdrawFromAtm capability with level medium. If you're requesting for multiple capabilities, add another set of key-value object.
curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \
-H "content-type: application/json" \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-X PATCH \
-d '{
"capabilities" : {
"withdrawFromAtm" : {
"requested" : true,
"requestedLevel" : "medium"
}
}
}'You receive a response informing you that the capability has been requested and the verification status is pending.
{
"balancePlatform": "YOUR_BALANCE_PLATFORM",
"id": "AH32272223222B5D3755J3C3C",
"legalEntityId": "LE00000000000000000000001",
"description": "S.Hopper",
"capabilities": {
"withdrawFromAtm": {
"requested": true,
"requestedLevel": "medium",
"allowed": false,
"verificationStatus": "pending"
}
}
}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.
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.
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 disable a capability, make a PATCH /accountHolders/{id} request to update the capability. Set the enabled field to false.
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 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, transfer any remaining balance.
-
Close balance accounts by updating each balance account and setting the
statusto 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
statusto Closed.
View balance accounts
To view the balance accounts and the available balances of your account holder, you can either use your Balance Platform Customer Area or make an API request.
To get balance accounts, use the following endpoints:
- GET /accountHolders/{id}/balanceAccounts: Get a list of the balance accounts of an account holder. This endpoint returns a paginated list of balance accounts.
- GET /balanceAccounts/{id}: Get the details of a balance account, including a list of balances and paymentInstruments (cards) associated with the balance account.
Update a balance account
To update a balance account, make a PATCH /balanceAccounts/{id} request. The example below shows how you would update the description of a balance account.
Close a balance account
In some scenarios, you might want to close an account holder's balance account. For example, an account holder that has separate balance accounts for their businesses might want to close one of their businesses.
To permanently close a balance account:
- Check if the balance account has zero balance. You can only close an empty balance account, so if there are funds left, you must transfer any remaining balance to another balance account.
- Close a balance account by updating the balance account and setting the
statusto Closed.
If an account holder discontinues their contractual relationship with your platform, you can also permanently deactivate the account holder.