Marketpay icon

Legal Entity Management v3

Learn about the improvements and new features in Legal Entity Management API v3.

We recommend that you use the latest version of the Legal Entity Management API to benefit from improvements and new features. This page summarizes the most important changes between v1/v2 and v3 of the Legal Entity Management API.

For more detailed information about these changes, please see our release notes.

Improved information and validations for transfer instrument creation

When creating a transfer instrument in v1 and v2, the bankAccount object does not specify the required information required for accounts based on the country and currency combination.

We added the type field. This field specifies, for example, the bank account is a local account in the United States, and the required information based on that type.

For a US bank account, set the type to usLocal. When the type is usLocal, the fields accountNumber and routingNumber are required. For UK bank accounts, the type is ukLocal and the required fields are accountNumber and sortCode.

In LEM v3, the currencyCode has been removed from the bank account object since it is not needed to create a transfer instrument. If you need to block the creation of cross-border transfer instruments, you can use the countryCode of the transfer instrument and the country of the associated legal entity.

We have also improved the validations and made error messages more specific to reduce the amount of failed payouts.

Support for multiple transfer instruments

The capability sendToTransferInstrument is now validated at both the transfer instrument resource and associated legal entity level. Previously, this capability was only validated at the legal entity level, which prevented payouts for users with multiple bank accounts that were not all verified. The verificationStatus of the capability and any verfificationErrors are returned:

Aligning business lines with Adyen products and services

We replaced the capability field with the service field. The capability field is now deprecated. The possible values for service are:

-paymentProcessing: corresponds to capability receivePayments.
-banking corresponds to capability issueBankAccount.

Note that you still must request capabilities for your account holders.

Error responses for legal entities

In the /legalEntities responses for POST, PATCH, and GET, we separated the status of capabilities from the problems that you need to resolve. We also grouped together the problems per type of capability.

We also added a new endpoint /legalEntities/{id}/checkVerificationErrors returns only the verificationErrors for a legal entity in the response without any additional details.

Terms of Service and PCI requirements

Adyen now determines if your users need to accept the Terms of Service and sign self-assessment questionnaires to comply with Payment Card Industry Data Security Standards (PCI DSS).

If you are using hosted onboarding, these steps are included in the user's hosted onboarding page. For custom onboarding, listen to webhooks and follow the steps to have your user accept the Terms of Service or sign self-assessment questionnaires.

Verification deadlines and data review

When a user updated their data in v1/v2, their capabilities were disallowed until verification checks were completed. We now provide a verification deadline. They are allowed to continue using the capabilities while the deadline is active.

We now inform you when your user needs to review their data by sending a verification error "Review of data is required" in a webhook. There is a verification deadline to review their data and they are allowed to continue using their capabilities while the deadline is active. To resolve the error, make a POST /legalEntities/{id}/confirmDataReview request to confirm the user has reviewed their data.

Compliance requirements for v3

Description Details
Data review Adyen may occasionally require your users to review and confirm that their data is up-to-date.
Required information and verification checks The following requirements are enforced during the verification process.
  • Authorized signatory mandatory for companies.
  • Email address and phone number mandatory for individuals.
  • Job title mandatory for authorized signatories and UBOs through control.
  • The legal structure of the company is mandatory.
  • The complete address of the legal entity is mandatory.
  • VAT number required in countries with VAT system.
  • Industry code and web data information mandatory for platform setups.
  • The platform setup and financial products are not offered to individual legal entities.
  • Industry codes are mandatory for business accounts.
Requirements in APAC countries
  • Tax ID is mandatory for business accounts and countries without a VAT system.
  • The date of incorporation is mandatory for organizations in Singapore and Hong Kong.
  • Nationality is required for natural persons in Singapore and Hong Kong.
  • Director is a mandatory type for organizations in Hong Kong, Singapore, Australia, New Zealand, Brazil, and the US when associating legal entities.
  • ID number is mandatory for natural persons in Singapore, Hong Kong, United States, and Brazil.
  • The required number of members must be provided for trusts and partnerships.
Terms of Service and PCI If you are using custom onboarding, confirm that your user has accepted the Terms of Service or signed self-assessment questionnaires.
Business lines Payment facilitators need to create business lines when onboarding users.

Next steps