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.
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: 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 2: 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:
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. |
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"
}
}
}'
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 3: 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.
- 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" } ] }'
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 4: 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 5 (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/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.