Manage your platform

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

View account holders

To view account holder details, you can either use your Balance Platform Customer Area or make an API request.

Request a capability

Default capabilities are automatically requested when you create an account holder. However, if you need to request a specific capability, you need to 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 this to the desired capability level.

Here is an example of how you would update an existing account holder to request for 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"
    }
  }
}

Deactivate a capability

When an account holder has a capability, they are allowed to perform the action, but you can still control the use of the capability.
When you want to temporarily stop an account holder from using a capability, make a PATCH /accountHolders/{id} request to update the capability. Set the enabled field to false.

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": {
        "sendToTransferInstrument": {
            "enabled": 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.

curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders/AH00000000000000000000001 \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-X PATCH \
-d '{
    "primaryBalanceAccount":"BA00000000000000000000002"
}'

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:

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