Search

Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Create accounts

Learn how to create account holders and balance accounts for your users.

Before you can issue a card to a user, you need to create the following:

  1. An accountHolder resource to represent the user's entity within the Balance Platform. This account holder will need to complete Know Your Customer (KYC) verification checks.
  2. A balanceAccount resource to hold the funds of the account holder. All transactions using an Adyen-issued card are processed against the associated balance account.

In some scenarios, you might need to create multiple balance accounts for a single account holder. 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 providing:

Parameter Required Description
balancePlatform -white_check_mark- Your balance platform account.
description -x- Your description for this account holder. Free text, human-readable field for your support agent and other staff.
contactDetails.email -white_check_mark- The account holder's email address.
contactDetails.phone.* -white_check_mark- Object that contains the account holder's phone number.

- phoneNumber: Full phone number in string format.
- phoneType: Specify if Mobile or Landline.
contactDetails.address.* -white_check_mark- Object that contains the account holder's address. The KYC requirements will depend on the country.
legalEntityId A unique legal entity ID for the account holder, used as a reference for the KYC process. Contact our Support Team to get this ID.

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

Create an account holder
curl https://balanceplatform-api-test.adyen.com/bcl/v1/accountHolders \
-u "ws@Company.YourCompany":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-d '{
  "balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
  "description":"{hint:Human-readable field for your support agents and other staff}S.Hopper - Staff 123{/hint}",
  "legalEntityId":"{hint:Unique legal entity ID. Contact our Support team to get this ID.}LE1249248458283{/hint}",
  "contactDetails":{
    "email":"s.hopper@example.com",
    "phone": {
        "number": "+315551231234",
        "type": "{hint:Mobile or Landline}Mobile{/hint}"
    },
    "address": {
      "city": "Amsterdam",
      "country": "NL",
      "street": "Brannan Street",
      "houseNumberOrName": "274",
      "postalCode": "1020CD"
    }
  }
}'

The response returns the new accountHolder resource, along with the unique account holder id.

Response
{
    "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

To create a balanceAccount resource, make a POST /balanceAccounts request providing:

  • accountHolderId: The ID of the account holder to be associated with this balance account.
  • description: A human-readable description for this balance account. You can use this field to help 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.

Create balance account
curl https://balanceplatform-api-test.adyen.com/bcl/v1/balanceAccounts \
-u "ws@Company.YourCompany":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-d '{
  "accountHolderId":"AHA1B2C3D4E5F6G7H8I9J0",
  "description":"{hint:Human-readable field description}S.Hopper - Main balance account{/hint}",
}'

The response returns the balanceAccount resource. This also includes the balances array which contains information about the account's funds.

Response
{
  "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.

Next steps

After you've created the account holder, start the KYC verification process. The account holder will still need to undergo KYC verification checks before you can enable card processing and perform payouts.