Search

Are you looking for test card numbers?

Would you like to contact support?

Issuin icon

Onboard and verify account holders

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

Payment industry regulations require that a business (Adyen) verifies the identity of its clients. This means your account holders need to go through a Know Your Customer (KYC) verification process with Adyen before you can issue cards to them.

We perform the KYC checks against the legal entity of the account holder. We also need to verify individuals associated with the company or organization (such as shareholders and control officers). This means that the individuals must also be represented as legal entities within Adyen.

KYC process

You'll need to create an onboarding flow where you gather your account holder's information with your own pages and screens. You can then use the Balance Platform API to submit the required information and upload documents if needed.

To start the KYC process:

  1. Identify the country where the legal entity is operating in and collect the required information based on the country.
  2. Create legal entities and provide the required information.
  3. If necessary, Adyen informs you if you need to collect and upload additional documents.

Adyen uses the information you provide to verify the organization and the individuals. After Adyen confirms that the account holder passed the KYC checks, you can create a card for them.

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.

Confirm with your Adyen contact if you can use such a scenario, because we only allow this in specific circumstances.

Step 1: Identify country and collect required information

  1. Identify the country where your account holder is operating in. You need the country to know the required information that you will need to collect from them.
  2. Collect the required information from your account holder.

When you have collected the required information from your account holder, create legal entities for each of the following:

  • The organization.
  • Individuals who are the ultimate beneficial owners, control officers, and signatory for the organization.

Individuals must be linked to the organization legal entity. You can include the individual legal entities in the entityAssociations array when you create the organization legal entity, or update the organization legal entity resource at a later time.

Select a tab below:

To create a legal entity for an organization, make a POST /legalEntities request providing the required information based on the country.

Parameter Required Description
type -white_check_mark- organization
organization.legalName -white_check_mark- The organization's legally registered name.
organization.type -white_check_mark- The type of organization, for example business or listedPublicCompany. Refer to Organization types for a list of possible values.
organization.address -white_check_mark- Object that contains the organization's registered or principalPlaceOfBusiness address. Provide the principalPlaceOfBusiness (where the organization operates from), if different from the registered address.
organization.email -white_check_mark- The organization's email address.
organization.phone -white_check_mark- Object that contains the organization's phone contact details. The type can be mobile, landline, sip, or fax.
organization.doingBusinessAs The name the organization is locally known for.
organization.registrationNumber The organization's registration number, issued by the local Chamber of Commerce or equivalent.
organization.taxId The organization's tax number.
organization.description A description of what the organization does.
organization.webData Object that contains the organization's appAddress and webAddress.
entityAssociations Array where you link the legal entities of individuals associated with the organization. Include this array if you have already created the legal entities for the individuals, or you can also update the resource at a later time.

Here is an example of how you would create and provide the required information for an organization 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" : "business",
        "taxId": "101002749",
        "address" : {
            "street" : "Brannan Street",
            "street2" : "Example Building",
            "city" : "San Francisco",
            "postalCode" : "94107",
            "stateOrProvince" : "CA",
            "country" : "US",
            "type" : "principalPlaceOfBusiness"
        },
        "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": {
        "address": {
            "city": "San Francisco",
            "country": "US",
            "postalCode": "94107",
            "stateOrProvince": "CA",
            "street": "Brannan Street",
            "street2": "Example Building",
            "type": "principalPlaceOfBusiness"
        },
        "email": "info@example.com",
        "phone": {
            "countryCode": "US",
            "number": "4153671502",
            "type": "mobile"
        },
        "legalName": "Example Company",
        "taxId": "101002749",
        "type": "business"
    },
    "type": "organization",
    "id": "LE32272223222D5CKDZFL7DQC"
}

To create a legal entity for an individual, make a POST /legalEntities request, providing the required information based on the country.

Parameter Required Description
type -white_check_mark- individual
individual.name -white_check_mark- Object that contains the individual's firstName, lastName, and infix if applicable.
individual.address -white_check_mark- Object that contains the individual's residential address.
individual.phone -white_check_mark- Object that contains the individual's phone contact details. The type can be mobile, landline, sip, or fax.
individual.birthData.dateOfBirth -white_check_mark- In YYYY-MM-DD format.
individual.identificationData Object that contains information about the individual's identification number, including:
  • type: The type of identification number. For example, ssn.
  • number: The identification number. For example, the full 9 digits of the Social Security Number.
  • issuerCountry: Optional.The country where the ID was issued in, in a two-letter country code format.
  • issuerState: Optional.The state where the ID was issued in.
  • expiryDate : Optional.The expiry date in YYYY-MM-DD format.
individual.email The individual's email address.
individual.nationality The individual's nationality, in a two-letter country code format.

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":
    {
        "address": {
            "city": "San Francisco",
            "country": "US",
            "houseNumberOrName": "274",
            "postalCode": "1111",
            "street": "Brannan Street",
            "stateOrProvince": "CA",
            "type": "residential"
        },
        "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": {
        "address": {
            "city": "San Francisco",
            "country": "US",
            "postalCode": "1111",
            "stateOrProvince": "CA",
            "street": "Brannan Street",
            "street2": "274",
            "type": "residential"
        },
        "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"
}

After you successfully create and provide the information for the organization and individuals, wait for Adyen to inform you of the KYC check results. In some cases, Adyen may ask you to provide additional documents.

Step 3 (Conditional): Upload additional documents

Do this step only when Adyen informs you that you need to provide additional documents.

Adyen attempts to verify the organization and the individuals based on the information 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.

Adyen will inform you about the type of document that you need to provide. For more information possible types of document, refer to Additional documents.

  1. Collect the additional document from your account holder.

  2. Upload the document with a POST /documents request specifying:

    Parameter Required Description
    owner -white_check_mark- Object that contains information about the legal entity the document is being uploaded for.
    description -white_check_mark- Your description for the document.
    issuerCountry -white_check_mark- Country that issued the document, in a two-letter country code format (for example, US).
    type -white_check_mark- The type of document being uploaded. Refer to Document types for a list of possible values.
    attachment -white_check_mark- Object that contains the document, which includes:
    • contentType: The file format.
      Possible values: application/pdf, image/jpg, image/jpeg, or image/png.
    • filename: Name of the file with the file extension.
    • content: The document in a Base64 encoded format.
      number The number in the document.
      issuerState The state where the ID was issued.
      expiryDate The expiry date of the document in YYYY-MM-DD format.
      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" : "businessRegistration",
        "issuerCountry" : "US",
        "attachment" : {
            "contentType" : "application/pdf",
            "filename" : "busReg.pdf",
            "content": "AAQSkZJRgABAQEAYABgAAD/s.."
        }
    }'

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

      Response 
      {
    "issuerCountry": "US",
    "type": "businessRegistration",
    "attachment": {
        "content": "AAQSkZJRgABAQEAYABgAAD/s..",
        "contentType": "application/pdf",
        "filename": "busReg.pdf"
    },
    "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.

    Updating the legal entity resource

    In case an account holder wants to update their information or if you want to associate legal entities of individuals to an organization, update the existing legal entity resource with a PATCH /legalEntities/{id} request.

    Associate individuals to an organization

    Specify the individuals linked to an organization legal entity in the entityAssociations array. The array must contain the following:

    Parameter Description
    legalEntityId The legal entity ID of the individual.
    type Specifies how the individual is connected to the organization. Possible values are:
    • uboThroughOwnership: The individual directly or indirectly owns 25% or more of a company.
    • uboThroughControl: The individual is a member of the senior management staff responsible for managing the company.
    • signatory: The individual who signs up for the Adyen account and is authorized to sign on behalf of the organization.
    jobTitle Required for type signatory.
    sharePercentage In case of type uboThroughOwnership, the percentage of shares that the individual owns.

    If the organization legal entity already exists, update the resource with a PATCH /legalEntities/{id} request.

    You are replacing the entire array when you update entityAssociations. This means that if you want to update the type of a particular array entry, you need to include the rest of the entries in your PATCH 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",
            "sharePercentage": 49.9
          },
          {
            "jobTitle": "Country Manager",
            "legalEntityId": "LE32272223222D5CK99ZQ33D7",
            "type": "signatory"
          }
       ]
    }'

    The response contains the updated legal entity resource.

    Getting the KYC check results

    Your Adyen contact will inform you of the status and results of the KYC checks.

    After Adyen confirms that the account holder passed the KYC checks, you can create a card for your user.

    In a future version of the API, you will be informed of the KYC checks status through a notification webhook. You can also get the status when you make a GET /legalEntities/{id} request.

    Next steps

    required
    Link the resources

    Update the account holder resource to link the legal entity.
    required
    Create cards

    Create and issue cards for your users.