---
title: "Onboarding versions"
description: "Learn how you can keep your integration up-to-date with the latest onboarding version."
url: "https://docs.adyen.com/marketplaces/onboard-users/onboarding-versions"
source_url: "https://docs.adyen.com/marketplaces/onboard-users/onboarding-versions.md"
canonical: "https://docs.adyen.com/marketplaces/onboard-users/onboarding-versions"
last_modified: "2025-02-10T10:35:00+01:00"
language: "en"
---

# Onboarding versions

Learn how you can keep your integration up-to-date with the latest onboarding version.

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

This page explains onboarding versioning and what you need to do in order to [update to the latest onboarding version](#update-version). We recommend that you update to the latest version as soon as possible to take advantage of new features and meet compliance requirements. The latest stable onboarding version is v4. For more information about onboarding v4, see the [v4 overview page](/marketplaces/onboard-users/onboarding-versions/onboarding-v4).

## Onboarding versioning

An onboarding version includes any breaking changes related to:

* Legal Entity Management API
* [Hosted onboarding](/marketplaces/onboard-users#hosted-onboarding)
* Know your customer (KYC) verification checks

If a breaking change needs to be made in any of these three areas, we introduce this as part of a new onboarding version. However, an onboarding version does not necessarily include changes in all three areas.

You do not need to immediately update to the latest onboarding version. We will notify you approximately 6-12 months before we sunset a version. To use any new features and meet compliance requirements, we recommend that you update to the latest version as soon as possible.

### Legal Entity Management API

We regularly update the Legal Entity Management API with [non-breaking changes](/development-resources/versioning#non-breaking-changes), so you can receive updates without needing to re-integrate with Adyen. These changes do not break existing integrations.

The following are considered non-breaking changes:

* An existing data point becomes needed in order to meet the minimum requirements for allowing a certain capability, such as paying out to your user. For example, a sole proprietorship in a new supported country or for an additional requested capability.
* Adding or updating [verification errors](/marketplaces/kyc-verification-codes) since they are string values.
* Adding new features or making enhancements to the performance of Adyen's APIs.

When a breaking change is necessary, we release this change as part of a new version of the LEM API. If there are critical security or compliance changes required, we first release this version in test environments four weeks before it is available in live environments. Adyen notifies you about these changes in your [Customer Area](https://ca-test.adyen.com/).

Any API changes are always backward compatible, but not forwards compatible. Changes to the LEM API are described in our [release notes](/release-notes/platforms-and-financial-products).

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

**

#### Release schedule

We aim to release new stable versions of the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview) and [Hosted onboarding](#hosted-onboarding) regularly. We recommend you [upgrade](/development-resources/versioning#upgrade-api) to the latest API version as soon as possible. Although older versions can still be used, they do not receive any additional updates.

Before we release a new stable version of the LEM API, we offer a preview API-only release candidate version. The release candidate version is subject to change based on feedback received from pilot merchants.

The release candidate API version provides early access to new features and improvements planned for the latest stable version. To get access to a release candidate version, contact your Adyen account manager.

**

#### Sunsetting LEM API versions and updating to new versions

As part of our API lifecycle management, we may need to sunset older versions of the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview). After the specified sunset date, you can no longer use that version of the API.

If you use API-only onboarding, you need to update to the latest API version before the sunset date of the version that you are using.

If you only use hosted onboarding, you still need to update to the latest API version before the sunset date. This is so that your hosted onboarding page remains up-to-date. See [here](#update-v3) for more information about how to update to onboarding v3, the latest stable onboarding version.

## Update your onboarding version

To update your onboarding version to the latest version:

1. Reach out to your Adyen contact to discuss your update and timelines.
2. Update your server integration to v4 of the [Legal Entity Management API](https://docs.adyen.com/api-explorer/legalentity/latest/overview).
3. Review and implement any new features.
4. [Test your integration](#test-onboarding).
5. Go live with the new onboarding version.

### Update from v2 to v4

The following table explains some key differences between onboarding v2 and v4 for specific features. For more information, see the dedicated [v4 overview page](/marketplaces/onboard-users/onboarding-versions/onboarding-v4) and the [API Diff Tool](https://docs.adyen.com/api-explorer/api-diff-tool).

| Features                                                                                                              | User onboarded in older version                                                                                                                             | New user onboarded in latest version           |   |
| --------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | - |
| [Verification deadlines](/marketplaces/verification-overview?tab=adyen_requires_data_review_4#verification-deadlines) | Available after the onboarding version is updated. Capabilities that were invalid in the older version do not automatically receive verification deadlines. | Available                                      |   |
| [Acceptance of Adyen's Terms of Service](/marketplaces/onboard-users/terms-of-service/)                               | Acceptance by the user is backfilled. If new capabilities are requested, the user must sign additional ToS documents.                                       | Automatically required when user is onboarded. |   |

Depending on your [type of onboarding](/marketplaces/onboard-users), you need to perform the following actions. Note that after updating your onboarding version, verification checks are not immediately triggered for your users. New verification checks are only triggered when the user [updates their data](/marketplaces/verification-overview/#when-users-change-their-data) or has a [required data review](/marketplaces/verification-overview/#when-adyen-requires-data-reviews).

### Tab: Hosted onboarding

Hosted onboarding is built on top of our Legal Entity Management (LEM) API. Therefore, if you are using hosted onboarding, it continues to use LEM v2 until you update your integration. After the update, it automatically uses LEM v4.

To support onboarding v4, you need to implement the following backend changes to your systems:

* Implement logic to notify your users when they have a [required data review](/marketplaces/verification-overview/#when-adyen-requires-data-reviews). The user can confirm or update their information in the hosted onboarding page.

* Implement logic to interpret and enforce [verification deadlines](/marketplaces/verification-overview/#verification-deadlines).

* Review the [new compliance requirements](/marketplaces/onboard-users/onboarding-versions/onboarding-v4#countries-regions) for specific countries/regions.

* Review the new structure for verification errors. In earlier onboarding versions, each capability requested for the legal entity had any verification errors shown within the capability array. Verification errors are now shown with all affected capabilities as an array underneath. You can also use the new [/checkVerificationErrors](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/checkVerificationErrors) endpoint to see only the verification errors for a legal entity.

* Review the new webhook structure for verification statuses. The capability **sendToTransferInstrument** is now validated at both the transfer instrument resource and associated legal entity level. This means that transfers are possible to a verified transfer instrument independently of the verification status of other transfer instruments that the legal entity has.

* Review the [required data points](/marketplaces/onboard-users/onboarding-steps).

* Review the [new validations for name and address fields](/marketplaces/onboard-users/onboarding-versions/onboarding-v4/#validations).

* Align with the new API structure when creating business lines. The [capability](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-capability) field has been replaced by the [service](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-service) field. The [capability](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-capability) field is now deprecated. The possible values for [service](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-service) are:

  * **paymentProcessing**: corresponds to capability **receivePayments**
  * **banking** corresponds to capability **issueBankAccount**
  * **issuing** corresponds to capability **issueCard**

* When creating business lines, you must provide the [source of funds](/marketplaces/onboard-users/onboarding-versions/onboarding-v4/#source-funds) for both card issuing and business accounts.

### Tab: API-only onboarding

To support onboarding v4, you need to implement the following backend changes to your systems.

* Implement logic to notify your users when they have a [required data review](/marketplaces/verification-overview/#when-adyen-requires-data-reviews).

* Implement logic to interpret and enforce [verification deadlines](/marketplaces/verification-overview/#verification-deadlines).

* Review the [new compliance requirements](/marketplaces/onboard-users/onboarding-versions/onboarding-v4#countries-regions) for specific countries/regions.

* Review the new structure for verification errors. In earlier onboarding versions, each capability requested for the legal entity had any verification errors shown within the capability array. Verification errors are now shown with all affected capabilities as an array underneath. You can also use the new [/checkVerificationErrors](https://docs.adyen.com/api-explorer/legalentity/latest/post/legalEntities/\(id\)/checkVerificationErrors) endpoint to see only the verification errors for a legal entity.

* Review the new webhook structure for verification statuses. The capability **sendToTransferInstrument** is now validated at both the transfer instrument resource and associated legal entity level. The capability status of the user is only visible at the legal entity level until they update their data or they have a required data review.

* Review the [required data points](/marketplaces/onboard-users/onboarding-steps).

* Review the new API structure when creating [/transferInstruments](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments). The new [type](https://docs.adyen.com/api-explorer/legalentity/latest/post/transferInstruments#request-type) field specifies whether the bank account is an IBAN or local account. The required information is then based on the type.

  * To integrate more quickly, we recommend using our [transfer instrument components](/marketplaces/onboard-users/components/transfer-instrument). The components reduce the number of API requests needed to create transfer instrument resources and are always updated to the latest onboarding API version. Additionally, these components enable your users to verify their bank accounts instantly when adding or updating their bank account details.

* Review the [new validations for name and address fields](/marketplaces/onboard-users/onboarding-versions/onboarding-v4/#validations).

* Align with the new API structure when creating business lines. The [capability](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-capability) field has been replaced by the [service](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-service) field. The [capability](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-capability) field is now deprecated. The possible values for [service](https://docs.adyen.com/api-explorer/legalentity/latest/post/businessLines#request-service) are:

  * **paymentProcessing**: corresponds to capability **receivePayments**
  * **banking** corresponds to capability **issueBankAccount**
  * **issuing** corresponds to capability **issueCard**

* When creating business lines, you must provide the [source of funds](/marketplaces/onboard-users/onboarding-versions/onboarding-v4/#source-funds) for both card issuing and business accounts.

### Test your integration

When you are ready to test the new onboarding version, reach out to your Adyen contact to ensure that all new features are enabled in your test environment. We strongly recommend that you perform integration tests for all major features and [check your error handling](/marketplaces/test-verification-errors) if the verification process is unsuccessful.

## See also

* [Release notes](/release-notes/platforms-and-financial-products/)
