---
title: "Onboarding v4"
description: "Learn about the changes in onboarding v4."
url: "https://docs.adyen.com/marketplaces/onboard-users/onboarding-versions/onboarding-v4"
source_url: "https://docs.adyen.com/marketplaces/onboard-users/onboarding-versions/onboarding-v4.md"
canonical: "https://docs.adyen.com/marketplaces/onboard-users/onboarding-versions/onboarding-v4"
last_modified: "2025-02-10T10:41:00+01:00"
language: "en"
---

# Onboarding v4

Learn about the changes in onboarding v4.

[View source](/marketplaces/onboard-users/onboarding-versions/onboarding-v4.md)

This page provides an overview of the changes in onboarding v4. For more information about onboarding versioning, see [here](/marketplaces/onboard-users/onboarding-versions#onboard-versions).

To see the difference between Legal Entity Management API versions, use the [API Diff Tool](https://docs.adyen.com/api-explorer/api-diff-tool).

* [Limitations on using PO box as address](#po-box)
* [Improvements for LEM API](#lem-improvements)
* [Improved validation for ID document uploads](#id-validation)
* [New validations on fields](#validations)
* [Onboarding underage users](#underage-users)
* [Onboarding unincorporated partnerships](#unincorporated-partnerships)
* [Providing registration number before first payment](#registration-number)
* [Requirement for doing business as name](#doing-business-as)
* [Requirement for principal place of business](#principal-place)
* [Requirements for specific countries/regions](#countries-regions)
* [Updates for hosted onboarding](#hosted-onboarding)

## Limitations on using a PO Box as an address

* An individual user cannot use a PO box as their residential address.

* An organization can use a PO box as their registered address. However, they must also provide an alternative address for their principal place of business. The address for the principal place of business cannot be a PO box.

You can [test your error handling flow](/marketplaces/test-verification-errors/) for the new verification error messages.

| Error Code | Error Message                             | Sub Error Code | Sub error Message                                 | Remediating action Code | Remediating action                                                                                                                       |
| ---------- | ----------------------------------------- | -------------- | ------------------------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 1\_50      | Organization details couldn't be verified | 1\_5093        | The business address details couldn’t be verified | 1\_524                  | Make sure the registered business address is correct, and that the principal place of business address is a physical, non-PO box address |
|            |                                           | 1\_5094        | The principal place of business was missing       | 1\_525                  | Add the physical address of the principal place of business                                                                              |
| 1\_30      | Individual details couldn't be verified   | 1\_3085        | The residential address is a P.O. Box             | 1\_321                  | Update the residential address                                                                                                           |

## Improvements for Legal Entity Management API

When you delete a document by making a DELETE [/documents/{id}](https://docs.adyen.com/api-explorer/legalentity/4/delete/documents/\(id\)) request, it now returns a [404 response](/errors/not-found/#00_404).

## Improved validation for ID document uploads

We added a validation error when a low-quality ID document, such as a passport or driver's license, is uploaded by making a POST [/documents](https://docs.adyen.com/api-explorer/legalentity/4/post/documents). This allows you to quickly see if an improved document needs to be uploaded to pass verification checks.

**API response when a low-quality ID document is uploaded**

```json
{
   "type":"https://docs.adyen.com/errors/validation",
   "title":"The request is missing required fields or contains invalid data.",
   "status":422,
   "detail":"Invalid legal entity information provided",
   "requestId":"NO_PSP_REF_1738250600995123",
   "invalidFields":[
      {
         "name":"document.attachment.attachment.content",
         "value":"Content quality could not be validated",
         "message":"There was a validation error on this request{\"detect_cutoff\":[\"cutoff document in image\"]}"
      }
   ],
   "errorCode":"30_102"
}
```

## New validations on fields

To meet compliance requirements, we have added validations to specific fields for legal entities and legal arrangements. These validations are applicable for both [hosted onboarding](/marketplaces/onboard-users#hosted-onboarding) and [API-only onboarding](/marketplaces/onboard-users#api-only-onboarding).

### Tab: Names

The `name` field refers to the following:

* `individual.name` object including:

  * `individual.name.firstName`
  * `individual.name.infix`
  * `individual.name.lastName`

* `organization.legalName`

* `soleProprietorship.name`

* `trust.name`

* `unincorporatedPartnership.name`

The name field for all entity types cannot contain:

* An emoji

* Only one repeated character, unless the name is two characters long. For example, *Aa* and *AaaaBa* are allowed, but *zzzzz* is not.

* Only symbols. For example, *&&&&*

* Only numbers. For example, *123456*

* Only spaces

* A fictitious name. For example, "John Doe". The name field cannot contain any of the following names:

  * "ABCD"
  * "ABCDE"
  * "ABCDEF"
  * "ABCDEFG"
  * "An other"
  * "Jane Doe"
  * "John Doe"
  * "My Customer"
  * "N/A"
  * "n/a"
  * "N/a"
  * "n/A"
  * "N\ /A"
  * "not app"
  * "not applicable"
  * "null"

The name field for individuals and other entity types must contain:

* A minimum of three characters across all of the fields. For example, an individual with `firstName` N and `lastName` Ha.

The name field for other entity types must contain:

* Only allowed special characters. These are `,`, `-`, `—`, `.`,`;`,`:`,`&`,`?`,`@`,`(`,`)`,`"`,`'`,`!`,`\`,`+`, and `/`. Accents and non-latin scripts are allowed.

The name field for individuals must contain:

* Only allowed special characters. These are `-`, `—`, `.`, and `/`. Accents and non-latin scripts are allowed.

### Tab: Addresses

The address field refers to all the following:

* `individual.residentialAddress`
* `organization.registeredAddress`
* `soleProprietorship.registeredAddress`
* `trust.registeredAddress`
* `unincorporatedPartnership.registeredAddress`

The address field for all entity types cannot contain:

* An emoji

* A repeated field for all parts of the address. For example, **Spain**, **Spain**, **Spain**.

* Only one repeated character, except for city names with two characters:

  * City names **can** contain only repeated characters if the city name is two characters long. For example, *Aa* is allowed, but *Aaaa* is not.
  * All other address fields cannot contain only repeated characters. For example, *zzzzz*.

* Only symbols. For example, *&&&&*

* Only numbers. For example, *123456*

* Only spaces

* A fictitious address. The address field cannot contain any of the following:

  * "ABCD"
  * "ABCDE"
  * "ABCDEF"
  * "ABCDEFG"
  * "An other"
  * "Jane Doe"
  * "John Doe"
  * "My Customer"
  * "N/A"
  * "n/a"
  * "N/a"
  * "n/A"
  * "N\ /A"
  * "not app"
  * "not applicable"
  * "null"

The address field must contain:

* A minimum of three characters for the street name.
* A minimum of three characters for the city name. (If the city name contains only repeated characters, for example, "Aa", the minimum length is two characters.)

## Onboarding underage users

Users between the ages of 13-18 in particular countries/regions can be onboarded with a legal representative. See [here](/platforms/verification-requirements/#minimum-age-requirements-for-users) for more information.

## Onboarding unincorporated partnerships

Beginning with onboarding v3, you can now onboard [unincorporated partnerships](/marketplaces/verification-requirements/?tab=unincorporated_partnership_4_5) in [selected countries/regions](/marketplaces/verification-requirements/?tab=unincorporated_partnership_4_5). Unincorporated partnerships can only be onboarded using the Legal Entity Management API.

## Providing registration number before processing payments

Organizations must provide their registration number prior to processing payments. See [here](/marketplaces/verification-requirements/data-formats-per-country/) for the accepted format per country.

## Requirements for doing business as name

Adyen must identify if the name that an organization or legal arrangement trades under is different from its registered name. This is referred to as the *Doing Business As* (DBA) name. Organizations and legal arrangements that do not have a DBA name can indicate this while onboarding.

If you are using hosted onboarding, users can select this in the hosted onboarding page. If you are using the LEM API, set the corresponding value to **true** in your POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/4/post/legalEntities) request:

* `organization.doingBusinessAsAbsent`
* `soleProprietorship.doingBusinessAsAbsent`
* `trust.doingBusinessAsAbsent`
* `unincorporatedPartnership.doingBusinessAsAbsent`

Make sure that your systems can handle all the related verification error messages.

| Error Code | Error Message                                   | Remediating action Code | Remediating action                                     |
| ---------- | ----------------------------------------------- | ----------------------- | ------------------------------------------------------ |
| 2\_8086    | `organization.doingBusinessAs` was missing      | 2\_133                  | Add `organization.doingBusinessAs` to legal entity     |
| 2\_8246    | `legalArrangement.doingBusinessAs` was missing. | 2\_233                  | Add `legalArrangement.doingBusinessAs` to legal entity |

## Requirements for principal place of business

If an organization has a principal place of business address, the country must be the same country as its registered address.

Make sure that your systems can handle all the related verification error messages.

| Error Code | Error Message                                                        | Remediating action Code | Remediating action                                                          |
| ---------- | -------------------------------------------------------------------- | ----------------------- | --------------------------------------------------------------------------- |
| 2\_8212    | `organization.principalPlaceOfBusiness.country` was missing          | 2\_195                  | Add `organization.principalPlaceOfBusiness.country` to legal entity         |
| 2\_8214    | `organization.principalPlaceOfBusiness.stateOrProvince` was missing. | 2\_197                  | Add `organization.principalPlaceOfBusiness.stateOrProvince` to legal entity |
| 2\_8216    | `organization.principalPlaceOfBusiness.street` was missing.          | 2\_199                  | Add `organization.principalPlaceOfBusiness.street` to legal entity          |
| 2\_8218    | `organization.principalPlaceOfBusiness.city` was missing.            | 2\_207                  | Add `organization.principalPlaceOfBusiness.city` to legal entity            |
| 2\_8219    | `organization.principalPlaceOfBusiness.postalCode` was missing.      | 2\_209                  | Add `organization.principalPlaceOfBusiness.postalCode` to legal entity      |
| 2\_8221    | `organization.principalPlaceOfBusiness.street2` was missing.         | 2\_211                  | Add `organization.principalPlaceOfBusiness.street2` to legal entity         |

## Requirements for specific countries/regions

The following compliance requirements are based on the country of the user and its associated entities.

**

### Australia

* The format for [registration numbers](/marketplaces/verification-requirements/data-formats-per-country#australia) for all organizations, sole proprietorships, and trusts is now only 9 digits. Example: 123456789

| Data for                           | Type                                              | Description                         | Format            | Example      | Onboarding version |
| ---------------------------------- | ------------------------------------------------- | ----------------------------------- | ----------------- | ------------ | ------------------ |
| Organizations/sole proprietorships | Registration number                               | ACN Number                          | 9 digits          | 123456789    | v4                 |
|                                    | Tax Information                                   | ABN Number                          | 11 digits         | 55123456789  |                    |
|                                    | Registration number for incorporated associations | Various formats per state/territory | 3-20 alphanumeric | 12345A678901 | v1/v2/v3/v4        |
| Trusts                             | Tax Information                                   | ABN Number                          | 11 digits         | 55123456789  |                    |
| Individuals                        | Identification number                             | Driver's license number             | 5-11 alphanumeric | 2093628291   | v3/v4              |
|                                    |                                                   | Driver's license card number        | 5-11 alphanumeric | FCC6811469   | v3/v4              |

* Registration numbers for partnerships (both incorporated and unincorporated) are optional.

* Tax numbers for trustees are optional.

* Certain types of organizations and legal arrangements may not have a registration number or tax ID. If you are using the LEM API, specify either `registrationNumberAbsent`: **true** or `taxAbsent`: **true** in your POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/4/post/legalEntities) request. If you are using hosted onboarding, users can add this information in the hosted onboarding page.

**

### Brazil

For organizations and legal arrangements, all associated entities that are resident in a different country/region must provide an [identity document](/platforms/verification-requirements/document-requirements/#photo-id-requirements).

**

### European Union

To offer business accounts to their users, organizations in the European Union must provide either of the following:

* Their annual turnover
* Their annual balance sheet

If you are using hosted onboarding, users can add this information in the hosted onboarding page. If you are using the LEM API, in your POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/4/post/legalEntities) request, specify `organization.financialReports.annualTurnover` or `organization.financialReports.balanceSheetTotal`.

Make sure that your systems can handle all the related verification error messages.

| Error Code | Error Message                   | Remediating action Code | Remediating action                           |
| ---------- | ------------------------------- | ----------------------- | -------------------------------------------- |
| 2\_8240    | Balance sheet total was missing | 2\_227                  | Provide balance sheet total for legal entity |
| 2\_8241    | Annual turnover was missing     | 2\_228                  | Provide annual turnover for legal entity     |

**

### Gibraltar

Organizations and sole proprietorships can now provide their tax ID instead of a VAT number. See [here](/marketplaces/verification-requirements/data-formats-per-country/) for accepted formats in different countries/regions.

**

### Hong Kong

For organizations and legal arrangements, all associated entities that are resident in a different country/region must provide an [identity document](/platforms/verification-requirements/document-requirements/#photo-id-requirements).

**

### New Zealand

Organizations in New Zealand do not have a registration number. When onboarding an organization, specify `registrationNumberAbsent`: **true** in your POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/4/post/legalEntities) request. If you are using hosted onboarding, users can add this information in the hosted onboarding page.

Sole proprietorships in New Zealand must provide their [IRD number](https://www.ird.govt.nz/managing-my-tax/ird-numbers). Registration numbers for sole proprietorships are optional.

#### Identification of nominees

Individuals that are associated to legal entities and legal arrangements as directors, UBOs through ownership, or secondary partners must also identify if they are nominees.

Make a [/legalEntities/{id}](https://docs.adyen.com/api-explorer/legalentity/latest/patch/legalEntities/\(id\)) request using the [id](https://docs.adyen.com/api-explorer/legalentity/4/patch/legalEntities/\(id\)#path-id) of the organization legal entity in the path. In the request, specify an [entityAssociations](https://docs.adyen.com/api-explorer/legalentity/4/patch/legalEntities/\(id\)#request-entityAssociations) array containing `entityAssociation.nominee` set to **true** or **false**.

#### Verification of natural persons

In New Zealand, Adyen must verify the following information for all natural persons. This requirement applies to both individual users and users associated to a legal entity or legal arrangement.

* First name
* Last name
* Date of birth
* Residential address

Make sure that your systems can handle all the related verification error messages.

| Error Code  | Error Message                                               | Remediating action Code | Remediating action                                                  |
| ----------- | ----------------------------------------------------------- | ----------------------- | ------------------------------------------------------------------- |
| 2\_8009     | `individual.firstName` was missing                          | 2\_102                  | Add `individual.name.firstName` to legal entity                     |
| 2\_8011     | `individual.lastName` was missing                           | 2\_103                  | Add `individual.name.lastName` to legal entity                      |
| 2\_8018     | `individual.residentialAddress.stateOrProvince` was missing | 2\_105                  | Add `individual.residentialAddress.stateOrProvince` to legal entity |
| []()2\_8019 | `individual.residentialAddress.street` was missing          | 2\_106                  | Add `individual.residentialAddress.street` to legal entity          |
| []()2\_8020 | `individual.residentialAddress.city` was missing            | 2\_107                  | Add `individual.residentialAddress.city` to legal entity            |
| []()2\_8021 | `individual.residentialAddress.postalCode` was missing      | 2\_108                  | Add `individual.residentialAddress.postalcode` to legal entity      |
| []()2\_8058 | `individual.name` was missing                               | 2\_120                  | Add `individual.name` to legal entity                               |

| Sub Error Code | Sub error Message                                                               | Remediating action Code | Remediating action        |
| -------------- | ------------------------------------------------------------------------------- | ----------------------- | ------------------------- |
| 1\_3083        | The name or residential address couldn't be verified                            | 1\_319                  | Update individual details |
|                |                                                                                 | 1\_320                  | Upload proof of residency |
| 1\_3084        | The name or residential address does not match the proof of residential address | 1\_319                  | Update individual details |
|                |                                                                                 | 1\_320                  | Upload proof of residency |

**

### Singapore

For organizations and legal arrangements, all associated entities that are resident in a different country/region must provide an [identity document](/platforms/verification-requirements/document-requirements/#photo-id-requirements).

#### Singpass for identity verification

Users in Singapore may be required to verify their identity using [Singpass](https://www.singpass.gov.sg/main/), the Singapore government’s digital identity platform. Users need to have a Singpass account before they can begin the process. To create an account, see [here](https://portal.singpass.gov.sg/home/ui/register/instructions).

In the hosted onboarding page, users are prompted to provide the following verified information through Singpass:

* Name (including any aliases)
* Date of birth
* NRIC or FIN number
* Registered or residential address
* Email address
* Phone number

Users can choose to enter this information separately, but they need to upload additional documentation, such as a scan of their identity document.

**

### United Kingdom

#### Country of governing law

The country of governing law is now required for both organizations and sole proprietorships. The country of governing law can be different from the country of the registered address for the legal entity/legal arrangement.

To provide this information using the LEM API, in your POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/4/post/legalEntities) request, include the two-letter country code in `organization.countryOfGoverningLaw` or `soleProprietorship.countryOfGoverningLaw`.

#### Identification of directors

Adyen must verify all directors of UK organizations. For more information about the requirements for supporting documents, see [here](/marketplaces/verification-requirements/document-requirements#director-proof).

If you are using hosted onboarding, users can add this information in the hosted onboarding page. To provide this information using the LEM API, include `type` **proofOfDirector** in your POST [/documents](https://docs.adyen.com/api-explorer/legalentity/4/post/documents) request.

#### Requirements for business accounts

To offer business accounts to their users, UK organizations must provide their number of employees, and either their annual turnover or annual balance sheet.

If you are using hosted onboarding, users can add this information in the hosted onboarding page. If you are using the LEM API, in your POST [/legalEntities](https://docs.adyen.com/api-explorer/legalentity/4/post/legalEntities) request, specify `organization.financialReports.employeeCount` and either `organization.financialReports.annualTurnover` or `organization.financialReports.balanceSheetTotal`.

Make sure that your systems can handle all the related verification error messages.

| Error Code | Error Message                   | Remediating action Code | Remediating action                           |
| ---------- | ------------------------------- | ----------------------- | -------------------------------------------- |
| 2\_8239    | Number of employees was missing | 2\_226                  | Provide number of employees for legal entity |
| 2\_8240    | Balance sheet total was missing | 2\_227                  | Provide balance sheet total for legal entity |
| 2\_8241    | Annual turnover was missing     | 2\_228                  | Provide annual turnover for legal entity     |

**

### Crown dependencies of the United Kingdom

This section is applicable to Guernsey, Jersey, and the Isle of Man.

Organizations and sole proprietorships can now provide their tax ID instead of a VAT number. See [here](/marketplaces/verification-requirements/data-formats-per-country/) for accepted formats.

**

### United States

For US account holders, if their legal entity is associated to any non-US entities, all non-US individuals must provide an [identity document](/platforms/verification-requirements/document-requirements#photo-id-requirements).

For organizations and legal arrangements, all associated entities that are resident in a different country/region must provide an [identity document](/platforms/verification-requirements/document-requirements#photo-id-requirements).

## Updates for hosted onboarding

Publicly listed companies can now provide their ticker symbol in the hosted onboarding page.

Make sure that your systems can handle all the related verification error messages.

| Error Code | Error Message                                      | Remediating action Code | Remediating action                                        |
| ---------- | -------------------------------------------------- | ----------------------- | --------------------------------------------------------- |
| 2\_8247    | `organization.stockData.tickerSymbol` was missing. | 2\_150                  | Add `organization.stockData.tickerSymbol` to legal entity |