Adyen-for-platform icon

Manage legal entities

View and manage your users' legal entity resources.

A legal entity is an API resource that describes an individual or an organization on your Balance Platform. It contains information about your user, for example, the legal name, address, and tax information of the individual or organization. Adyen uses this information to perform verification checks as required by payment industry regulations.

The legal entity resource also contains the associations that the legal entity has with other entities on your platform. For example, most organizations need a signatory.

To manage legal entities, use the Legal Entity Management API.

This page contains instructions for common legal entity operations. These operations are part of a larger process which includes verification and onboarding steps.

Creating a legal entity is the first step in moving users though the onboarding and verification process. Adyen uses the details you include when you create the legal entity to verify the account holder that is linked to the legal entity.

The minimum required information for creating a legal entity depends on the location and entity type that you are onboarding. For a full list of details per region, check Required information.

To create a legal entity:

  1. Make a POST /legalEntities request using the individual or organization details. The following example shows how to create an organization in the United States.

  2. The response contains a generated legal entity id. Save this response because you need the ID to:

    Create legal entity response
    Expand view
    Copy link to code block
    Copy code
    Copy code
    {
    "organization": {
    "legalName": "Explorer Company based in US",
    "registeredAddress": {
    "city": "New York",
    "country": "US",
    "postalCode": "10003",
    "stateOrProvince": "NY",
    "street": "71 5th Avenue",
    "street2": "11th floor"
    },
    "registrationNumber": "101002749",
    "type": "privateCompany"
    },
    "type": "organization",
    // Generated legal entity ID
    "id": "LE00000000000000000000001"
    }

After creating a legal entity, you can view the resource at any time using the Customer Area, the Legal Entity Management API, or hosted onboarding.

To view the legal entity details of an account holder in your Customer Area, you can search for the account holder associated to the legal entity. As an alternative:

  1. In the navigation menu, select the merchant account linked to your balance platform.

  2. Select Accounts & balances > Account holders.
  3. In the account holder table, select an Account holder ID.

  4. In the Account holder details page, select Overview > legal entity.

The legal entity details of the main legal entity are shown. You can view bank account information for the main legal entity under Transfer instruments.

If the legal entity is an organization, the page also shows details about the associated legal entities under Entity associations.

If the legal entity is an individual or a sole proprietorship, their personally identifiable information (PII) is redacted. Personally identifiable information includes their:

  • Name
  • Address (except for the country/region)
  • Date of birth
  • Email address
  • Phone number
  • IBAN or bank account number

To view this information in its unredacted state, you must have the View account holders PII data user role.

When the details of your account holders change, you need to update the legal entity. For example, a business can change address or ownership. You can update a legal entity using the Customer Area, API, or Hosted onboarding.

Before you begin, make sure you have the following role:

  • Manage account holders and legal entities

To update the legal entity details of an account holder in your Customer Area:

  1. In the navigation menu, select the merchant account linked to your balance platform.

  2. Select Platforms > Accounts & balances > Account holders.
  3. In the account holder table, select an Account holder ID.

  4. Under Quick actions, select Go to Onboarding.
    This opens a new browser tab for Hosted onboarding.
  5. Edit the details and select Submit.

Verification checks will be run again when legal entity details are updated.

Users sometimes sign up with an incorrect legal entity type. To change the legal entity type to the correct one, you can:

  • API-only onboarding: make a PATCH /legalEntities/{id} request to update the legal entity type and then provide additional required information.
  • Hosted onboarding: let your user change their legal entity type and provide additional required information in the UI.

All verification checks are run again after the legal entity type is changed.

You can only change the type of the main legal entity. If the type of an associated legal entity is incorrect, you need to create a new legal entity.

Retained information

When you change the legal entity type, the following information is retained:

  • The legal entity id
  • Transfer instruments
  • Bank statement details
  • Proof of industry
  • Processed amounts
  • Business lines

When changing between an individual and an organization legal entity, the following information is migrated:

  • The country is migrated from the individual residentialAddress to the organization registeredAddress.
  • The individual name is migrated to the organization legalName.

When changing between an organization and an individual legal entity, the following information is migrated:

  • The country is migrated from the organization registeredAddress to the individual residentialAddress.
  • The organization legalName is migrated to the individual name.

Your user can change their legal entity type by selecting a different one in the entity selection page.

For example, to change the type from a company to a sole proprietorship

  1. Select the edit icon next to Your business setup.

  1. Select Sole proprietorship in the entity selection screen. Note that local names for the entity types are shown based on the location of the user.

See also