A balance account is an API resource that contains information about the funds held by your user. To manage the balance accounts use the Configuration API.
This page contains instructions for common balance account operations. These operations are part of a larger process which includes verification and onboarding steps.
Create a balance account
You can create balance accounts manually using the Configuration API. To create a balance account:
-
Make a POST /balanceAccounts using the account holder ID you want to attach the balance account to.
Create a balance accountExpand viewCopy link to code blockCopy codecurl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X POST \ -d '{ "accountHolderId": "AH00000000000000000000001", "description": "AccountHolder Primary Balance Account" }' -
In the response, note the
id
. You need this ID to:Create balance account responseExpand viewCopy link to code blockCopy code{ "accountHolderId": "AH00000000000000000000001", "defaultCurrencyCode": "EUR", "description": "Main Account", "reference": "Referee", "timeZone": "Europe/Amsterdam", "balances": [ { "available": 0, "balance": 0, "currency": "EUR", "pending": 0, "reserved": 0 } ], "id": "BA00000000000000000000001", "status": "active" }
View balance accounts
To view the balance accounts and the available balances of your account holder, you can either use your Customer Area or make an API request.
To view balance accounts in your Customer Area:
-
In the navigation menu, select the merchant account linked to your balance platform.
-
Select Accounts & balances > Balance accounts.
-
Select a Balance account ID to view more details, such as the available balances.
Alternatively, enter a balance account ID in the Search menu to find a balance account.
Update a balance account
To update a balance account, make a PATCH /balanceAccounts/{id} request. The following example shows how to update the description of a balance account.
curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts/BA00000000000000000000001 \ -H 'x-api-key: ADYEN_BALANCE_PLATFORM_API_KEY' \ -H 'content-type: application/json' \ -X PATCH \ -d '{ "description":"Balance account for new business" }'
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 pay out or transfer any remaining balance to another balance account.
- Close a balance account by updating the balance account and setting the
status
to Closed.
If an account holder discontinues their contractual relationship with your platform, you can also permanently deactivate the account holder.