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.

As required by payment industry regulations, account holders have to be verified before you can issue cards to them. These verification checks are required to help prevent fraudulent activities in your platform.

To start the checks, your account holders must provide information to Adyen. Using this information, Adyen verifies:

  • Their identity. When the account holder is an organization, Adyen also verifies the identity of individuals who are associated with the organization (such as shareholders and control officers).
  • Their bank account, when required for a use case. For example, to let an account holder transfer funds to their bank account, Adyen must verify that the bank account exists and that they own it.

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.

Step 1: Identify country and collect required information

To start the verification, you'll need to create an onboarding flow where you gather information using your own UI.

  1. Identify the country where the account holder is operating in.
  2. Determine the required information based on the country. This includes the information about their organization, individuals associated with their organization, and their bank account details if needed.
  3. Collect the required information.

Next, use the Balance Platform API to submit the required information and upload documents if needed.

When you have collected the required information from the account holder, 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: Here is how you would create a legal entity for a signatory for an organization operating in the US:
Create an individual legal entity
curl https://balanceplatform-api-test.adyen.com/bcl/v1/legalEntities \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-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

For use cases that involve moving funds between balance accounts and bank accounts, Adyen must perform checks on the bank account. To add the legal entity's bank account details, provide the required information in a POST /transferInstruments request, specifying:
  • 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:

Add bank account as a transfer instrument
curl https://balanceplatform-api-test.adyen.com/bcl/v1/transferInstruments \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-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 legal entity and their bank account based on 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:
    • 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 of 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 you would upload a registration document for an organization:

Upload documents
curl https://balanceplatform-api-test.adyen.com/bcl/v1/documents \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-H "content-type: application/json" \
-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

To link legal entities of individuals to an 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 show you would update an existing legalEntity resource with a PATCH /legalEntities/{id} request.

Associate an individual to an organization
curl https://balanceplatform-api-test.adyen.com/bcl/v1/legalEntities/LE32272223222D5CK99ZQ33D7 \
-u "ws@BalancePlatform.YOUR_BALANCE_PLATFORM":"YOUR_WS_PASSWORD" \
-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.

Next steps