Payment industry regulations require that a business (Adyen) verifies the identity of its clients. This means your account holders need to go through a Know Your Customer (KYC) verification process with Adyen before you can issue cards to them.
We perform the KYC checks against the legal entity of the account holder. We also need to verify individuals associated with the company or organization (such as shareholders and control officers). This means that the individuals must also be represented as legal entities within Adyen.
KYC process
You'll need to create an onboarding flow where you gather your account holder's information with your own pages and screens. You can then use the Balance Platform API to submit the required information and upload documents if needed.
To start the KYC process:
- Identify the country where the legal entity is operating in and collect the required information based on the country.
- Create legal entities and provide the required information.
- If necessary, Adyen informs you if you need to collect and upload additional documents.
Adyen uses the information you provide to verify the organization and the individuals. After Adyen confirms that the account holder passed the KYC checks, you can create a card for them.
Multiple card users under one balance account
Some use cases might require having multiple card users under one balance account, but only the account holder will go through the KYC process. For example:
- Creating named cards for multiple employees in one company.
- Creating additional cards for a spouse or children.
Confirm with your Adyen contact if you can use such a scenario, because we only allow this in specific circumstances.
Step 1: Identify country and collect required information
- Identify the country where your account holder is operating in. You need the country to know the required information that you will need to collect from them.
- Collect the required information from your account holder.
Step 2: Create legal entities
When you have collected the required information from your account holder, create legal entities for each of the following:
- The organization.
- Individuals who are the ultimate beneficial owners, control officers, and signatory for the organization.
Individuals must be linked to the organization legal entity. You can include the individual legal entities in the entityAssociations
array when you create the organization legal entity, or update the organization legal entity resource at a later time.
Select a tab below:
To create a legal entity for an organization, make a POST /legalEntities
request providing the required information based on the country.
Parameter | Required | Description |
---|---|---|
type |
![]() |
organization |
organization.legalName |
![]() |
The organization's legally registered name. |
organization.type |
![]() |
The type of organization, for example business or listedPublicCompany. Refer to Organization types for a list of possible values. |
organization.address |
![]() |
Object that contains the organization's registered or principalPlaceOfBusiness address. Provide the principalPlaceOfBusiness (where the organization operates from), if different from the registered address. |
organization.email |
![]() |
The organization's email address. |
organization.phone |
![]() |
Object that contains the organization's phone contact details. The type can be mobile, landline, sip, or fax. |
organization.doingBusinessAs |
The name the organization is locally known for. | |
organization.registrationNumber |
The organization's registration number, issued by the local Chamber of Commerce or equivalent. | |
organization.taxId |
The organization's tax number. | |
organization.description |
A description of what the organization does. | |
organization.webData |
Object that contains the organization's appAddress and webAddress . |
|
entityAssociations |
Array where you link the legal entities of individuals associated with the organization. Include this array if you have already created the legal entities for the individuals, or you can also update the resource at a later time. |
Here is an example of how you would create and provide the required information for an organization operating in the US:
curl https://balanceplatform-api-test.adyen.com/bcl/v1/legalEntities \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-d '{
"type" : "organization",
"organization" :
{
"legalName" : "Example Company",
"type" : "business",
"taxId": "101002749",
"address" : {
"street" : "Brannan Street",
"street2" : "Example Building",
"city" : "San Francisco",
"postalCode" : "94107",
"stateOrProvince" : "CA",
"country" : "US",
"type" : "principalPlaceOfBusiness"
},
"phone" : {
"type" : "mobile",
"countryCode" : "US",
"number" : "4153671502"
},
"email": "info@example.com"
}
}'
The response returns the legalEntity resource for the organization, identified by its unique id
.
{
"organization": {
"address": {
"city": "San Francisco",
"country": "US",
"postalCode": "94107",
"stateOrProvince": "CA",
"street": "Brannan Street",
"street2": "Example Building",
"type": "principalPlaceOfBusiness"
},
"email": "info@example.com",
"phone": {
"countryCode": "US",
"number": "4153671502",
"type": "mobile"
},
"legalName": "Example Company",
"taxId": "101002749",
"type": "business"
},
"type": "organization",
"id": "LE32272223222D5CKDZFL7DQC"
}
To create a legal entity for an individual, make a POST /legalEntities
request, providing the required information based on the country.
Parameter | Required | Description |
---|---|---|
type |
![]() |
individual |
individual.name |
![]() |
Object that contains the individual's firstName , lastName , and infix if applicable. |
individual.address |
![]() |
Object that contains the individual's residential address. |
individual.phone |
![]() |
Object that contains the individual's phone contact details. The type can be mobile, landline, sip, or fax. |
individual.birthData.dateOfBirth |
![]() |
In YYYY-MM-DD format. |
individual.identificationData |
Object that contains information about the individual's identification number, including:
|
|
individual.email |
The individual's email address. | |
individual.nationality |
The individual's nationality, in a two-letter country code format. |
Here is how you would create a legal entity for a signatory for an organization operating in the US:
curl https://balanceplatform-api-test.adyen.com/bcl/v1/legalEntities \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-d '{
"type": "individual",
"individual":
{
"address": {
"city": "San Francisco",
"country": "US",
"houseNumberOrName": "274",
"postalCode": "1111",
"street": "Brannan Street",
"stateOrProvince": "CA",
"type": "residential"
},
"phone": {
"countryCode": "US",
"number": "5551231234",
"type": "mobile"
},
"name": {
"firstName": "Simone",
"lastName": "Hopper"
},
"birthData": {
"dateOfBirth": "1981-12-01"
},
"email": "s.hopper@example.com"
}
}'
The response returns the legalEntity resource, identified by its unique id
. You'll need the IDs to associate the individuals with the organization legal entity.
{
"individual": {
"address": {
"city": "San Francisco",
"country": "US",
"postalCode": "1111",
"stateOrProvince": "CA",
"street": "Brannan Street",
"street2": "274",
"type": "residential"
},
"phone": {
"countryCode": "US",
"number": "5551231234",
"type": "mobile"
},
"birthData": {
"dateOfBirth": "1981-12-01"
},
"name": {
"firstName": "Simone",
"lastName": "Hopper"
},
"email": "s.hopper@example.com"
},
"type": "individual",
"id": "LE32272223222D5CK99ZQ33D7"
}
After you successfully create and provide the information for the organization and individuals, wait for Adyen to inform you of the KYC check results. In some cases, Adyen may ask you to provide additional documents.
Step 3 (Conditional): Upload additional documents
Do this step only when Adyen informs you that you need to provide additional documents.
Adyen attempts to verify the organization and the individuals based on the information that you provide. However, in some cases, the automatic verification might fail. This could be due to incorrect data or the data can't be verified. In these cases Adyen may ask you to provide additional documents.
Adyen will inform you about the type of document that you need to provide. For more information possible types of document, refer to Additional documents.
- Collect the additional document from your account holder.
-
Upload the document with a POST
/documents
request specifying:Parameter Required Description owner
Object that contains information about the legal entity the document is being uploaded for. description
Your description for the document. issuerCountry
Country that issued the document, in a two-letter country code format (for example, US). type
The type of document being uploaded. Refer to Document types for a list of possible values. attachment
Object that contains the document, which includes: contentType
: The file format.
Possible values: application/pdf, image/jpg, image/jpeg, or image/png.filename
: Name of the file with the file extension.content
: The document in a Base64 encoded format.
number
The number in the document. issuerState
The state where the ID was issued. expiryDate
The expiry date of the document in YYYY-MM-DD format. curl https://balanceplatform-api-test.adyen.com/bcl/v1/documents \ -u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \ -H "content-type: application/json" \ -d '{ "owner" : { "id" : "LE32272223222D5CGBR254SKT", "type" : "legalEntity" }, "description" : "Registration doc for Example Company", "type" : "businessRegistration", "issuerCountry" : "US", "attachment" : { "contentType" : "application/pdf", "filename" : "busReg.pdf", "content": "AAQSkZJRgABAQEAYABgAAD/s.." } }'
The response returns the document resource, identified by its unique
id
.{ "issuerCountry": "US", "type": "businessRegistration", "attachment": { "content": "AAQSkZJRgABAQEAYABgAAD/s..", "contentType": "application/pdf", "filename": "busReg.pdf" }, "description": "Registration doc for Example Company", "owner": { "id": "LE32272223222D5CK8JPC32PK", "type": "legalEntity" }, "id": "SE32272223222D5CKDZ987DQZ" }
After you successfully upload the additional documents, wait for Adyen to inform you of the KYC check results.
Updating the legal entity resource
In case an account holder wants to update their information or if you want to associate legal entities of individuals to an organization, update the existing legal entity resource with a PATCH /legalEntities/{id}
request.
Associate individuals to an organization
Specify the individuals linked to an organization legal entity in the entityAssociations
array. The array must contain the following:
Parameter | Description |
---|---|
legalEntityId |
The legal entity ID of the individual. |
type |
Specifies how the individual is connected to the organization. Possible values are:
|
jobTitle |
Required for type signatory. |
sharePercentage |
In case of type uboThroughOwnership, the percentage of shares that the individual owns. |
If the organization legal entity already exists, update the resource with a PATCH /legalEntities/{id}
request.
You are replacing the entire array when you update entityAssociations
. This means that if you want to update the type
of a particular array entry, you need to include the rest of the entries in your PATCH request.
curl https://balanceplatform-api-test.adyen.com/bcl/v1/legalEntities/LE32272223222D5CK99ZQ33D7 \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-X PATCH \
-d '{
"entityAssociations": [
{
"jobTitle": "CEO",
"legalEntityId": "LE32272223222D5CLJHN96SQQ",
"type": "uboThroughControl"
},
{
"legalEntityId": "LE3227C223222D5CKXQ439B6P",
"type": "uboThroughOwnership",
"sharePercentage": 49.9
},
{
"jobTitle": "Country Manager",
"legalEntityId": "LE32272223222D5CK99ZQ33D7",
"type": "signatory"
}
]
}'
The response contains the updated legal entity resource.
Getting the KYC check results
Your Adyen contact will inform you of the status and results of the KYC checks.
After Adyen confirms that the account holder passed the KYC checks, you can create a card for your user.
/legalEntities/{id}
request.