Marketplace icon

Onboarding v4

Learn about the changes in onboarding v4.

Limited availability
Onboarding v4 is currently in beta version. The processes and documentation are subject to change prior to general availability. If you are interested in piloting onboarding v4 or have any feedback, reach out to your Adyen contact.

This page provides an overview of the changes in onboarding v4. For more information about onboarding versioning, see here.

For an overview of the changes between Legal Entity Management API v2, v3, and v4, see our LEM API changelog.

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 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} request, it now returns a 404 response.

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. 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
Expand view
Copy link to code block
Copy code
Copy code
{
   "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 and API-only onboarding.

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. For example, zzzzz
  • Only symbols. For example, &&&&
  • Only numbers. For example, 123456
  • Only spaces
  • A fictitious name. For example, "John Doe"

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

  • A minimum of three characters across all fields.

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.

Onboarding underage users

Users between the ages of 13-18 in particular countries/regions can be onboarded with a legal representative. See here for more information.

Onboarding unincorporated partnerships

Beginning with onboarding v3, you can now onboard unincorporated partnerships in selected countries/regions. 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 for the accepted format per country.

Requirement for business lines and industry codes for issuing

To issue cards to your users, you must create business lines for them. To submit this information to Adyen, make a POST /businessLines request, specifying the service as issuing. In your request, specify the industry code.

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

Error Code Error Message Remediating action Code Remediating action
2_8181 industryCode was missing 2_176 Add industryCode to business line
2_8231 businessLine was missing. 2_136 Add business line

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 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.

Requirements for specific countries/regions

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

  • The format for registration numbers 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 number 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 request. If you are using hosted onboarding, users can add this information in the hosted onboarding page.

For organizations and legal arrangements, all associated entities that are resident in a different country/region must provide an identity document.

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

Organizations and sole proprietorships can now provide their tax ID instead of a VAT number. See here for accepted formats in different countries/regions.

For organizations and legal arrangements, all associated entities that are resident in a different country/region must provide an identity document.

Organizations in New Zealand do not have a registration number. When onboarding an organization, specify registrationNumberAbsent: true in your 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. 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} request using the id of the organization legal entity in the path. In the request, specify an 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

For organizations and legal arrangements, all associated entities that are resident in a different country/region must provide an identity document.

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 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.

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

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 for accepted formats.

For US account holders, if their legal entity is associated to any non-US entities, all non-US individuals must provide an identity document.

For organizations and legal arrangements, all associated entities that are resident in a different country/region must provide an identity document.

Singpass for identity verification

Users in Singapore may be required to verify their identity using Singpass, 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.

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.

Updates for hosted onboarding

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