No momento, esta página não está disponível em português
Adyen-for-platform 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.

To see the difference between Legal Entity Management API versions, use the API Diff Tool.

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

Changes in v4 for financial products

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.

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.

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.

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.

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.

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

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.

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.

Support email and phone numbers

If you are a platform model, your users must provide both a support phone number and email address.

  • If your user is a sole proprietorship, they need to provide this information in the individual legal entity of the owner of the sole proprietorship.

  • If your user is a trust, they need to provide this information in the individual or organization legal entity of the main trustee.

  • If your user is an unincorporated partnership, they need to provide this information in the individual legal entity of the main partner.

  • If you are using hosted onboarding, users can add this information in the hosted onboarding page.

To use the Legal Entity Management API, in your POST /legalEntities request, specify the required fields:

  • individual.support.phone
    • individual.support.phone.number
    • individual.support.phone.type
  • individual.support.email

or

  • organization.support.phone
    • organization.support.phone.number
    • organization.support.phone.type
  • organization.support.email

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.support.email was missing. 2_234 Add organization.support.email to legal entity
2_8248 individual.support.email was missing was missing. 2_235 Add individual.support.email to legal entity
2_8249 organization.support.phone.number was missing. 2_236 Add organization.support.phone.number to legal entity
2_8250 individual.support.phone.number was missing. 2_237 Add individual.support.phone.number to legal entity

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

Requirement for business lines and industry codes for issuing

Only applicable for card 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

Source of funds for business accounts and issuing

Only applicable for business accounts and card issuing.

Adyen is required to verify the source of funds (SOF) used to fund an account. This requirement is applicable for both card issuing and business accounts.

Depending on the type of funds, we may request additional documents as proof. We strongly recommend that you have these documents available before starting in order to speed up this process.

To submit this information to Adyen, make a POST /businessLines request, specifying the service as either:

  • banking for business accounts
  • issuing for card issuing

If the source of funds was processed through Adyen, set the sourceOfFunds.adyenProcessedFunds to true. If the source of funds was not processed through Adyen, set the sourceOfFunds.adyenProcessedFunds to false. You must then include the sourceOfFunds.type and sourceOfFunds.description. The description must state the origin of the source of funds.

The following table shows the accepted funding sources and the required documents for each type, if requested. If the type of accepted document has a listed date requirement, the document must meet this requirement.

Type of Source of Funds businessLines.sourceOfFunds.type API value Documents must show Examples of accepted documents
Business earnings processed through Adyen Set businessLines.adyenProcessedFunds to true N/A No supporting document is required
Previous business earnings business
  • Name of company
  • Amounts earned
  • Description of business activity
  • Latest accounts (issued within the last financial year)
  • Annual Statements (within 12 months)
  • Latest tax filing (issued within the last year)
  • Letter from accountant (signed and dated within 12 months)
  • Recent Invoices (last 3 months)
(Previous) employment employment
  • Your business name
  • Date document was issued
  • Bank logo/name (for bank statement)
  • Employer’s name (for payslips)
  • Last 3 months of bank statements
  • Last 3 months of payslips
Cryptocurrency cryptocurrencyIncome
  • Your business name
  • Date document was issued (no older than 12 months)
  • Name of Crypto-exchange
  • Name of coin
  • Proof of ownership of wallet
  • Statement of transaction history (showing crypto)
  • Latest tax report (showing crypto) (no older than 12 months)
Investments (dividends) dividendIncome
  • Your business name
  • The date your business received the money
  • The amount received
  • The type of investments
  • Names of the parties involved
  • Contract specifying dividends
  • Latest tax returns of the company (no older than 12 months)
  • Investment certificate
  • Broker statement (issued within 3 months)
Loans loans
  • Your business name
  • Amount you borrowed
  • The date you received the money
  • Name of the lender
  • Address of the lender
  • Purpose of the loan
  • Loan agreement
  • Loan statement (no older than 12 months)
Subsidies / Grants financialAid
  • Amount of Subsidy / Grant
  • Providers(s) of Subsidy / Grant
  • Time Period
  • Confirmation of Subsidy / Grant
  • Subsidy Receipt
Third Party Funding (capital investments) thirdPartyFunding
  • Your business name
  • The date your business received the money
  • The amount received
  • Names of the parties involved
  • Addresses of the parties involved
  • Signatures of the parties involved
  • Payment purpose
  • Investor contracts
  • Investor memoranda
  • Notarized statements (no older than 12 months)
  • Partnership agreement
Property Sale assetSale
  • Date money was received
  • Amount you received
  • Address (if applicable)
  • Description of property
  • Proof of ownership (notarized)
  • Signed letter from the solicitor / estate agent (no older than 12 months)
  • Copy of contract of sale
  • Tax declaration (no older than 12 months)
  • Title deed (notarized)
Rental Income rentalIncome
  • Amount received
  • Address
  • Name of parties to the agreement
  • Rental Agreement
  • Proof of Ownership
Donations / Gifts donations
  • Amount received
  • Date of transfer
  • Full name of donor
  • Original or certified copy of grant
Royalty Income royaltyIncome
  • Description of (intellectual) property
  • Amount received
  • Royalty agreement
  • Tax declaration (no older than 12 months)
Gambling / Lottery gamblingWinnings
  • Amount won
  • Date of winning
  • Location / Site
  • Proof of Winnings
  • Win Report
  • Win/Loss Statement (issued within 3 months)
  • Tax declaration that shows winnings (issued within 12 months)
Inheritance inheritance
  • Name of person who made the will
  • Amount received / Value of estate
  • Date received
  • Name of benefactor
  • Certificate of inheritance
  • A grant of probate
  • Letter from solicitor / notary (no older than 12 months)
  • Signed copy of the will
Pension pensionIncome
  • Amount to be received
  • Legal Name of recipient
  • Pension slip (no older than 12 months)
  • Letter from previous employer
  • Pension statement form (no older than 12 months)
Insurance / Settlement insuranceSettlement
  • Amount of settlement
  • Legal name of recipient
  • Date received
  • Court order
  • Letter from lawyer / solicitor
  • Letter from insurer

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

Error Code Error Message Remediating action Code Remediating action
2_8163 sourceOfFunds was missing 2_159 Add source of funds to business line
2_8164 businessLine.sourceOfFunds.type was missing 2_160 Add businessLine.sourceOfFunds.type to business line
2_8165 businessLine.sourceOfFunds.dateOfFundsReceived was missing 2_161 Add businessLine.sourceOfFunds.dateOfFundsReceived to business line
2_8166 businessLine.sourceOfFunds.dateOfSourceEvent was missing 2_162 Add businessLine.sourceOfFunds.dateOfSourceEvent to business line
2_8167 businessLine.sourceOfFunds.purpose was missing 2_163 Add businessLine.sourceOfFunds.purpose to business line
2_8168 businessLine.sourceOfFunds.adyenProcessedFunds was missing 2_164 Add businessLine.sourceOfFunds.adyenProcessedFunds to business line
2_8169 businessLine.sourceOfFunds.cryptocurrencyExchange was missing 2_165 Add businessLine.sourceOfFunds.cryptocurrencyExchange to business line
2_8170 businessLine.sourceOfFunds.description was missing 2_166 Add businessLine.sourceOfFunds.description to business line
2_8171 businessLine.sourceOfFunds.relationship was missing 2_167 Add businessLine.sourceOfFunds.relationship to business line
2_8173 businessLine.sourceOfFunds.amount was missing 2_169 Add businessLine.sourceOfFunds.amount to business line
2_8242 businessLine.sourceOfFunds.annualTurnover was missing. 2_229 Add businessLine.sourceOfFunds.annualTurnover to business line
2_8243 businessLine.sourceOfFunds.originatorLegalEntityId was missing. 2_230 Add businessLine.sourceOfFunds.originatorLegalEntityId to business line
2_8244 businessLine.sourceOfFunds.financiers was missing. 2_231 Add businessLine.sourceOfFunds.financiers to business line
2_8245 businessLine.sourceOfFunds.website was missing. 2_232 Add businessLine.sourceOfFunds.website to business line