Payment industry regulations require Adyen to verify the identity of its clients to help prevent fraudulent activities. This means that before you or your customers can issue cards, the corresponding account holder needs to go through a Know Your Customer (KYC) verification process.
In the KYC checks, Adyen verifies:
- The identity of the account holder. When the account holder is an organization, Adyen also verifies the identity of individuals associated with it (such as shareholders and control officers).
- The account holder's bank account, when required for a use case. For example, to let an account holder transfer funds from their balance account to their bank account, Adyen must verify that the bank account exists and that the account holder owns it.
To start the checks, the account holder must provide information to Adyen. For details of what they need to provide, refer to Required information.
Account holders and legal entities
The Balance Platform API uses the legalEntity resource to handle all the account holder's information required for KYC checks. To connect the resources, you can create the legal entity first then link it at the time you create the account holder. You can also update the accountHolder resource if it already exists.
Because Adyen also needs to verify the identity of individuals associated with the organization, the individuals must also have their corresponding legalEntity resources. Then you must use the entityAssociations array to link the legal entities of individuals to the organization.
For use cases that involve moving funds between balance accounts and bank accounts, the bank accounts must be represented as transferInstrument resources linked to the organization's legal entity.
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.
If you have a similar scenario, reach out to your Adyen contact to discuss and confirm the use case.
Step 1: Identify country and collect required information
To start the KYC process, you'll need to create an onboarding flow where you gather the account holder's information with your own pages and screens.
- Identify the country where the account holder is operating in.
- Determine the required information based on the country. This includes the information about their organization, individuals associated with their organization, and their bank account details (if needed).
- Collect the required information from the account holder.
Then you'll use the Balance Platform API to submit the required information and upload documents if needed.
Step 2: Create legal entities
When you have collected the required information from the account holder, you need to create legal entities for each of the following:
- The organization.
- Individuals who are the ultimate beneficial owners, control officers, and signatories for the organization. Refer to the minimum required number for each type.
To link the legal entities, you can first create legal entities for the individuals and then include the entityAssociations array when you create the organization's legal entity. Alternatively, you can update the organization's legalEntity resource if it already exists.
Select a tab below to create legal entities:
To create a legal entity for an organization, provide all the required information in a POST /legalEntities request, specifying:
- type: Set to organization.
- organization: Object that contains required information about the organization such as the type the legalName, email,
registeredAddress, andprincipalPlaceOfBusiness. - entityAssociations: Array that contains the legal entities of individuals associated with the organization. If you have not created these yet, you can also update the organization legal entity resource later.
Here is an example of how you would create a legal entity for a private company 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" : "privateCompany",
"taxId": "101002749",
"registeredAddress" : {
"city": "San Francisco",
"country": "US",
"postalCode": "94107",
"stateOrProvince": "CA",
"street": "Brannan Street",
"street2": "Example Building"
},
"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": {
"registeredAddress": {
"city": "San Francisco",
"country": "US",
"postalCode": "94107",
"stateOrProvince": "CA",
"street": "Brannan Street",
"street2": "Example Building"
},
"email": "info@example.com",
"phone": {
"countryCode": "US",
"number": "4153671502",
"type": "mobile"
},
"legalName": "Example Company",
"taxId": "101002749",
"type": "privateCompany"
},
"type": "organization",
"id": "LE32272223222D5CKDZFL7DQC"
}To create a legal entity for an individual, provide all the required information in a POST /legalEntities request, specifying:
- type: Set to individual.
- individual: Object that contains required information about the individual such as their name and identificationData.number.
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":
{
"residentialAddress": {
"city": "San Francisco",
"country": "US",
"postalCode": "94678",
"stateOrProvince": "CA",
"street": "Brannan Street",
"street2": "274"
},
"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": {
"residentialAddress": {
"city": "San Francisco",
"country": "US",
"postalCode": "94678",
"stateOrProvince": "CA",
"street": "Brannan Street",
"street2": "274"
},
"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"
}If your use case involves moving funds between balance accounts and bank accounts, proceed to step 3 to create a transfer instrument. Otherwise, wait for Adyen to inform you of the KYC check results. In some cases, Adyen may ask you to provide additional documents.
Step 3: Create a transfer instrument
For use cases that involve moving funds between balance accounts and bank accounts, Adyen must perform checks on the bank account. To add the account holder's bank account details, provide the required information in a POST /transferInstruments request, specifying:
- type: Set to bankAccount.
- legalEntityId: Unique identifier of the organization legal entity that owns the bank account.
- bankAccount: Object that contains required information about the account holder's bank account.
For example, here's a request for adding a transfer instrument for a bank account 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 '{
"legalEntityId" : "LE32272223222D5CK99ZQ33D7",
"type" : "bankAccount",
"bankAccount" : {
"countryCode" : "US",
"currencyCode" : "USD",
"accountNumber": "1234567890",
"branchCode": "121202211",
"accountType": "checking"
}
}'The response returns the transferInstrument resource, identified by its unique id.
After you successfully create and provide the information for their bank account, wait for Adyen to inform you of the KYC check results. In some cases, Adyen may ask you to provide additional documents.
Step 4 (Conditional): Upload additional documents
Do this step only when Adyen informs you that you need to provide additional documents.
Adyen attempts to verify the account holder and their bank account 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.
For information about the types of document that Adyen might require, refer to Additional documents.
To upload an additional document:
- Collect the document from the account holder.
- Upload the document with a POST /documents request, specifying:
- attachment: Object that contains the document content, contentType, and filename.
- issuerCountry: The two-letter code of the country that issued the document.
- owner: Object that contains information about the owner of the document. This could be the unique identifier of the legal entity or of the transfer instrument.
- type: The type of document. The type of document that you can upload depends on the legal entity type. Refer to types for a full list.
The combination of owner.id, type, and document.content must be unique. If you have already submitted the same combination, you'll receive an error message.
Here is an example of how you would upload a registration document for an organization:
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" : "registrationDocument",
"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": "registrationDocument",
"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.
Associate individuals with an organization
To link legal entities of individuals to an organization, include the entityAssociations array when creating the legal entity for an organization or updating an existing legalEntity resource for the organization. The array must include:
- legalEntityId: Unique identifier of the individual legal entity.
- type: The relationship of the individual to the organization. For example, if they are a shareholder with more than 25% of shares, the value should be uboThroughOwnership.
Depending on the type, you might also need to include information such as jobTitle.
When updating the entityAssociations in a PATCH request, note that the update replaces the entire array. If you only want to update an existing array entry, make sure that your request includes the rest of the entries along with the specific change.
The example below show you would update an existing legalEntity resource with a PATCH /legalEntities/{id} 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"
},
{
"jobTitle": "Country Manager",
"legalEntityId": "LE32272223222D5CK99ZQ33D7",
"type": "signatory"
}
]
}'The response contains the updated legalEntity 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.