Account holders and balance accounts

Before you can issue a card, you have to create the following resources:

• An accountHolder that is linked to their legalEntity, and owns balance accounts.
• A balanceAccount, which holds the funds of an account holder. The balance account is from which a card deducts funds.

In most cases, one balance account for an account holder is sufficient, but there are some scenarios when you might need to create multiple balance accounts. For example:

• A user requests additional cards to keep separate balances for their checking and savings accounts.
• A user requests additional cards with separate balances for their spouse or other family members.

Create an account holder

To create an account holder, make a POST /accountHolders request specifying:

• The legalEntityId, the unique identifier of the account holder's corresponding legal entity.
• The balancePlatform identifier. Required only if your API credentials has access to multiple balance platforms.

In your request, you can also include a human-readable description which can be useful for your staff and support agents when identifying account holders.

Here is an example of how you can create an account holder.

curl https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-d '{
  "{hint:Required if you have multiple balance platforms}balancePlatform{/hint}": "YOUR_BALANCE_PLATFORM_ACCOUNT",
  "{hint:Free-text field}description{/hint}":"S.Hopper - Staff 123",
  "{hint:Unique legal entity ID}legalEntityId{/hint}":"LE00000000000000000000001"
}'

The response returns the new accountHolder resource, identified by its unique id. The response also includes a capabilities array. You'll find out more about this array later when you check the account holder's capabilities.

{
    "balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
    "description": "S.Hopper - Staff 123",
    "id": "AH00000000000000000000001",
    "status": "Active",
    "legalEntityId":"LE00000000000000000000001",
    "capabilities":{
      "issueCard":{
        "enabled":"true",
        "requested":"true",
        "allowed":"false",
        "verificationStatus":"pending"
     }
   }
}

Next, you need to create a corresponding balance account to hold the account holder's funds.

Create a balance account

All card transactions are processed against a balance account.

To create a balance account, make a POST /balanceAccounts request specifying the accountHolderId to be associated with the balance account. In your request, you can also include a human-readable description to help your staff differentiate between multiple balance accounts under one account holder.

Here is an example for creating a new balance account for account holder with id AHA1B2C3D4E5F6G7H8I9J0.

curl https://balanceplatform-api-test.adyen.com/bcl/v2/balanceAccounts \
-H "x-api-key: YOUR_BALANCE_PLATFORM_API_KEY" \
-H "content-type: application/json" \
-d '{
  "accountHolderId":"AH00000000000000000000001",
  "{hint:Free-text field}description{/hint}":"S.Hopper - Main balance account"
}'

The response returns the balanceAccount resource, identified by its unique id. The response also includes the balances array which contains information about the account's funds. By default, the first balance account that you create for an account holder is assigned as their primary balance account. To change their primary balance account, you can update the account holder.

{
  "accountHolderId":"AH00000000000000000000001",
  "defaultCurrencyCode": "EUR",
  "description":"S.Hopper - Main balance account",
  "balances": [
        {
            "available": 0,
            "balance": 0,
            "currency": "EUR",
            "reserved": 0
        }
  ],
  "id":"BA00000000000000000000001",
  "status":"Active"
}

The balance account will have a zero initial balance. Before a user can use their card, you have to add funds to their balance account.