Create an account holder

post/accountHolders

API Version

Creates an account holder linked to a legal entity.

Endpoint destination URL

https://balanceplatform-api-test.adyen.com/bcl/v2/accountHolders

Request Parameters

Required

Optional

The unique identifier of the balance platform to which the account holder belongs. Required in the request if your API credentials can be used for multiple balance platforms.

Contains key-value pairs that specify the actions that an account holder can do in your platform. The key is a capability required for your integration. For example, issueCard for Issuing. The value is an object containing the settings for the capability.

Contact details of the account holder.

Max length: 300

Your description for the account holder.

The unique identifier of the legal entity associated with the account holder. Adyen performs a verification process against the legal entity of the account holder.

A set of key and value pairs for general use. 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.

Max length: 150

Your reference for the account holder.

The time zone of the account holder. For example, Europe/Amsterdam. Defaults to the time zone of the balance platform if no time zone is set. For possible values, see the list of time zone codes.

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.
balancePlatformstring
The unique identifier of the balance platform to which the account holder belongs. Required in the request if your API credentials can be used for multiple balance platforms.
capabilitiesobject
Contains key-value pairs that specify the actions that an account holder can do in your platform. The key is a capability required for your integration. For example, issueCard for Issuing. The value is an object containing the settings for the capability.
allowedboolean
Indicates whether the capability is allowed. Adyen sets this to true if the verification is successful and the account holder is permitted to use the capability.
allowedLevelstring
The capability level that is allowed for the account holder.

Possible values: notApplicable, low, medium, high.
allowedSettingsobject
A JSON object containing the settings that are allowed for the account holder.
amountPerIndustryobject
currencystring
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
authorizedCardUsersboolean
fundingSourcearray[string]
intervalstring
maxAmountobject
currencystring
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
enabledboolean
Indicates whether the capability is enabled. If false, the capability is temporarily disabled for the account holder.
problemsarray[object]
Contains verification errors and the actions that you can take to resolve them.
entityobject
Contains the type of the entity and the corresponding ID.
documentsarray[string]
List of document IDs to which the verification errors related to the capabilities correspond to.
idstring
The ID of the entity.
ownerobject
Contains details about the owner of the entity that has an error.
documentsarray[string]
List of document IDs to which the verification errors related to the capabilities correspond to.
idstring
The ID of the entity.
typestring
Type of entity.

Possible values: LegalEntity, BankAccount, Document.
typestring
Type of entity.

Possible values: LegalEntity, BankAccount, Document.
verificationErrorsarray[object]
Contains information about the verification error.
capabilitiesarray[string]
Contains the capabilities that the verification error applies to.
codestring
The verification error code.
messagestring
A description of the error.
remediatingActionsarray[object]
Contains the actions that you can take to resolve the verification error.
codestring
The remediating action code.
messagestring
A description of how you can resolve the verification error.
subErrorsarray[object]
Contains more granular information about the verification error.
capabilitiesarray[string]
Contains the capabilities that the verification error applies to.
codestring
The verification error code.
messagestring
A description of the error.
typestring
The type of error.

Possible values:

invalidInput

dataMissing

pendingStatus

dataReview

remediatingActionsarray[object]
Contains the actions that you can take to resolve the verification error.
codestring
The remediating action code.
messagestring
A description of how you can resolve the verification error.
typestring
The type of error.

Possible values:

invalidInput

dataMissing

pendingStatus

dataReview

requestedboolean
Indicates whether the capability is requested. To check whether the account holder is permitted to use the capability, refer to the allowed field.
requestedLevelstring
The requested level of the capability. Some capabilities, such as those used in card issuing, have different levels. Levels increase the capability, but also require additional checks and increased monitoring.

Possible values: notApplicable, low, medium, high.
requestedSettingsobject
A JSON object containing the settings that were requested for the account holder.
amountPerIndustryobject
currencystring
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
authorizedCardUsersboolean
fundingSourcearray[string]
intervalstring
maxAmountobject
currencystring
The three-character ISO currency code.
valueinteger
The amount of the transaction, in minor units.
transferInstrumentsarray[object]
Contains the status of the transfer instruments associated with this capability.
allowedboolean
Indicates whether the supporting entity capability is allowed. Adyen sets this to true if the verification is successful and the account holder is permitted to use the capability.
allowedLevelstring
The capability level that is allowed for the account holder.

Possible values: notApplicable, low, medium, high.
enabledboolean
Indicates whether the capability is enabled. If false, the capability is temporarily disabled for the account holder.
idstring
The ID of the supporting entity.
requestedboolean
Indicates whether the capability is requested. To check whether the account holder is permitted to use the capability, refer to the allowed field.
requestedLevelstring
The requested level of the capability. Some capabilities, such as those used in card issuing, have different levels. Levels increase the capability, but also require additional checks and increased monitoring.

Possible values: notApplicable, low, medium, high.
verificationStatusstring
The status of the verification checks for the supporting entity capability.

Possible values:

pending: Adyen is running the verification.

invalid: The verification failed. Check if the errors array contains more information.

valid: The verification has been successfully completed.

rejected: Adyen has verified the information, but found reasons to not allow the capability.

verificationStatusstring
The status of the verification checks for the capability.

Possible values:

pending: Adyen is running the verification.

invalid: The verification failed. Check if the errors array contains more information.

valid: The verification has been successfully completed.

rejected: Adyen has verified the information, but found reasons to not allow the capability.

contactDetailsobjectDeprecated
Contact details of the account holder.
addressobject
The address of the account holder.
citystring
Max length: 3000
The name of the city. Maximum length: 3000 characters.
countrystring
The two-character ISO-3166-1 alpha-2 country code. For example, US.

If you don't know the country or are not collecting the country from the shopper, provide country as ZZ.

houseNumberOrNamestring
Max length: 3000
The number or name of the house. Maximum length: 3000 characters.
postalCodestring
A maximum of five digits for an address in the US, or a maximum of ten characters for an address in all other countries.
stateOrProvincestring
The two-character ISO 3166-2 state or province code. For example, CA in the US or ON in Canada.

Required for the US and Canada.

streetstring
Max length: 3000
The name of the street. Maximum length: 3000 characters.

The house number should not be included in this field; it should be separately provided via houseNumberOrName.

emailstring
The email address of the account holder.
phoneobject
The phone number of the account holder.
numberstring
The full phone number provided as a single string. For example, "0031 6 11 22 33 44", "+316/1122-3344",

or "(0031) 611223344".
typestring
Type of phone number. Possible values: Landline, Mobile.

webAddressstring
The URL of the account holder's website.
descriptionstring
Max length: 300
Your description for the account holder.
idstring
The unique identifier of the account holder.
legalEntityIdstring
The unique identifier of the legal entity associated with the account holder. Adyen performs a verification process against the legal entity of the account holder.
metadataobject
A set of key and value pairs for general use. 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.

migratedAccountHolderCodestring
The unique identifier of the migrated account holder in the classic integration.
primaryBalanceAccountstring
The ID of the account holder's primary balance account. By default, this is set to the first balance account that you create for the account holder. To assign a different balance account, send a PATCH request.
referencestring
Max length: 150
Your reference for the account holder.
statusstring
The status of the account holder.

Possible values:

active: The account holder is active and allowed to use its capabilities. This is the initial status for account holders and balance accounts. You can change this status to suspended or closed.

suspended: The account holder is temporarily disabled and payouts are blocked. You can change this status to active or closed.

closed: The account holder and all of its capabilities are permanently disabled. This is a final status and cannot be changed.

timeZonestring
The time zone of the account holder. For example, Europe/Amsterdam. Defaults to the time zone of the balance platform if no time zone is set. For possible values, see the list of time zone codes.
verificationDeadlinesarray[object]
List of verification deadlines and the capabilities that will be disallowed if verification errors are not resolved.
capabilitiesarray[string]
The names of the capabilities to be disallowed.
entityIdsarray[string]
The unique identifiers of the bank account(s) that the deadline applies to
expiresAtstring
The date that verification is due by before capabilities are disallowed.
400 - Bad Request
A problem reading or understanding the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
namestring
The field that has an invalid value.
valuestring
The invalid value.
messagestring
Description of the validation error.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
401 - Unauthorized
Authentication required.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
namestring
The field that has an invalid value.
valuestring
The invalid value.
messagestring
Description of the validation error.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
403 - Forbidden
Insufficient permissions to process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
namestring
The field that has an invalid value.
valuestring
The invalid value.
messagestring
Description of the validation error.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
422 - Unprocessable Entity
A request validation error.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
namestring
The field that has an invalid value.
valuestring
The invalid value.
messagestring
Description of the validation error.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
500 - Internal Server Error
The server could not process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
namestring
The field that has an invalid value.
valuestring
The invalid value.
messagestring
Description of the validation error.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.

Create an account holder

HTTP Responses

200 - OK

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error