Get an account holder

post/getAccountHolder

Returns the details of an account holder.

Endpoint destination URL

https://cal-test.adyen.com/cal/services/Account/v5/getAccountHolder

Request Parameters

Required

Optional

The code of the account of which to retrieve the details.

Required if no accountHolderCode is provided.

The code of the account holder of which to retrieve the details.

Required if no accountCode is provided.

True if the request should return the account holder details

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
Show moreShow less
accountHolderCodestring
The code of the account holder.
accountHolderDetailsobject
Details of the account holder.
Show children Hide children
addressobject
The address of the account holder.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
bankAccountDetailsarray[object]
Array of bank accounts associated with the account holder. For details about the required bankAccountDetail fields, see Required information.
Show children Hide children
accountNumberstring
The bank account number (without separators).

Refer to Required information for details on field requirements.

accountTypestring
The type of bank account. Only applicable to bank accounts held in the USA. The permitted values are: checking, savings.

Refer to Required information for details on field requirements.

bankAccountNamestring
The name of the bank account.
bankAccountReferencestring
Merchant reference to the bank account.
bankAccountUUIDstring
The unique identifier (UUID) of the Bank Account.

If, during an account holder create or update request, this field is left blank (but other fields provided), a new Bank Account will be created with a procedurally-generated UUID.

If, during an account holder create request, a UUID is provided, the creation of the Bank Account will fail while the creation of the account holder will continue.

If, during an account holder update request, a UUID that is not correlated with an existing Bank Account is provided, the update of the account holder will fail.

If, during an account holder update request, a UUID that is correlated with an existing Bank Account is provided, the existing Bank Account will be updated.

bankBicSwiftstring
The bank identifier code.

Refer to Required information for details on field requirements.

bankCitystring
The city in which the bank branch is located.

Refer to Required information for details on field requirements.

bankCodestring
The bank code of the banking institution with which the bank account is registered.

Refer to Required information for details on field requirements.

bankNamestring
The name of the banking institution with which the bank account is held.

Refer to Required information for details on field requirements.

branchCodestring
The branch code of the branch under which the bank account is registered. The value to be specified in this parameter depends on the country of the bank account:

United States - Routing number

United Kingdom - Sort code

Germany - Bankleitzahl

Refer to Required information for details on field requirements.

checkCodestring
The check code of the bank account.

Refer to Required information for details on field requirements.

countryCodestring
The two-letter country code in which the bank account is registered.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

Refer to Required information for details on field requirements.

currencyCodestring
The currency in which the bank account deals.

The permitted currency codes are defined in ISO-4217 (e.g. 'EUR').

ibanstring
The international bank account number.

The IBAN standard is defined in ISO-13616.

Refer to Required information for details on field requirements.

ownerCitystring
The city of residence of the bank account owner.

Refer to Required information for details on field requirements.

ownerCountryCodestring
The country code of the country of residence of the bank account owner.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

Refer to Required information for details on field requirements.

ownerDateOfBirthstringDeprecated
The date of birth of the bank account owner. The date should be in ISO-8601 format yyyy-mm-dd (e.g. 2000-01-31).
ownerHouseNumberOrNamestring
The house name or number of the residence of the bank account owner.

Refer to Required information for details on field requirements.

ownerNamestring
The name of the bank account owner.

Refer to Required information for details on field requirements.

ownerNationalitystring
The country code of the country of nationality of the bank account owner.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

Refer to Required information for details on field requirements.

ownerPostalCodestring
The postal code of the residence of the bank account owner.

Refer to Required information for details on field requirements.

ownerStatestring
The state of residence of the bank account owner.

Refer to Required information for details on field requirements.

ownerStreetstring
The street name of the residence of the bank account owner.

Refer to Required information for details on field requirements.

primaryAccountboolean
If set to true, the bank account is a primary account.
taxIdstring
The tax ID number.

Refer to Required information for details on field requirements.

urlForVerificationstring
The URL to be used for bank account verification. This may be generated on bank account creation.

Refer to Required information for details on field requirements.

bankAggregatorDataReferencestring
The opaque reference value returned by the Adyen API during bank account login.
businessDetailsobject
Details about the business or nonprofit account holder. Required when creating an account holder with legalEntity Business or NonProfit.
Show children Hide children
doingBusinessAsstring
The registered name of the company (if it differs from the legal name of the company).
legalBusinessNamestring
The legal name of the company.
listedUltimateParentCompanyarray[object]
Information about the parent public company. Required if the account holder is 100% owned by a publicly listed company.
Show children Hide children
addressobject
Address of the ultimate parent company.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
businessDetailsobject
Details about the ultimate parent company's business.
Show children Hide children
legalBusinessNamestring
The legal name of the company.
registrationNumberstring
The registration number of the company.
stockExchangestring
Market Identifier Code (MIC).
stockNumberstring
International Securities Identification Number (ISIN).
stockTickerstring
Stock Ticker symbol.
ultimateParentCompanyCodestring
Adyen-generated unique alphanumeric identifier (UUID) for the entry, returned in the response when you create an ultimate parent company. Required when updating an existing entry in an /updateAccountHolder request.
registrationNumberstring
The registration number of the company.
shareholdersarray[object]
Array containing information about individuals associated with the account holder either through ownership or control. For details about how you can identify them, refer to our verification guide.
Show children Hide children
addressobject
The address of the person.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
emailstring
The e-mail address of the person.
fullPhoneNumberstring
The phone number of the person provided as a single string. It will be handled as a landline phone. Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"
jobTitlestring
Job title of the person. Required when the shareholderType is Controller.

Example values: Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, President, Vice President, Executive President, Managing Member, Partner, Treasurer, Director, or Other.
nameobject
The name of the person.
Show children Hide children
firstNamestring
Max length: 80
The first name.
genderstring
Max length: 1
The gender.

The following values are permitted: MALE, FEMALE, UNKNOWN.

infixstring
Max length: 20
The name's infix, if applicable.

A maximum length of twenty (20) characters is imposed.

lastNamestring
Max length: 80
The last name.
personalDataobject
Contains information about the person.
Show children Hide children
dateOfBirthstring
The person's date of birth, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
documentDataarray[object]
Array that contains information about the person's identification document. You can submit only one entry per document type.
Show children Hide children
expirationDatestring
The expiry date of the document, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
issuerCountrystring
Min length: 2Max length: 2
The country where the document was issued, in the two-character ISO 3166-1 alpha-2 format. For example, NL.
issuerStatestring
The state where the document was issued (if applicable).
numberstring
The number in the document.
typestring
The type of the document. Possible values: ID, DRIVINGLICENSE, PASSPORT, SOCIALSECURITY, VISA.

To delete an existing entry for a document type, send only the type field in your request.
nationalitystring
Min length: 2Max length: 2
The nationality of the person represented by a two-character country code, in ISO 3166-1 alpha-2 format. For example, NL.

phoneNumberobject
The phone number of the person.
Show children Hide children
phoneCountryCodestring
The two-character country code of the phone number.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

phoneNumberstring
The phone number.

The inclusion of the phone number country code is not necessary.

phoneTypestring
The type of the phone number.

The following values are permitted: Landline, Mobile, SIP, Fax.

shareholderCodestring
The unique identifier (UUID) of the shareholder entry.

If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Shareholder will be created with a procedurally-generated UUID.

If, during an Account Holder create request, a UUID is provided, the creation of Account Holder will fail with a validation Error..

If, during an Account Holder update request, a UUID that is not correlated with an existing Shareholder is provided, the update of the Shareholder will fail.

If, during an Account Holder update request, a UUID that is correlated with an existing Shareholder is provided, the existing Shareholder will be updated.

shareholderReferencestring
Your reference for the shareholder entry.
shareholderTypestring
Specifies how the person is associated with the account holder.

Possible values:

Owner: Individuals who directly or indirectly own 25% or more of a company.

Controller: Individuals who are members of senior management staff responsible for managing a company or organization.

webAddressstring
The URL of the person's website.
signatoriesarray[object]
Signatories associated with the company. Each array entry should represent one signatory.
Show children Hide children
addressobject
The address of the person.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
emailstring
The e-mail address of the person.
fullPhoneNumberstring
The phone number of the person provided as a single string. It will be handled as a landline phone. Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"
jobTitlestring
Job title of the signatory.

Example values: Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, President, Vice President, Executive President, Managing Member, Partner, Treasurer, Director, or Other.
nameobject
The name of the person.
Show children Hide children
firstNamestring
Max length: 80
The first name.
genderstring
Max length: 1
The gender.

The following values are permitted: MALE, FEMALE, UNKNOWN.

infixstring
Max length: 20
The name's infix, if applicable.

A maximum length of twenty (20) characters is imposed.

lastNamestring
Max length: 80
The last name.
personalDataobject
Contains information about the person.
Show children Hide children
dateOfBirthstring
The person's date of birth, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
documentDataarray[object]
Array that contains information about the person's identification document. You can submit only one entry per document type.
Show children Hide children
expirationDatestring
The expiry date of the document, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
issuerCountrystring
Min length: 2Max length: 2
The country where the document was issued, in the two-character ISO 3166-1 alpha-2 format. For example, NL.
issuerStatestring
The state where the document was issued (if applicable).
numberstring
The number in the document.
typestring
The type of the document. Possible values: ID, DRIVINGLICENSE, PASSPORT, SOCIALSECURITY, VISA.

To delete an existing entry for a document type, send only the type field in your request.
nationalitystring
Min length: 2Max length: 2
The nationality of the person represented by a two-character country code, in ISO 3166-1 alpha-2 format. For example, NL.

phoneNumberobject
The phone number of the person.
Show children Hide children
phoneCountryCodestring
The two-character country code of the phone number.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

phoneNumberstring
The phone number.

The inclusion of the phone number country code is not necessary.

phoneTypestring
The type of the phone number.

The following values are permitted: Landline, Mobile, SIP, Fax.

signatoryCodestring
The unique identifier (UUID) of the signatory.

If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Signatory will be created with a procedurally-generated UUID.

If, during an Account Holder create request, a UUID is provided, the creation of the Signatory will fail while the creation of the Account Holder will continue.

If, during an Account Holder update request, a UUID that is not correlated with an existing Signatory is provided, the update of the Signatory will fail.

If, during an Account Holder update request, a UUID that is correlated with an existing Signatory is provided, the existing Signatory will be updated.

signatoryReferencestring
Your reference for the signatory.
webAddressstring
The URL of the person's website.
taxIdstring
The tax ID of the company.
emailstring
The email address of the account holder.
fullPhoneNumberstring
The phone number of the account holder provided as a single string. It will be handled as a landline phone. Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"
individualDetailsobject
Details about the individual account holder. Required when creating an account holder with legalEntity Individual.

Show children Hide children
nameobject
The name of the individual.

Make sure your account holder registers using the name shown on their Photo ID. Maximum length: 80 characters Cannot contain numbers. /n Cannot be empty.

Show children Hide children
firstNamestring
Max length: 80
The first name.
genderstring
Max length: 1
The gender.

The following values are permitted: MALE, FEMALE, UNKNOWN.

infixstring
Max length: 20
The name's infix, if applicable.

A maximum length of twenty (20) characters is imposed.

lastNamestring
Max length: 80
The last name.
personalDataobject
Personal information of the individual.
Show children Hide children
dateOfBirthstring
The person's date of birth, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
documentDataarray[object]
Array that contains information about the person's identification document. You can submit only one entry per document type.
Show children Hide children
expirationDatestring
The expiry date of the document, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
issuerCountrystring
Min length: 2Max length: 2
The country where the document was issued, in the two-character ISO 3166-1 alpha-2 format. For example, NL.
issuerStatestring
The state where the document was issued (if applicable).
numberstring
The number in the document.
typestring
The type of the document. Possible values: ID, DRIVINGLICENSE, PASSPORT, SOCIALSECURITY, VISA.

To delete an existing entry for a document type, send only the type field in your request.
nationalitystring
Min length: 2Max length: 2
The nationality of the person represented by a two-character country code, in ISO 3166-1 alpha-2 format. For example, NL.

lastReviewDatestring
Date when you last reviewed the account holder's information, in ISO-8601 YYYY-MM-DD format. For example, 2020-01-31.
merchantCategoryCodestring
The Merchant Category Code of the account holder.

If not specified in the request, this will be derived from the platform account (which is configured by Adyen).

metadataobject
A set of key and value pairs for general use by the account holder or merchant. The keys do not have specific names and may be used for storing miscellaneous data as desired.

The values being stored have a maximum length of eighty (80) characters and will be truncated if necessary. Note that during an update of metadata, the omission of existing key-value pairs will result in the deletion of those key-value pairs.

payoutMethodsarray[object]
Array of tokenized card details associated with the account holder. For details about how you can use the tokens to pay out, refer to Pay out to cards.
Show children Hide children
merchantAccountstring
The merchantAccount you used in the /payments request when you saved the account holder's card details.
payoutMethodCodestring
Adyen-generated unique alphanumeric identifier (UUID) for the payout method, returned in the response when you create a payout method. Required when updating an existing payout method in an /updateAccountHolder request.
payoutMethodReferencestring
Your reference for the payout method.
recurringDetailReferencestring
The recurringDetailReference returned in the /payments response when you saved the account holder's card details.
shopperReferencestring
The shopperReference you sent in the /payments request when you saved the account holder's card details.
phoneNumberobject
The phone number of the account holder.

Required if a fullPhoneNumber is not provided.

Show children Hide children
phoneCountryCodestring
The two-character country code of the phone number.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

phoneNumberstring
The phone number.

The inclusion of the phone number country code is not necessary.

phoneTypestring
The type of the phone number.

The following values are permitted: Landline, Mobile, SIP, Fax.

principalBusinessAddressobject
The principal business address of the account holder.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
storeDetailsarray[object]
Array of stores associated with the account holder. Required when onboarding account holders that have an Adyen point of sale.
Show children Hide children
addressobject
The address of the physical store where the account holder will process payments from.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
fullPhoneNumberstring
The phone number of the store provided as a single string. It will be handled as a landline phone.

Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"
logostring
Store logo for payment method setup.
merchantAccountstring
The merchant account to which the store belongs.
merchantCategoryCodestring
The merchant category code (MCC) that classifies the business of the account holder.
merchantHouseNumberstring
Merchant house number for payment method setup.
phoneNumberobject
The phone number of the store.
Show children Hide children
phoneCountryCodestring
The two-character country code of the phone number.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

phoneNumberstring
The phone number.

The inclusion of the phone number country code is not necessary.

phoneTypestring
The type of the phone number.

The following values are permitted: Landline, Mobile, SIP, Fax.

shopperInteractionstring
The sales channel. Possible values: Ecommerce, POS.
splitConfigurationUUIDstring
The unique reference for the split configuration, returned when you configure splits in your Customer Area. When this is provided, the virtualAccount is also required. Adyen uses the configuration and the virtualAccount to split funds between accounts in your platform.
statusstring
The status of the store. Possible values: Pending, Active, Inactive, InactiveWithModifications, Closed.
storestring
Adyen-generated unique alphanumeric identifier (UUID) for the store, returned in the response when you create a store. Required when updating an existing store in an /updateAccountHolder request.
storeNamestring
The name of the account holder's store. This value is shown in shopper statements.

Length: Between 3 to 22 characters

The following characters are not supported: :;}{$#@!|<>%^*+=\

Note: storeName does not appear in American Express shopper statements by default. Contact Adyen Support to enable this for American Express.
storeReferencestring
Your unique identifier for the store. The Customer Area also uses this value for the store description.

Length: Between 3 to 128 characters

The following characters are not supported: :;}{$#@!|<>%^*+=\

virtualAccountstring
The account holder's accountCode where the split amount will be sent. Required when you provide the splitConfigurationUUID.
webAddressstring
URL of the ecommerce store.
webAddressstring
The URL of the website of the account holder.
accountHolderStatusobject
The status of the account holder.
Show children Hide children
eventsarray[object]
A list of events scheduled for the account holder.
Show children Hide children
eventstring
The event.

Permitted values: InactivateAccount, RefundNotPaidOutTransfers. For more information, refer to Verification checks.

executionDatestring
The date on which the event will take place.
reasonstring
The reason why this event has been created.
payoutStateobject
The payout state of the account holder.
Show children Hide children
allowPayoutboolean
Indicates whether payouts are allowed. This field is the overarching payout status, and is the aggregate of multiple conditions (e.g., KYC status, disabled flag, etc). If this field is false, no payouts will be permitted for any of the account holder's accounts. If this field is true, payouts will be permitted for any of the account holder's accounts.
disableReasonstring
The reason why payouts (to all of the account holder's accounts) have been disabled (by the platform). If the disabled field is true, this field can be used to explain why.
disabledboolean
Indicates whether payouts have been disabled (by the platform) for all of the account holder's accounts. A platform may enable and disable this field at their discretion. If this field is true, allowPayout will be false and no payouts will be permitted for any of the account holder's accounts. If this field is false, allowPayout may or may not be enabled, depending on other factors.
notAllowedReasonstring
The reason why payouts (to all of the account holder's accounts) have been disabled (by Adyen). If payouts have been disabled by Adyen, this field will explain why. If this field is blank, payouts have not been disabled by Adyen.
payoutLimitobject
The maximum amount that payouts are limited to. Only applies if payouts are allowed but limited.
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
tierNumberinteger
The payout tier that the account holder occupies.
processingStateobject
The processing state of the account holder.
Show children Hide children
disableReasonstring
The reason why processing has been disabled.
disabledboolean
Indicates whether the processing of payments is allowed.
processedFromobject
The lower bound of the processing tier (i.e., an account holder must have processed at least this amount of money in order to be placed into this tier).
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
processedToobject
The upper bound of the processing tier (i.e., an account holder must have processed less than this amount of money in order to be placed into this tier).
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
tierNumberinteger
The processing tier that the account holder occupies.
statusstring
The status of the account holder.

Permitted values: Active, Inactive, Suspended, Closed.

statusReasonstring
The reason why the status was assigned to the account holder.
accountsarray[object]
A list of the accounts under the account holder.
Show children Hide children
accountCodestring
The code of the account.
bankAccountUUIDstring
The bankAccountUUID of the bank account held by the account holder to couple the account with. Scheduled payouts in currencies matching the currency of this bank account will be sent to this bank account. Payouts in different currencies will be sent to a matching bank account of the account holder.
beneficiaryAccountstring
The beneficiary of the account.
beneficiaryMerchantReferencestring
The reason that a beneficiary has been set up for this account. This may have been supplied during the setup of a beneficiary at the discretion of the executing user.
descriptionstring
A description of the account.
metadataobject
A set of key and value pairs for general use by the merchant. The keys do not have specific names and may be used for storing miscellaneous data as desired.

Note that during an update of metadata, the omission of existing key-value pairs will result in the deletion of those key-value pairs.

payoutMethodCodestring
The payout method code held by the account holder to couple the account with. Scheduled card payouts will be sent using this payout method code.
payoutScheduleobject
The account's payout schedule.
Show children Hide children
nextScheduledPayoutstring
The date of the next scheduled payout.
schedulestring
The payout schedule for the account.

Possible values: DEFAULT, DAILY, DAILY_US, DAILY_EU, DAILY_AU, DAILY_SG, WEEKLY, WEEKLY_ON_TUE_FRI_MIDNIGHT, BIWEEKLY_ON_1ST_AND_15TH_AT_MIDNIGHT, MONTHLY, HOLD.

HOLD prevents scheduled payouts, but you can still initiate payouts manually.

payoutSpeedstring
Speed with which payouts for this account are processed. Permitted values: STANDARD, SAME_DAY.
statusstring
The status of the account. Possible values: Active, Inactive, Suspended, Closed.
descriptionstring
The description of the account holder.
invalidFieldsarray[object]
Contains field validation errors that would prevent requests from being processed.
Show children Hide children
errorCodeinteger
The validation error code.
errorDescriptionstring
A description of the validation error.
fieldTypeobject
The type of error field.
Show children Hide children
fieldstring
The full name of the property.
fieldNamestring
The type of the field.
shareholderCodestring
The code of the shareholder that the field belongs to. If empty, the field belongs to an account holder.
legalEntitystring
The legal entity of the account holder.
migrationDataobject
Details of the account holder migrated to the balance platform.
Show children Hide children
accountHolderIdstring
The unique identifier of the account holder in the balance platform.
balancePlatformstring
The unique identifier of the balance platfrom to which the account holder was migrated.
migratedboolean
Set to true if the account holder has been migrated.
migratedAccountsarray[object]
Contains the mapping of virtual account codes (classic integration) to the balance account codes (balance platform) associated with the migrated account holder.
Show children Hide children
accountCodestring
The unique identifier of the account of the migrated account holder in the classic integration.
balanceAccountIdstring
The unique identifier of the account of the migrated account holder in the balance platform.
migratedShareholdersarray[object]
Contains the mapping of shareholders associated with the migrated legal entities.
Show children Hide children
legalEntityCodestring
The unique identifier of the legal entity of that shareholder in the balance platform.
shareholderCodestring
The unique identifier of the account of the migrated shareholder in the classic integration.
migratedStoresarray[object]
Contains the mapping of business lines and stores associated with the migrated account holder.
Show children Hide children
businessLineIdstring
The unique identifier of the business line associated with the migrated account holder in the balance platform.
storeCodestring
The unique identifier of the store associated with the migrated account holder in the classic integration.
storeIdstring
The unique identifier of the store associated with the migrated account holder in the balance platform.
storeReferencestring
Your reference for the store in the classic integration. The Customer Area uses this value for the store description.
migrationDatestring
The date when account holder was migrated.
primaryCurrencystring
The three-character ISO currency code, with which the prospective account holder primarily deals.
pspReferencestring
The reference of a request. Can be used to uniquely identify the request.
resultCodestring
The result code.
systemUpToDateTimestring
The time that shows how up to date is the information in the response.
verificationobject
The details of KYC Verification of the account holder.
Show children Hide children
accountHolderobject
The results of the checks on the account holder.
Show children Hide children
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

bankAccountsarray[object]
The results of the checks on the bank accounts.
Show children Hide children
bankAccountUUIDstring
The unique ID of the bank account to which the check applies.
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

cardsarray[object]
The results of the checks on the cards.
Show children Hide children
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

payoutMethodCodestring
The unique ID of the card to which the check applies.
shareholdersarray[object]
The results of the checks on the shareholders.
Show children Hide children
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

shareholderCodestring
The code of the shareholder to which the check applies.
signatoriesarray[object]
The results of the checks on the signatories.
Show children Hide children
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

signatoryCodestring
The code of the signatory to which the check applies.
202 - Accepted
The request has been accepted for processing, but the processing has not been completed.
Show moreShow less
accountHolderCodestring
The code of the account holder.
accountHolderDetailsobject
Details of the account holder.
Show children Hide children
addressobject
The address of the account holder.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
bankAccountDetailsarray[object]
Array of bank accounts associated with the account holder. For details about the required bankAccountDetail fields, see Required information.
Show children Hide children
accountNumberstring
The bank account number (without separators).

Refer to Required information for details on field requirements.

accountTypestring
The type of bank account. Only applicable to bank accounts held in the USA. The permitted values are: checking, savings.

Refer to Required information for details on field requirements.

bankAccountNamestring
The name of the bank account.
bankAccountReferencestring
Merchant reference to the bank account.
bankAccountUUIDstring
The unique identifier (UUID) of the Bank Account.

If, during an account holder create or update request, this field is left blank (but other fields provided), a new Bank Account will be created with a procedurally-generated UUID.

If, during an account holder create request, a UUID is provided, the creation of the Bank Account will fail while the creation of the account holder will continue.

If, during an account holder update request, a UUID that is not correlated with an existing Bank Account is provided, the update of the account holder will fail.

If, during an account holder update request, a UUID that is correlated with an existing Bank Account is provided, the existing Bank Account will be updated.

bankBicSwiftstring
The bank identifier code.

Refer to Required information for details on field requirements.

bankCitystring
The city in which the bank branch is located.

Refer to Required information for details on field requirements.

bankCodestring
The bank code of the banking institution with which the bank account is registered.

Refer to Required information for details on field requirements.

bankNamestring
The name of the banking institution with which the bank account is held.

Refer to Required information for details on field requirements.

branchCodestring
The branch code of the branch under which the bank account is registered. The value to be specified in this parameter depends on the country of the bank account:

United States - Routing number

United Kingdom - Sort code

Germany - Bankleitzahl

Refer to Required information for details on field requirements.

checkCodestring
The check code of the bank account.

Refer to Required information for details on field requirements.

countryCodestring
The two-letter country code in which the bank account is registered.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

Refer to Required information for details on field requirements.

currencyCodestring
The currency in which the bank account deals.

The permitted currency codes are defined in ISO-4217 (e.g. 'EUR').

ibanstring
The international bank account number.

The IBAN standard is defined in ISO-13616.

Refer to Required information for details on field requirements.

ownerCitystring
The city of residence of the bank account owner.

Refer to Required information for details on field requirements.

ownerCountryCodestring
The country code of the country of residence of the bank account owner.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

Refer to Required information for details on field requirements.

ownerDateOfBirthstringDeprecated
The date of birth of the bank account owner. The date should be in ISO-8601 format yyyy-mm-dd (e.g. 2000-01-31).
ownerHouseNumberOrNamestring
The house name or number of the residence of the bank account owner.

Refer to Required information for details on field requirements.

ownerNamestring
The name of the bank account owner.

Refer to Required information for details on field requirements.

ownerNationalitystring
The country code of the country of nationality of the bank account owner.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

Refer to Required information for details on field requirements.

ownerPostalCodestring
The postal code of the residence of the bank account owner.

Refer to Required information for details on field requirements.

ownerStatestring
The state of residence of the bank account owner.

Refer to Required information for details on field requirements.

ownerStreetstring
The street name of the residence of the bank account owner.

Refer to Required information for details on field requirements.

primaryAccountboolean
If set to true, the bank account is a primary account.
taxIdstring
The tax ID number.

Refer to Required information for details on field requirements.

urlForVerificationstring
The URL to be used for bank account verification. This may be generated on bank account creation.

Refer to Required information for details on field requirements.

bankAggregatorDataReferencestring
The opaque reference value returned by the Adyen API during bank account login.
businessDetailsobject
Details about the business or nonprofit account holder. Required when creating an account holder with legalEntity Business or NonProfit.
Show children Hide children
doingBusinessAsstring
The registered name of the company (if it differs from the legal name of the company).
legalBusinessNamestring
The legal name of the company.
listedUltimateParentCompanyarray[object]
Information about the parent public company. Required if the account holder is 100% owned by a publicly listed company.
Show children Hide children
addressobject
Address of the ultimate parent company.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
businessDetailsobject
Details about the ultimate parent company's business.
Show children Hide children
legalBusinessNamestring
The legal name of the company.
registrationNumberstring
The registration number of the company.
stockExchangestring
Market Identifier Code (MIC).
stockNumberstring
International Securities Identification Number (ISIN).
stockTickerstring
Stock Ticker symbol.
ultimateParentCompanyCodestring
Adyen-generated unique alphanumeric identifier (UUID) for the entry, returned in the response when you create an ultimate parent company. Required when updating an existing entry in an /updateAccountHolder request.
registrationNumberstring
The registration number of the company.
shareholdersarray[object]
Array containing information about individuals associated with the account holder either through ownership or control. For details about how you can identify them, refer to our verification guide.
Show children Hide children
addressobject
The address of the person.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
emailstring
The e-mail address of the person.
fullPhoneNumberstring
The phone number of the person provided as a single string. It will be handled as a landline phone. Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"
jobTitlestring
Job title of the person. Required when the shareholderType is Controller.

Example values: Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, President, Vice President, Executive President, Managing Member, Partner, Treasurer, Director, or Other.
nameobject
The name of the person.
Show children Hide children
firstNamestring
Max length: 80
The first name.
genderstring
Max length: 1
The gender.

The following values are permitted: MALE, FEMALE, UNKNOWN.

infixstring
Max length: 20
The name's infix, if applicable.

A maximum length of twenty (20) characters is imposed.

lastNamestring
Max length: 80
The last name.
personalDataobject
Contains information about the person.
Show children Hide children
dateOfBirthstring
The person's date of birth, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
documentDataarray[object]
Array that contains information about the person's identification document. You can submit only one entry per document type.
Show children Hide children
expirationDatestring
The expiry date of the document, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
issuerCountrystring
Min length: 2Max length: 2
The country where the document was issued, in the two-character ISO 3166-1 alpha-2 format. For example, NL.
issuerStatestring
The state where the document was issued (if applicable).
numberstring
The number in the document.
typestring
The type of the document. Possible values: ID, DRIVINGLICENSE, PASSPORT, SOCIALSECURITY, VISA.

To delete an existing entry for a document type, send only the type field in your request.
nationalitystring
Min length: 2Max length: 2
The nationality of the person represented by a two-character country code, in ISO 3166-1 alpha-2 format. For example, NL.

phoneNumberobject
The phone number of the person.
Show children Hide children
phoneCountryCodestring
The two-character country code of the phone number.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

phoneNumberstring
The phone number.

The inclusion of the phone number country code is not necessary.

phoneTypestring
The type of the phone number.

The following values are permitted: Landline, Mobile, SIP, Fax.

shareholderCodestring
The unique identifier (UUID) of the shareholder entry.

If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Shareholder will be created with a procedurally-generated UUID.

If, during an Account Holder create request, a UUID is provided, the creation of Account Holder will fail with a validation Error..

If, during an Account Holder update request, a UUID that is not correlated with an existing Shareholder is provided, the update of the Shareholder will fail.

If, during an Account Holder update request, a UUID that is correlated with an existing Shareholder is provided, the existing Shareholder will be updated.

shareholderReferencestring
Your reference for the shareholder entry.
shareholderTypestring
Specifies how the person is associated with the account holder.

Possible values:

Owner: Individuals who directly or indirectly own 25% or more of a company.

Controller: Individuals who are members of senior management staff responsible for managing a company or organization.

webAddressstring
The URL of the person's website.
signatoriesarray[object]
Signatories associated with the company. Each array entry should represent one signatory.
Show children Hide children
addressobject
The address of the person.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
emailstring
The e-mail address of the person.
fullPhoneNumberstring
The phone number of the person provided as a single string. It will be handled as a landline phone. Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"
jobTitlestring
Job title of the signatory.

Example values: Chief Executive Officer, Chief Financial Officer, Chief Operating Officer, President, Vice President, Executive President, Managing Member, Partner, Treasurer, Director, or Other.
nameobject
The name of the person.
Show children Hide children
firstNamestring
Max length: 80
The first name.
genderstring
Max length: 1
The gender.

The following values are permitted: MALE, FEMALE, UNKNOWN.

infixstring
Max length: 20
The name's infix, if applicable.

A maximum length of twenty (20) characters is imposed.

lastNamestring
Max length: 80
The last name.
personalDataobject
Contains information about the person.
Show children Hide children
dateOfBirthstring
The person's date of birth, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
documentDataarray[object]
Array that contains information about the person's identification document. You can submit only one entry per document type.
Show children Hide children
expirationDatestring
The expiry date of the document, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
issuerCountrystring
Min length: 2Max length: 2
The country where the document was issued, in the two-character ISO 3166-1 alpha-2 format. For example, NL.
issuerStatestring
The state where the document was issued (if applicable).
numberstring
The number in the document.
typestring
The type of the document. Possible values: ID, DRIVINGLICENSE, PASSPORT, SOCIALSECURITY, VISA.

To delete an existing entry for a document type, send only the type field in your request.
nationalitystring
Min length: 2Max length: 2
The nationality of the person represented by a two-character country code, in ISO 3166-1 alpha-2 format. For example, NL.

phoneNumberobject
The phone number of the person.
Show children Hide children
phoneCountryCodestring
The two-character country code of the phone number.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

phoneNumberstring
The phone number.

The inclusion of the phone number country code is not necessary.

phoneTypestring
The type of the phone number.

The following values are permitted: Landline, Mobile, SIP, Fax.

signatoryCodestring
The unique identifier (UUID) of the signatory.

If, during an Account Holder create or update request, this field is left blank (but other fields provided), a new Signatory will be created with a procedurally-generated UUID.

If, during an Account Holder create request, a UUID is provided, the creation of the Signatory will fail while the creation of the Account Holder will continue.

If, during an Account Holder update request, a UUID that is not correlated with an existing Signatory is provided, the update of the Signatory will fail.

If, during an Account Holder update request, a UUID that is correlated with an existing Signatory is provided, the existing Signatory will be updated.

signatoryReferencestring
Your reference for the signatory.
webAddressstring
The URL of the person's website.
taxIdstring
The tax ID of the company.
emailstring
The email address of the account holder.
fullPhoneNumberstring
The phone number of the account holder provided as a single string. It will be handled as a landline phone. Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"
individualDetailsobject
Details about the individual account holder. Required when creating an account holder with legalEntity Individual.

Show children Hide children
nameobject
The name of the individual.

Make sure your account holder registers using the name shown on their Photo ID. Maximum length: 80 characters Cannot contain numbers. /n Cannot be empty.

Show children Hide children
firstNamestring
Max length: 80
The first name.
genderstring
Max length: 1
The gender.

The following values are permitted: MALE, FEMALE, UNKNOWN.

infixstring
Max length: 20
The name's infix, if applicable.

A maximum length of twenty (20) characters is imposed.

lastNamestring
Max length: 80
The last name.
personalDataobject
Personal information of the individual.
Show children Hide children
dateOfBirthstring
The person's date of birth, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
documentDataarray[object]
Array that contains information about the person's identification document. You can submit only one entry per document type.
Show children Hide children
expirationDatestring
The expiry date of the document, in ISO-8601 YYYY-MM-DD format. For example, 2000-01-31.
issuerCountrystring
Min length: 2Max length: 2
The country where the document was issued, in the two-character ISO 3166-1 alpha-2 format. For example, NL.
issuerStatestring
The state where the document was issued (if applicable).
numberstring
The number in the document.
typestring
The type of the document. Possible values: ID, DRIVINGLICENSE, PASSPORT, SOCIALSECURITY, VISA.

To delete an existing entry for a document type, send only the type field in your request.
nationalitystring
Min length: 2Max length: 2
The nationality of the person represented by a two-character country code, in ISO 3166-1 alpha-2 format. For example, NL.

lastReviewDatestring
Date when you last reviewed the account holder's information, in ISO-8601 YYYY-MM-DD format. For example, 2020-01-31.
merchantCategoryCodestring
The Merchant Category Code of the account holder.

If not specified in the request, this will be derived from the platform account (which is configured by Adyen).

metadataobject
A set of key and value pairs for general use by the account holder or merchant. The keys do not have specific names and may be used for storing miscellaneous data as desired.

The values being stored have a maximum length of eighty (80) characters and will be truncated if necessary. Note that during an update of metadata, the omission of existing key-value pairs will result in the deletion of those key-value pairs.

payoutMethodsarray[object]
Array of tokenized card details associated with the account holder. For details about how you can use the tokens to pay out, refer to Pay out to cards.
Show children Hide children
merchantAccountstring
The merchantAccount you used in the /payments request when you saved the account holder's card details.
payoutMethodCodestring
Adyen-generated unique alphanumeric identifier (UUID) for the payout method, returned in the response when you create a payout method. Required when updating an existing payout method in an /updateAccountHolder request.
payoutMethodReferencestring
Your reference for the payout method.
recurringDetailReferencestring
The recurringDetailReference returned in the /payments response when you saved the account holder's card details.
shopperReferencestring
The shopperReference you sent in the /payments request when you saved the account holder's card details.
phoneNumberobject
The phone number of the account holder.

Required if a fullPhoneNumber is not provided.

Show children Hide children
phoneCountryCodestring
The two-character country code of the phone number.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

phoneNumberstring
The phone number.

The inclusion of the phone number country code is not necessary.

phoneTypestring
The type of the phone number.

The following values are permitted: Landline, Mobile, SIP, Fax.

principalBusinessAddressobject
The principal business address of the account holder.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
storeDetailsarray[object]
Array of stores associated with the account holder. Required when onboarding account holders that have an Adyen point of sale.
Show children Hide children
addressobject
The address of the physical store where the account holder will process payments from.
Show children Hide children
citystring
The name of the city. Required if the houseNumberOrName, street, postalCode, or stateOrProvince are provided.
countrystring
The two-character country code of the address in ISO-3166-1 alpha-2 format. For example, NL.
houseNumberOrNamestring
The number or name of the house.
postalCodestring
The postal code. Required if the houseNumberOrName, street, city, or stateOrProvince are provided.

Maximum length:

5 digits for addresses in the US.

10 characters for all other countries.

stateOrProvincestring
The abbreviation of the state or province. Required if the houseNumberOrName, street, city, or postalCode are provided.

Maximum length:

2 characters for addresses in the US or Canada.

3 characters for all other countries.

streetstring
The name of the street. Required if the houseNumberOrName, city, postalCode, or stateOrProvince are provided.
fullPhoneNumberstring
The phone number of the store provided as a single string. It will be handled as a landline phone.

Examples: "0031 6 11 22 33 44", "+316/1122-3344", "(0031) 611223344"
logostring
Store logo for payment method setup.
merchantAccountstring
The merchant account to which the store belongs.
merchantCategoryCodestring
The merchant category code (MCC) that classifies the business of the account holder.
merchantHouseNumberstring
Merchant house number for payment method setup.
phoneNumberobject
The phone number of the store.
Show children Hide children
phoneCountryCodestring
The two-character country code of the phone number.

The permitted country codes are defined in ISO-3166-1 alpha-2 (e.g. 'NL').

phoneNumberstring
The phone number.

The inclusion of the phone number country code is not necessary.

phoneTypestring
The type of the phone number.

The following values are permitted: Landline, Mobile, SIP, Fax.

shopperInteractionstring
The sales channel. Possible values: Ecommerce, POS.
splitConfigurationUUIDstring
The unique reference for the split configuration, returned when you configure splits in your Customer Area. When this is provided, the virtualAccount is also required. Adyen uses the configuration and the virtualAccount to split funds between accounts in your platform.
statusstring
The status of the store. Possible values: Pending, Active, Inactive, InactiveWithModifications, Closed.
storestring
Adyen-generated unique alphanumeric identifier (UUID) for the store, returned in the response when you create a store. Required when updating an existing store in an /updateAccountHolder request.
storeNamestring
The name of the account holder's store. This value is shown in shopper statements.

Length: Between 3 to 22 characters

The following characters are not supported: :;}{$#@!|<>%^*+=\

Note: storeName does not appear in American Express shopper statements by default. Contact Adyen Support to enable this for American Express.
storeReferencestring
Your unique identifier for the store. The Customer Area also uses this value for the store description.

Length: Between 3 to 128 characters

The following characters are not supported: :;}{$#@!|<>%^*+=\

virtualAccountstring
The account holder's accountCode where the split amount will be sent. Required when you provide the splitConfigurationUUID.
webAddressstring
URL of the ecommerce store.
webAddressstring
The URL of the website of the account holder.
accountHolderStatusobject
The status of the account holder.
Show children Hide children
eventsarray[object]
A list of events scheduled for the account holder.
Show children Hide children
eventstring
The event.

Permitted values: InactivateAccount, RefundNotPaidOutTransfers. For more information, refer to Verification checks.

executionDatestring
The date on which the event will take place.
reasonstring
The reason why this event has been created.
payoutStateobject
The payout state of the account holder.
Show children Hide children
allowPayoutboolean
Indicates whether payouts are allowed. This field is the overarching payout status, and is the aggregate of multiple conditions (e.g., KYC status, disabled flag, etc). If this field is false, no payouts will be permitted for any of the account holder's accounts. If this field is true, payouts will be permitted for any of the account holder's accounts.
disableReasonstring
The reason why payouts (to all of the account holder's accounts) have been disabled (by the platform). If the disabled field is true, this field can be used to explain why.
disabledboolean
Indicates whether payouts have been disabled (by the platform) for all of the account holder's accounts. A platform may enable and disable this field at their discretion. If this field is true, allowPayout will be false and no payouts will be permitted for any of the account holder's accounts. If this field is false, allowPayout may or may not be enabled, depending on other factors.
notAllowedReasonstring
The reason why payouts (to all of the account holder's accounts) have been disabled (by Adyen). If payouts have been disabled by Adyen, this field will explain why. If this field is blank, payouts have not been disabled by Adyen.
payoutLimitobject
The maximum amount that payouts are limited to. Only applies if payouts are allowed but limited.
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
tierNumberinteger
The payout tier that the account holder occupies.
processingStateobject
The processing state of the account holder.
Show children Hide children
disableReasonstring
The reason why processing has been disabled.
disabledboolean
Indicates whether the processing of payments is allowed.
processedFromobject
The lower bound of the processing tier (i.e., an account holder must have processed at least this amount of money in order to be placed into this tier).
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
processedToobject
The upper bound of the processing tier (i.e., an account holder must have processed less than this amount of money in order to be placed into this tier).
Show children Hide children
currencystring
Min length: 3Max length: 3
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
tierNumberinteger
The processing tier that the account holder occupies.
statusstring
The status of the account holder.

Permitted values: Active, Inactive, Suspended, Closed.

statusReasonstring
The reason why the status was assigned to the account holder.
accountsarray[object]
A list of the accounts under the account holder.
Show children Hide children
accountCodestring
The code of the account.
bankAccountUUIDstring
The bankAccountUUID of the bank account held by the account holder to couple the account with. Scheduled payouts in currencies matching the currency of this bank account will be sent to this bank account. Payouts in different currencies will be sent to a matching bank account of the account holder.
beneficiaryAccountstring
The beneficiary of the account.
beneficiaryMerchantReferencestring
The reason that a beneficiary has been set up for this account. This may have been supplied during the setup of a beneficiary at the discretion of the executing user.
descriptionstring
A description of the account.
metadataobject
A set of key and value pairs for general use by the merchant. The keys do not have specific names and may be used for storing miscellaneous data as desired.

Note that during an update of metadata, the omission of existing key-value pairs will result in the deletion of those key-value pairs.

payoutMethodCodestring
The payout method code held by the account holder to couple the account with. Scheduled card payouts will be sent using this payout method code.
payoutScheduleobject
The account's payout schedule.
Show children Hide children
nextScheduledPayoutstring
The date of the next scheduled payout.
schedulestring
The payout schedule for the account.

Possible values: DEFAULT, DAILY, DAILY_US, DAILY_EU, DAILY_AU, DAILY_SG, WEEKLY, WEEKLY_ON_TUE_FRI_MIDNIGHT, BIWEEKLY_ON_1ST_AND_15TH_AT_MIDNIGHT, MONTHLY, HOLD.

HOLD prevents scheduled payouts, but you can still initiate payouts manually.

payoutSpeedstring
Speed with which payouts for this account are processed. Permitted values: STANDARD, SAME_DAY.
statusstring
The status of the account. Possible values: Active, Inactive, Suspended, Closed.
descriptionstring
The description of the account holder.
invalidFieldsarray[object]
Contains field validation errors that would prevent requests from being processed.
Show children Hide children
errorCodeinteger
The validation error code.
errorDescriptionstring
A description of the validation error.
fieldTypeobject
The type of error field.
Show children Hide children
fieldstring
The full name of the property.
fieldNamestring
The type of the field.
shareholderCodestring
The code of the shareholder that the field belongs to. If empty, the field belongs to an account holder.
legalEntitystring
The legal entity of the account holder.
migrationDataobject
Details of the account holder migrated to the balance platform.
Show children Hide children
accountHolderIdstring
The unique identifier of the account holder in the balance platform.
balancePlatformstring
The unique identifier of the balance platfrom to which the account holder was migrated.
migratedboolean
Set to true if the account holder has been migrated.
migratedAccountsarray[object]
Contains the mapping of virtual account codes (classic integration) to the balance account codes (balance platform) associated with the migrated account holder.
Show children Hide children
accountCodestring
The unique identifier of the account of the migrated account holder in the classic integration.
balanceAccountIdstring
The unique identifier of the account of the migrated account holder in the balance platform.
migratedShareholdersarray[object]
Contains the mapping of shareholders associated with the migrated legal entities.
Show children Hide children
legalEntityCodestring
The unique identifier of the legal entity of that shareholder in the balance platform.
shareholderCodestring
The unique identifier of the account of the migrated shareholder in the classic integration.
migratedStoresarray[object]
Contains the mapping of business lines and stores associated with the migrated account holder.
Show children Hide children
businessLineIdstring
The unique identifier of the business line associated with the migrated account holder in the balance platform.
storeCodestring
The unique identifier of the store associated with the migrated account holder in the classic integration.
storeIdstring
The unique identifier of the store associated with the migrated account holder in the balance platform.
storeReferencestring
Your reference for the store in the classic integration. The Customer Area uses this value for the store description.
migrationDatestring
The date when account holder was migrated.
primaryCurrencystring
The three-character ISO currency code, with which the prospective account holder primarily deals.
pspReferencestring
The reference of a request. Can be used to uniquely identify the request.
resultCodestring
The result code.
systemUpToDateTimestring
The time that shows how up to date is the information in the response.
verificationobject
The details of KYC Verification of the account holder.
Show children Hide children
accountHolderobject
The results of the checks on the account holder.
Show children Hide children
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

bankAccountsarray[object]
The results of the checks on the bank accounts.
Show children Hide children
bankAccountUUIDstring
The unique ID of the bank account to which the check applies.
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

cardsarray[object]
The results of the checks on the cards.
Show children Hide children
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

payoutMethodCodestring
The unique ID of the card to which the check applies.
shareholdersarray[object]
The results of the checks on the shareholders.
Show children Hide children
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

shareholderCodestring
The code of the shareholder to which the check applies.
signatoriesarray[object]
The results of the checks on the signatories.
Show children Hide children
checksarray[object]
A list of the checks and their statuses.
Show children Hide children
requiredFieldsarray[string]
A list of the fields required for execution of the check.
statusstring
The status of the check.

Possible values: AWAITING_DATA , DATA_PROVIDED, FAILED, INVALID_DATA, PASSED, PENDING, RETRY_LIMIT_REACHED.
summaryobject
A summary of the execution of the check.
Show children Hide children
kycCheckCodeinteger
The code of the check. For possible values, refer to Verification codes.
kycCheckDescriptionstring
A description of the check.
typestring
The type of check.

Possible values:

BANK_ACCOUNT_VERIFICATION: Used in v5 and earlier. Replaced by PAYOUT_METHOD_VERIFICATION in v6 and later.

COMPANY_VERIFICATION

CARD_VERIFICATION

IDENTITY_VERIFICATION

LEGAL_ARRANGEMENT_VERIFICATION

NONPROFIT_VERIFICATION

PASSPORT_VERIFICATION

PAYOUT_METHOD_VERIFICATION: Used in v6 and later.

PCI_VERIFICATION

signatoryCodestring
The code of the signatory to which the check applies.
400 - Bad Request
A problem reading or understanding the request.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
401 - Unauthorized
Authentication required.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
403 - Forbidden
Insufficient permissions to process the request.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
422 - Unprocessable Entity
A request validation error.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.
500 - Internal Server Error
The server could not process the request.
Show more Show less
errorCodestring
The error code mapped to the error message.
errorTypestring
The category of the error.
messagestring
A short explanation of the issue.
pspReferencestring
The PSP reference of the payment.
statusinteger
The HTTP response status.

Get an account holder

Request Parameters

Response parameters

HTTP Responses

200 - OK

202 - Accepted

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error