This page explains onboarding versioning and what you need to do in order to update to the latest onboarding 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 v3.
We are currently piloting onboarding v4. For more information about onboarding v4, see the v4 overview page.
Onboarding versioning
An onboarding version includes any breaking changes related to:
- Legal Entity Management API
- 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, 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 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.
Any API changes are always backward compatible, but not forwards compatible. Changes to the LEM API are described in our release notes.
For an overview of the changes between LEM v2, v3, and v4, see our LEM API changelog.
We aim to release new stable versions of the Legal Entity Management API and Hosted onboarding regularly. We recommend you upgrade 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.
As part of our API lifecycle management, we may need to sunset older versions of the Legal Entity Management API. 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 for more information about how to update to onboarding v3, the latest stable onboarding version.
Update your onboarding version
Select which onboarding version you want to update to below.
For a summary of the differences between Onboarding v2 and v3, you can also check our release notes.
To update your onboarding version:
- Reach out to your Adyen contact to discuss your update and timelines.
- Update your server integration to v3 of the Legal Entity Management API.
- Review and implement any new features.
- Test your integration.
- Go live with the new onboarding version.
The following table explains some key differences between onboarding v2 and v3 for specific features.
| Features | User onboarded in older version | New user onboarded in latest version | |
|---|---|---|---|
| Verification deadlines | Available after the onboarding version is updated. Capabilities that were invalid in the older version do not automatically receive verification deadlines. | Available | |
| PCI enforcement | Acceptance by the user is backfilled. Any updates to sales channels may require the user to sign new PCI questionnaires. | Enforced when onboarding | |
| Acceptance of Adyen's 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, 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 or has a required data review.
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 v3.
To support onboarding v3, you need to implement the following backend changes to your systems:
- Implement logic to notify your users when they have a required data review. The user can confirm or update their information in the hosted onboarding page.
- Implement logic to interpret and enforce verification deadlines.
- 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. In v3, verification errors are shown with all affected capabilities as an array underneath. You can also use the new /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 new compliance requirements.
-
Align with the new API structure when creating business lines. The capability field has been replaced by 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
For an overview of the differences between Onboarding v2 and v4, see the dedicated v4 overview page and the v2-v4 LEM API changelog.
To update your onboarding version to v4:
- Reach out to your Adyen contact to discuss your update and timelines.
- Update your server integration to v4 of the Legal Entity Management API.
- Review and implement any new features.
- Test your integration.
- Go live with the new onboarding version.
The following table explains some key differences between onboarding v2 and v4 for specific features.
| Features | User onboarded in older version | New user onboarded in latest version | |
|---|---|---|---|
| Verification deadlines | Available after the onboarding version is updated. Capabilities that were invalid in the older version do not automatically receive verification deadlines. | Available | |
| PCI enforcement | Acceptance by the user is backfilled. Any updates to sales channels may require the user to sign new PCI questionnaires. | Enforced when onboarding | |
| Acceptance of Adyen's 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, 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 or has a required data review.
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. The user can confirm or update their information in the hosted onboarding page.
-
Implement logic to interpret and enforce verification deadlines.
-
Review the new compliance requirements 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 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.
-
Review the new validations for name and address fields.
-
Align with the new API structure when creating business lines. The capability field has been replaced by 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
- issuing corresponds to capability issueCard
-
When creating business lines, you must provide the source of 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 if the verification process is unsuccessful.