Onboard and verify account holders

Collect information from your account holders and submit the information to Adyen.

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.
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 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):
- vatNumber
If the country where your user is operating in does not have a VAT system, collect their tax ID and send the following instead.
- taxInformation.number
- taxInformation.country

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:

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/v2/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"
       }
     }
   }'

https://docs.adyen.com/issuing/onboarding#create-legalEntity-organization-request

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"
}

https://docs.adyen.com/issuing/onboarding#create-legalEntity-organization-response

To create a legal entity for an individual, provide all the required information in a POST /legalEntities request, specifying:

Parameter	Required	Description
type		Set to individual.
individual		Object that contains required information about the individual such as their name and their residentialAddress.

The following is an example of how to create a legal entity for an individual in the US.

curl https://kyc-test.adyen.com/lem/v2/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": {
        "number": "+14153671502",
        "type": "mobile"
      },
      "name": {
        "firstName": "Simone",
        "lastName": "Hopper"
      },
      "birthData": {
        "dateOfBirth": "1981-12-01"
      },
      "email": "s.hopper@example.com"
    }
}'

https://docs.adyen.com/issuing/onboarding#create-legalEntity-individual-request

The response returns the legalEntity resource, identified by its unique id. You will need the IDs to associate the individuals with the organization legal entity.

{
    "individual": {
        "email": "s.hopper@example.com",
        "phone": {
            "number": "+14153671502",
            "type": "mobile"
        },
        "birthData": {
            "dateOfBirth": "1981-12-01"
        },
        "name": {
            "firstName": "Simone",
            "lastName": "Hopper"
        },
        "residentialAddress": {
            "city": "San Francisco",
            "country": "US",
            "postalCode": "94678",
            "stateOrProvince": "CA",
            "street": "Brannan Street",
            "street2": "274"
        }
    },
    "type": "individual",
    "id": "LE00000000000000000000002"
}

https://docs.adyen.com/issuing/onboarding#create-legalEntity-individual-response

To create a legal entity for a sole proprietorship, provide all the required information in a POST /legalEntities request, specifying:

Parameter	Required	Description
type		Set to soleProprietorship.
soleProprietorship		Object that contains required information about the business such as the name of the business and its registeredAddress.

The following is an example of how to create a sole proprietorship in the United Kingdom.

curl https://kyc-test.adyen.com/lem/v2/legalEntities \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
  "type": "soleProprietorship",
  "soleProprietorship": {
    "name": "Example Sole Trader",
    "countryOfGoverningLaw": "GB",
    "registeredAddress" : {
      "city": "London",
      "country": "GB",
      "postalCode": "W1T 3HE",
      "street": "12-13 Wells Mews"
    }
  }
}'

https://docs.adyen.com/issuing/onboarding#create-legalEntity-soleprop-request

The response returns the legalEntity resource, identified by its unique id. You need this ID in the next step when you link it to the legal entity of the owner.

{
  "type": "soleProprietorship",
  "soleProprietorship": {
    "name": "Example Sole Trader",
    "countryOfGoverningLaw": "GB",
    "registeredAddress" : {
      "city": "London",
      "country": "GB",
      "postalCode": "W1T 3HE",
      "street": "12-13 Wells Mews"
    }
  },
  "id": "LE00000000000000000000003"
}

https://docs.adyen.com/issuing/onboarding#create-legalEntity-soleprop-response

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.

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.
Associate UBOs to an organization
curl https://kyc-test.adyen.com/lem/v2/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" } ] }'
https://docs.adyen.com/managed-model/collect-verification-data/custom-onboarding#associate-ubos-to-an-organization

The response contains the updated legalEntity resource.

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/v2/transferInstruments \
-u "ws123456@Scope.BalancePlatform_YourBalancePlatform":"YourWsPassword" \
-H "content-type: application/json" \
-X POST \
-d '{
    "legalEntityId" : "LE00000000000000000000001",
    "type" : "bankAccount",
    "bankAccount" : {
      "countryCode" : "US",
      "currencyCode" : "USD",
      "accountNumber": "1234567890",
      "branchCode": "121202211",
      "accountType": "checking"
    }
 }'

https://docs.adyen.com/managed-model/collect-verification-data/custom-onboarding#create-transferInstrument-request

The response returns the transferInstrument resource, identified by its unique id.

{
  "bankAccount": {
    "accountNumber": "1234567890",
    "accountType": "checking",
    "branchCode": "121202211",
    "countryCode": "US",
    "currencyCode": "USD"
  },
  "legalEntityId": "LE00000000000000000000001",
  "type": "bankAccount",
  "id": "SE00000000000000000000001"
}

https://docs.adyen.com/managed-model/collect-verification-data/custom-onboarding#create-legalEntity-organization-response

If we are not able to verify the bank account details, you will need to provide additional documents.

Step 5 (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/v2/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.."
        }
      ]
   }'

https://docs.adyen.com/issuing/onboarding#upload-documents-request

The response returns the document resource, identified by its unique id.

{
  "type": "registrationDocument",
  "attachments": [
    {
      "content": "AAQSkZJRgABAQEAYABgAAD/s.."
    }
  ],
  "description": "Registration doc for Example Company",
  "owner": {
    "id": "LE00000000000000000000001",
    "type": "legalEntity"
  },
  "id": "SE00000000000000000000001"
}

https://docs.adyen.com/issuing/onboarding#upload-documents-response

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.

Next steps

required

Create an account holder

Create an account holder linked to the legal entity.