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.
Select a tab below to create an account holder for a specific entity:
To create an account holder for an individual or sole proprietor, make a POST /accountHolders request providing:
| Parameter | Required | Description |
|---|---|---|
balancePlatform |
 |
Your balance platform account. |
legalEntityType |
|
Set this to Individual. |
description |
 |
Your description for this account holder. Free text, human-readable field for your support agent and other staff. |
individualDetails.name.firstName |
|
The account holder's first name. |
individualDetails.name.lastName |
|
The account holder's last name. |
individualDetails.personalData.dateOfBirth |
|
The account holder's birthday. Format: YYYY-MM-DD. |
individualDetails.personalData.nationality |
|
The account holder's nationality represented by a two-character country code defined in ISO-3166-1 alpha-2. |
individualDetails.personalData.idNumber |
|
The account holder's national number, such as a Social Security Number for US residents. |
contactDetails.email |
|
The account holder's contact email. |
contactDetails.phone.* |
|
Object that contains the account holder's phone number. - phoneNumber: Full phone number in string format. - phoneType: Specify if Mobile or Landline. |
contactDetails.address.* |
|
Object that contains the account holder's address. The country specified dictates the KYC requirements for the account holder. |
{
"balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
"legalEntityType":"Individual",
"description":"{hint:Human-readable field for your support agents and other staff}S.Hopper - Staff 123{/hint}",
"individualDetails":{
"name":{
"firstName":"Simon",
"lastName":"Hopper"
},
"personalData": {
"dateOfBirth": "1987-03-07",
"nationality": "NL",
"idNumber": "123456789"
}
},
"contactDetails":{
"email":"s.hopper@testcompany.com",
"phone": {
"number": "+315551231234",
"type": "{hint:One of: Mobile or Landline}Mobile{/hint}"
},
"address": {
"city": "Amsterdam",
"country": "NL",
"stateOrProvince": "NH",
"street": "Brannan Street",
"houseNumberOrName": "274",
"postalCode": "1020CD"
}
}
}The response contains the new accountHolder resource.
{
"id":"AHA1B2C3D4E5F6G7H8I9J0",
"balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
"legalEntityType":"Individual",
"individualDetails":{
"name":{
"firstName":"Simon",
"lastName":"Hopper"
},
"dateOfBirth": "1987-03-07",
"nationality": "NL",
"idNumber": "123456789"
},
"contactDetails":{
"email":"s.hopper@testcompany.com",
"phone": {
"number": "+315551231234",
"type": "{hint: Set this to Mobile or Landline}Mobile{/hint}"
},
"address": {
"city": "Amsterdam",
"country": "NL",
"stateOrProvince": "NH",
"street": "Brannan Street",
"houseNumberOrName": "274",
"postalCode": "1020CD"
}
},
"description":"{hint:Human-readable field for your support agents and other staff}S.Hopper - Staff 123{/hint}",
"balanceAccounts":[{
"id":"BA6534654365436534"
}]
}To create an account holder for a business or company, make a POST /accountHolders request providing:
| Parameter | Required | Description |
|---|---|---|
balancePlatform |
|
Your balance platform account. |
legalEntityType |
|
Set this to Business. |
description |
|
Your description for this account holder. Free text, human-readable field for your support agent and other staff. |
businessDetails.legalBusinessName |
|
The company's legal business name. |
businessDetails.tradingName |
|
The name that the company is known for by its customers. |
businessDetails.registrationNumber |
|
The company's registration number. |
businessDetails.taxId |
|
The company's tax identification number. |
shareHolders |
|
Array that contains shareholder information. |
shareHolders.email |
|
The shareholder's email. |
shareHolders.shareholderReference |
|
Your reference for this shareholder. |
shareHolders.fullPhoneNumber |
|
The shareholder's full phone number in string. |
shareHolders.name.firstName |
|
The shareholder's first name. |
shareHolders.name.lastName |
|
The shareholder's last name. |
shareHolders.personalData.dateOfBirth |
|
The shareholder's birthday. Format: YYYY-MM-DD. |
shareHolders.personalData.nationality |
|
The shareholder's nationality represented by a two-character country code defined in ISO-3166-1 alpha-2. This determines how the idNumber will be validated. |
shareHolders.personalData.idNumber |
|
The shareholder's national number, such as a Social Security Number for US residents. |
shareHolders.address.* |
|
Object that contains the shareholder's address. |
shareHolders.phone.* |
|
Object that contains the shareholder's phone number. - phoneCountryCode: The two-character country code of the phone number. - phoneNumber: Full phone number in string format. - phoneType: Specify if Mobile or Landline. |
shareHolders.personalDocuments.* |
|
Object that contains information about the shareholder's identification documents. If you include this in the request, the type and number are required. Values for type: ID, PASSPORT, VISA, or DRIVINGLICENSE |
contactDetails.email |
|
The account holder's contact email. |
contactDetails.phone.* |
|
Object that contains the account holder's phone number. - number: Full phone number in string format. - type: Specify if Mobile or Landline. |
contactDetails.address.* |
|
Object that contains the account holder's address. The country specified dictates the KYC requirements for the account holder. |
{
"balancePlatform": "YOUR_BALANCE_PLATFORM_ACCOUNT",
"legalEntityType": "Business",
"description": "{hint:Human-readable field for your support agents and other staff}Main account holder{/hint}",
"contactDetails": {
"email": "test@testcompany.com",
"phone": {
"number":"0031205277777",
"type": "{hint: Set this to Mobile or Landline}Landline{/hint}"
},
"address": {
"city": "Amsterdam",
"country": "NL",
"stateOrProvince": "NH",
"street": "Brannan Street",
"houseNumberOrName": "274",
"postalCode": "1020CD"
}
},
"businessDetails": {
"legalBusinessName": "LEGAL_BUSINESS_NAME",
"tradingName": "TRADING_NAME",
"registrationNumber": "53453453453",
"taxId": "43535345345",
"shareHolders": [
{
"address": {
"street": "Axis Street",
"houseNumberOrName": "23C",
"city": "Amsterdam",
"postalCode": "15266",
"country": "NL",
"stateOrProvince": "NH"
},
"email": "s@testcompany.com",
"fullPhoneNumber": "9999999999",
"name": {
"firstName": "Simon",
"lastName": "Hopper"
},
"personalData": {
"dateOfBirth": "1990-12-25",
"idNumber": "43534534534",
"nationality": "NL"
},
"personalDocuments": [
{
"type": "PASSPORT",
"expirationDate": "2022-12-25",
"issuerCountry": "NL",
"issuerState": "NL",
"number": "222325094583049"
}
],
"phone": {
"countryCode": "GB",
"number": "65775675675",
"type": "Landline"
},
"shareholderReference": "SHAREREF"
}
]
}
}The response contains the new accountHolder resource.
{
"id":"AHA1B2C3D4E5F6G7H8I9J0",
"legalEntityType":"Business",
"contactDetails":{
"email":"test@testcompany.com",
"phone": {
"phoneNumber": "0031205277777",
"phoneType": "{hint:One of: Mobile or Landline}Landline{/hint}"
},
"address": {
"city": "Amsterdam",
"country": "NL",
"stateOrProvince": "NH",
"street": "Brannan Street",
"houseNumberOrName": "274",
"postalCode": "1020CD"
}
},
"description":"{hint:Human-readable field for your support agents and other staff}Main account holder{/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.