Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

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.

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 -white_check_mark- Set to organization.
organization -white_check_mark- 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.
Create organization legal entity
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"
       }
     }
   }'
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.
Response
{
    "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"
}

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

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 -white_check_mark- Set to bankAccount.
legalEntityId -white_check_mark- Unique identifier of the legal entity that has the contractual relationship with your platform and owns the bank account.
bankAccount -white_check_mark- 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:

Add bank account as a transfer instrument
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"
    }
 }'

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

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

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:

  1. Collect the document from the account holder.
  2. Upload the document with a POST /documents request, specifying:
Parameter Required Description
attachments -white_check_mark- Array that contains the document.
owner -white_check_mark- 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 -white_check_mark- 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:

Upload documents
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.."
        }
      ]
   }'

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

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

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