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 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.
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.
- 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.
Before you begin
Make sure that you have API credentials for the Legal Entity API.
Step 1: 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.
Step 2: Create legal entities
When you have collected the required information from your user, create a legalEntity resource 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.
Select a tab below to create legal entities:
| Parameter | Required | Description |
|---|---|---|
| type |  |
Set to individual. |
| individual | |
Object that contains required information about the individual such as their name and identificationData.number. |
curl https://kyc-test.adyen.com/lem/v1/legalEntities \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-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"
}
}'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"
}Step 3: Create transfer instruments
Adyen must perform checks on the bank account on which your user will receive their payouts. Collect 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 owns the bank account. |
| bankAccount | |
Object that contains required information about the legal entity's bank account. |
For example, here's a request for adding a transfer instrument for a bank account in the US:
curl https://kyc-test.adyen.com/lem/v1/transferInstruments \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-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 verification results. In some cases, Adyen may ask you to provide additional documents.
Step 4 (Conditional): Upload 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. |
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/v1/documents \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
"owner" : {
"id" : "LE32272223222D5CGBR254SKT",
"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.
Associate individuals with an organization
When linking legal entities, the associations must be defined on the legal entity that is conducting business and holds a contractual relationship with Adyen. In the case of organizations, the organization is conducting business with Adyen. This means that the legal entities of individuals that own the business must be linked to the legal entity of the organization.
To link individuals to the organization, include the entityAssociations array when creating or updating a 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. To know the types that you need to provide, see Identifying ultimate beneficial owners (UBOs) and signatories.
Depending on the type, you might also need to include information such as jobTitle.
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 to update an existing legalEntity resource with a PATCH /legalEntities/{id} request.
curl https://kyc-test.adyen.com/lem/v1/legalEntities/LE32272223222D5CK99ZQ33D7 \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-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 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.