Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Issuin icon

Onboard and verify account holders

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

As required by payment industry regulations, account holders have to go through Know Your Customer (KYC) checks before you can issue cards to them. These checks are required to help prevent fraudulent activities in your platform.

To start the KYC 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 KYC checks. 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 their KYC verification checks. For details, refer to Required KYC 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 KYC process. 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 KYC process, 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.

To link the legal entities, you can first create legal entities for the individuals and then include the entityAssociations array when you create the organization's legal entity. Alternatively, you can update the organization's legalEntity resource if it already exists.

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

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

Here is an example of how you would create a legal entity for a private company operating in the US.

Create organization 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" : "organization",
    "organization" :
      {
        "legalName" : "Example Company",
        "type" : "privateCompany",
        "taxId": "101002749",
        "registeredAddress" : {
            "city": "San Francisco",
            "country": "US",
            "postalCode": "94107",
            "stateOrProvince": "CA",
            "street": "Brannan Street",
            "street2": "Example Building"
        },
        "phone" : {
            "type" : "mobile",
            "countryCode" : "US",
            "number" : "4153671502"
        },
        "email": "info@example.com"
      }
   }'

The response returns the legalEntity resource for the organization, identified by its unique id.

Response
{
    "organization": {
        "registeredAddress": {
            "city": "San Francisco",
            "country": "US",
            "postalCode": "94107",
            "stateOrProvince": "CA",
            "street": "Brannan Street",
            "street2": "Example Building"
        },
        "email": "info@example.com",
        "phone": {
            "countryCode": "US",
            "number": "4153671502",
            "type": "mobile"
        },
        "legalName": "Example Company",
        "taxId": "101002749",
        "type": "privateCompany"
    },
    "type": "organization",
    "id": "LE32272223222D5CKDZFL7DQC"
}

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 KYC check 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 KYC check 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:

  • legalEntityId: Unique identifier of the individual legal entity.
  • type: The relationship of the individual to the organization. For example, if they are a shareholder with more than 25% of shares, the value should be uboThroughOwnership.

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 KYC check 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 KYC checks. We call these actions capabilities.

Adyen returns the results of the KYC checks and the available capabilities on the accountHolder resource. To start receiving KYC updates, you need to create an account holder.

In the future, you will be informed of the KYC checks status through a notification webhook.

Próximos passos