This page explains 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.
To update your onboarding version to use the latest version (v3), see here. For a summary of the differences between Onboarding v2 and v3, you can also check our release notes.
Onboarding versions
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 plan to support older onboarding versions for approximately 24 months from the release date of the 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. Any API changes are always backward compatible, but not forwards compatible. Changes to the LEM API are described in our release notes.
Breaking changes to the LEM API
We make breaking changes in order to:
- Introduce new onboarding features.
- Enhance onboarding performance and stability.
- Ensure compliance with new regulatory requirements.
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.
Release schedule
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. Release candidate versions do not offer hosted onboarding support. 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 upgrading to new versions
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 upgrade 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 upgrade to the latest API version before the sunset date. This is so that your hosted onboarding page remains up-to-date.
Update from Onboarding v2 to Onboarding v3
To update your onboarding version:
- Reach out to your Adyen contact to discuss your update and timelines.
- Update your server integration to the latest version 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, 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.
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.