Account holders and balance accounts

Before you can issue a card, you have to create an account holder and a balance account from which the card can deduct 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

An accountHolder resource represents the user's entity within your balance platform. This account holder will need to complete Know Your Customer (KYC) verification checks before you can issue a card to them.

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

• The account holder's contactDetails with their address, email, and phone number.
• The legalEntityId, referring to the unique identifier of the account holder's corresponding legal entity resource. If you have not created their legal entity resource yet, you can also update the account holder resource at a later time.
• 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/v1/accountHolders \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-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}":"LE1249248458283",
  "contactDetails":{
    "email":"s.hopper@example.com",
    "phone": {
        "number": "+315551231234",
        "{hint:Mobile or Landline}type{/hint}": "Mobile"
    },
    "address": {
      "city": "Amsterdam",
      "country": "NL",
      "street": "Brannan Street",
      "houseNumberOrName": "274",
      "postalCode": "1020CD"
    }
  }
}'

The response returns the new accountHolder resource, identified by its unique id.

{
    "balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
    "contactDetails": {
        "address": {
            "city": "Amsterdam",
            "country": "NL",
            "houseNumberOrName": "274",
            "postalCode": "1020CD",
            "street": "Brannan Street"
        },
        "email": "s.hopper@example.com",
        "phone": {
            "number": "+315551231234",
            "type": "Mobile"
        }
    },
    "description": "S.Hopper - Staff 123",
    "id": "AHA1B2C3D4E5F6G7H8I9J0",
    "status": "Active"
}

After creating an account holder, you need to create a corresponding balance account to hold their funds.

Create a balance account

A balanceAccount resource holds the funds of the account holder. All transactions using an issued card are processed against the associated 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/v1/balanceAccounts \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-d '{
  "accountHolderId":"AHA1B2C3D4E5F6G7H8I9J0",
  "{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.

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

The balance account will have a zero initial balance. Before a user can use their card, you need to make sure that the balance account has funds. For more information, refer to Manage funds.