Search

Are you looking for test card numbers?

Would you like to contact support?

Default icon

Create account holders

Learn how to create account holders for your users.

Before you start creating cards for your users, you need to create an accountHolder and a balanceAccount resource for each user.

  • The accountHolder represents your user's entity.
  • A balanceAccount is owned by an accountHolder. All transactions and money movement is processed against a balanceAccount. A card has to be associated with a balanceAccount.

An account holder can have multiple balance accounts associated with it.

Before you can issue cards, every account holder will need to go through KYC and onboarding processes.

Create an account holder

You need to create an accountHolder to represent your user.

The information you need to create for an accountHolder depends primarily on their entity:

  • Individual: a person or sole proprietorship.
  • Business: a business or company.

To create an account holder for an individual or sole proprietor, make a POST /accountHolders request providing:

  • legalEntityType: Specify as Individual.
  • individual.name.firstName: The account holder's first name.
  • individual.name.lastName: The account holder's last name.
  • individual.dateOfBirth: The account holder's birthday. Format: YYYY-MM-DD.
  • individual.nationality: The account holder's nationality represented by a two-character country code defined in ISO-3166-1 alpha-2.
  • individual.idNumber: The account holder's national number, such as Social Security Number for US residents.
  • contact.email: The account holder's contact email.
  • contact.phoneNumber: The account holder's full phone number provided as a single string.
  • contact.address.*: The account holder's address. The country specified dictates the KYC requirements for the account holder.
{
  "balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
  "legalEntityType":"Individual",
  "individualDetails":{
    "name":{
      "firstName":"Simon",
      "lastName":"Hopper"
    },
  "personalData": {
    "dateOfBirth": "1987-03-07",
    "nationality": "NL",
    "idNumber": "123456789"
   }
  },
  "contactDetails":{
    "email":"s.hopper@testcompany.com",
    "phoneNumber":"+315551231234",
    "address": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD"
    }
  },
  "description":"{hint:Human-readable field for your support agents and other staff}S.Hopper - Staff 123{/hint}", 
  "reference":"{hint:Your unique identifier for this resource}myAccountHolder_12345{/hint}" 
}

The response contains the new accountHolder resource.

{
  "id":"AHA1B2C3D4E5F6G7H8I9J0",
  "balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
  "legalEntityType":"individual",
  "individual":{
    "name":{
      "firstName":"Simon",
      "lastName":"Hopper"
    },
    "dateOfBirth": "1987-03-07",
    "nationality": "NL",
    "idNumber": "123456789"
  },
  "contact":{
    "email":"s.hopper@testcompany.com",
    "phoneNumber":"+315551231234",
    "address": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD"
    }
  },
  "reference":"{hint:Your unique identifier for this resource}myAccountHolder_12345{/hint}", 
  "balanceAccounts":[{
    "id":"BA6534654365436534"
  }]
}

To create an account holder for a business or company, make a POST /accountHolders request providing:

  • legalEntityType: Specify as Business.
  • business.legalBusinessName: The business name of the company.

  • individual.*: Information about the person with the right to sign up the company.

    • individual.name.first: The first name of the user signing up the account.
    • individual.name.last: The last name of the user signing up the account.
    • individual.dateOfBirth: The birthday of the user signing up the account. Format: YYYY-MM-DD.
    • individual.nationality: The nationality of the user signing up the account, represented by a two-character country code defined in ISO-3166-1 alpha-2. This determines how the idNumber will be validated.
    • individual.idNumber: The national number of the user signing up the account, such as Social Security Number for US residents.
  • contact.email: A contact email for the business.
  • contact.phoneNumber: The full phone number of the business, provided as a single string.
  • contact.address.*: The address of the business. The country specified dictates the KYC requirements for the business.
{
  "legalEntityType":"Business",
  "business":{
    "legalBusinessName":"Test Company Inc"
  },
  "individual":{
    "name":{
      "firstName":"Simon",
      "lastName":"Hopper"
    },
    "dateOfBirth": "1987-03-07",
    "nationality": "NL",
    "idNumber": "123456789"
  },
  "contact":{
    "email":"s.hopper@testcompany.com",
    "phoneNumber":"+315551231234",
    "address": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD"
    }
  },
  "description":"{hint:Human-readable field for your support agents and other staff}S.Hopper - Staff 123{/hint}", 
  "reference":"{hint:Your unique identifier for this resource}myAccountHolder_12345{/hint}"
}

The response contains the new accountHolder resource.

{
  "id":"AHA1B2C3D4E5F6G7H8I9J0",
  "legalEntityType":"business",
  "individual":{
    "name":{
      "firstName":"Simon",
      "lastName":"Hopper"
    },
    "dateOfBirth": "1987-03-07",
    "nationality": "NL",
    "idNumber": "123456789"
  },
  "contact":{
    "email":"s.hopper@testcompany.com",
    "phoneNumber":"+315551231234",
    "address": {
      "city": "Amsterdam",
      "country": "NL",
      "stateOrProvince": "NH",
      "street": "274 Brannan Street",
      "street2": "Suite 600",
      "postalCode": "1020CD"
    }
  },
  "reference":"{hint:Your unique identifier for this resource}myAccountHolder_12345{/hint}", 
  "balanceAccounts":[{
    "id":"BA6534654365436534"
  }]
}

The accountHolder will automatically be created with a balanceAccount. You will need the balanceAccount.id when creating payment instruments to issue cards.

Your account holder will still need to undergo Know Your Customer (KYC) verification process before you can enable card processing and perform payouts.

Balance accounts and liable balance accounts

Balance accounts are financial accounts that contain a transaction history and can hold a balance. All financial movement in the Balance Platform happens through balance accounts. Your company has it's own balance account called a liable balance account. This is where you load funds, transfer balances between yourself and your users, and are paid out from.

All cards, represented by paymentInstrument resources, have to be associated with a balance account. All transactions made with an Adyen-issued card, such as purchases and refunds, are performed against their associated balance account.

Account holders are automatically created with a single balance account, though you can explicitly create additional balance accounts as needed.

Next steps

required
KYC and onboarding

Understand KYC and how to provide your user's KYC data.
Manage accounts

Learn how to manage account holders and balance accounts.
required
Create cards

Create and issue cards for your users.