Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em inglês
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.

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:

To create a legal entity for an individual, provide all the required information in a POST /legalEntities request, specifying:
Parameter Required Description
type -white_check_mark- Set to individual.
individual -white_check_mark- Object that contains required information about the individual such as their name and identificationData.number.
Here is an example of how to create a legal entity for a signatory for an organization operating in the US:
Create an individual legal entity
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"
    }
}'
The response returns the legalEntity resource, identified by its unique id. You'll need the IDs to associate the individuals with the organization legal entity.
Response
{
  "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 -white_check_mark- Set to bankAccount.
legalEntityId -white_check_mark- Unique identifier of the legal entity that owns the bank account.
bankAccount -white_check_mark- 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:

Add bank account as a transfer instrument
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.

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

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

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/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.

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

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:

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.

Associate an individual to an organization
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.

Próximas etapas