When a user signs up on your platform, create their entity with Adyen so that you can start issuing cards to them. Once they are onboarded with Adyen:
- You can create the corresponding account holder and balance accounts that will hold their funds within your platform.
- The verification process starts. As required by payment industry regulations, Adyen must verify your users before you can pay out their funds. The information that Adyen checks is based on the verification requirements.
On this page, we explain how you can onboard your users using the Legal Entity Management API.
Legal entities
The account holder's entity is represented in your platform as a legal entity. The legalEntity resource contains the information required for verification. For every account holder, you need to create a legal entity for their organization and the individuals associated with their organization.
The legal entity type determines the kind of information that Adyen requires for verification. For details, refer to Required information.
As part of the checks, Adyen verifies the identity of individuals that are associated with an organization. We refer to these individuals as ultimate beneficial owners (UBOs) and signatories. The table below describes the criteria for identifying them, and the minimum required number for each.
| Who | Criteria | Required number of individuals |
|---|---|---|
| UBOs through ownership | Individuals who directly or indirectly own 25% or more of the total shares, voting rights or other equity in the organization. | Between zero to four. Adyen requires information about all individuals that fit the criteria. If no one owns 25% or more of the organization, then information must be provided about UBOs through control. |
| UBOs through control | Any individuals who exercise ultimate effective control in making decisions for the whole organization. If such an individual cannot be identified, then members of senior management must be identified as UBOs through control. | At least one. Required if no one fits the criteria of UBO through ownership, or if the organization is operating in the United States. |
| Signatories | Officers or representatives who legally represent the organization towards Adyen and are authorised to enter a binding agreement with Adyen on behalf of their organization. | At least one. |
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 verification. For example, creating named cards for multiple employees in one company.
If you have a similar scenario, reach out to your Adyen contact to discuss and confirm the use case.
Before you begin
Make sure that you have API credentials for the Legal Entity Management API.
Step 1: Set up webhooks
Before you start collecting the required information from users, we recommend that you configure your system to accept our webhooks. Webhooks keep you updated on the progress of your users' verification process, merchant account and capability status changes, notify you of errors and contain instructions on how resolve them. Webhooks are crucial for a successful integration with Adyen, and the only way you'll receive automatic updates.
For instructions on how to configure webhooks, see Webhooks.
Step 2: Identify country and collect required information
Create an onboarding flow and collect information from your users with your own UI. During the onboarding, you must collect the verification requirements from your users.
You can issue cards to organizations and sole proprietors operating in the EU, the UK, and the US. In addition to the minimum required information, you also need to provide the data below.
-
Additional required information in the legal entity of the organization (only applicable for legal entities in the EU and UK):
If the country where your user is operating in does not have a VAT system, collect their tax ID and send the following instead.
Step 3: Create legal entities
A legal entity resource holds information required for the verification checks. You need to create a legal entity for the user that has a contractual relationship with your platform. You may also need to create legal entities to represent entities connected to the main user. Make sure you collect the required information for each legal entity.
Select a tab below to create different types of legal entities:
To create a legal entity for an organization, provide all the required information in a POST /legalEntities request, specifying:
| Parameter | Required | Description |
|---|---|---|
| type |  |
Set to organization. |
| organization | |
Object that contains required information about the organization such as the type, the legalName, and its registeredAddress. |
The following is an example of how to create a legal entity for a private company operating in the US.
curl https://kyc-test.adyen.com/lem/v3/legalEntities \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
"type" : "organization",
"organization" : {
"legalName" : "Example Company",
"registrationNumber": "101002749",
"type" : "privateCompany",
"registeredAddress" : {
"city": "San Francisco",
"country": "US",
"postalCode": "94107",
"stateOrProvince": "CA",
"street": "Brannan Street",
"street2": "Example Building"
}
}
}'The response returns the legalEntity resource for the organization, identified by its unique id. You will need this ID in the next step when you link the legal entity to the legal entity of its owner.
{
"organization": {
"legalName": "Example Company",
"registrationNumber": "101002749",
"registeredAddress": {
"city": "San Francisco",
"country": "US",
"postalCode": "94107",
"stateOrProvince": "CA",
"street": "Brannan Street",
"street2": "Example Building"
},
"taxExempt": false,
"type": "privateCompany"
},
"type": "organization",
"id": "LE00000000000000000000001"
}Step 4: Associate legal entities
The user that holds a contractual relationship with your platform is the main legal entity. You also need to create legal entities for other entities associated with this user. For example, if the main legal entity conducting business with your platform is an organization, then the legal entities of the owners of the organization must be linked to the legal entity of the organization.
To associate legal entities, update the main legal entity by making a PATCH /legalEntities/{id} request, specifying the entityAssociations array.
When updating the entityAssociations, note that a PATCH request replaces the whole array. If you only want to update one array item, make sure you include all existing items along with the specific change in your request.
The example below shows how you can associate an ultimate beneficial owner (UBO) to an organization.
Update the legal entity of the organization by making a PATCH /legalEntities/{id} request.
The array must include:
- legalEntityId: Unique identifier of the individual legal entity being associated.
- type: The relationship of the individual with the organization. Possible values: uboThroughControl, uboThroughOwnership, or signatory.
curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001 \ -u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \ -H "content-type: application/json" \ -X PATCH \ -d '{ "entityAssociations":[ { "jobTitle":"CEO", "legalEntityId":"LE00000000000000000000002", "type":"uboThroughControl" }, { "legalEntityId":"LE00000000000000000000003", "type":"uboThroughOwnership" }, { "jobTitle":"Country Manager", "legalEntityId":"LE00000000000000000000004", "type":"signatory" } ] }'If a person holds multiple roles in an organization, use their individual legal entity id to link them to each type or jobTitle.
curl https://kyc-test.adyen.com/lem/v3/legalEntities/LE00000000000000000000001 \ -u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \ -H "content-type: application/json" \ -X PATCH \ -d '{ "entityAssociations":[ { "jobTitle":"CEO", "legalEntityId":"LE00000000000000000000002", "type":"uboThroughControl" }, { "legalEntityId":"LE00000000000000000000002", "type":"uboThroughOwnership" }, { "jobTitle":"CEO", "legalEntityId":"LE00000000000000000000002", "type":"signatory" } ] }'
The response contains the updated legal entity.
Step 5: Create transfer instruments
Adyen must perform checks on the bank account where your user will receive their payouts. We refer to this bank account as a transfer instrument resource.
Collect the required information and provide this in a POST /transferInstruments request, specifying:
| Parameter | Required | Description |
|---|---|---|
| type | |
Set to bankAccount. |
| legalEntityId | |
Unique identifier of the legal entity that has the contractual relationship with your platform and owns the bank account. For sole proprietorships, this is the legal entity ID of the individual owner. |
| bankAccount | |
Object that contains required information about the legal entity's bank account. |
Here is an example request to add a transfer instrument for a bank account in the US:
curl https://kyc-test.adyen.com/lem/v3/transferInstruments \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
"legalEntityId":"LE00000000000000000000001",
"type":"bankAccount",
"bankAccount":{
"accountIdentification":{
"type":"usLocal",
"accountNumber":"0000000123",
"routingNumber":"121202211"
}
}
}'The response returns the transferInstrument resource, identified by its unique id.
If we are not able to verify the bank account details, you will need to provide additional documents.
Step 6 (Conditional): Upload additional documents
Do this step only when Adyen informs you that you need to provide additional documents.
Adyen attempts to verify the data 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.
To submit a document to Adyen:
- Collect the document from the account holder.
- Upload the document with a POST /documents request, specifying:
| Parameter | Required | Description |
|---|---|---|
| attachments | |
Array that contains the document. |
| owner | |
Object that contains information about the owner of the document. The value can be the unique identifier of the legal entity or 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 attachments.content must be unique. If you have already submitted the same combination, you'll receive an error message. Either update the existing document resource, or delete the resource and create a new one.
Here is an example of how to upload a registration document for an organization:
curl https://kyc-test.adyen.com/lem/v3/documents \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
"owner" : {
"id" : "LE00000000000000000000001",
"type" : "legalEntity"
},
"description" : "Registration doc for Example Company",
"type" : "registrationDocument",
"attachments" : [
{
"content": "AAQSkZJRgABAQEAYABgAAD/s.."
}
]
}'The response returns the document resource, identified by its unique id.
After you successfully upload the additional documents, wait for Adyen to inform you of the verification results.
Getting the verification results
An account holder's ability to perform different actions in your platform such as withdrawing cash from ATMs depends on the results of the verification. We call these actions capabilities.
Adyen returns the results of the verification and the available capabilities on the accountHolder resource. To receive verification updates, you need to create an account holder.