---
title: "Migrate to a new version"
description: "Follow these instructions to migrate your Adobe Commerce plugin to a new major version"
url: "https://docs.adyen.com/plugins/adobe-commerce/migrate-to-a-new-version"
source_url: "https://docs.adyen.com/plugins/adobe-commerce/migrate-to-a-new-version.md"
canonical: "https://docs.adyen.com/plugins/adobe-commerce/migrate-to-a-new-version"
last_modified: "2024-08-20T11:44:00+02:00"
language: "en"
---

# Migrate to a new version

Follow these instructions to migrate your Adobe Commerce plugin to a new major version

[View source](/plugins/adobe-commerce/migrate-to-a-new-version.md)

On this page, we describe the changes that you need to make in your existing integration when migrating to a later version of the Adobe Commerce plugin.

### Tab: Migrate to version 10

## Step 1: Upgrade Adobe Commerce and PHP

Version 10 of the plugin supports PHP 8.2 and later, and Adobe Commerce 2.4.8. We no longer support Adobe Commerce 2.4.7 or earlier due to the backward incompatible changes introduced in later versions.

If you are on an earlier version, upgrade your [Adobe Commerce](https://experienceleague.adobe.com/en/docs/commerce-operations/release/notes/magento-open-source/2-4-8) and [PHP version](https://www.php.net/manual/en/migration82.php) before you upgrade the plugin.

## Step 2: Upgrade the plugin

Follow the [instructions to upgrade the plugin](/plugins/adobe-commerce/upgrade) to version 10.

## Step 3: Check dependencies

Version 10 of the plugin uses:

* [Checkout API version 71](/online-payments/release-notes?integration_type=api\&version=71): if you have customized the plugin logic, upgrading could cause issues in the implementation of your custom code. Check if your integration is compatible with the new version of Checkout API.
* [Web Components version 6.13.1](/online-payments/release-notes/?integration_type=web\&version=6.13.1): Web Components v6 introduces various changes. If you applied any customizations to our Components, or have a [headless integration](/plugins/adobe-commerce/headless-integration), review the changes to make sure your integration is compatible. Refer to our [migration guide](/online-payments/upgrade-your-integration/migrate-to-web-v6/) to learn about the changes you may need to apply depending on what you have customized.

If you are using the default checkout and payments logic offered with the plugin, you do not need to take any action.

## Step 4: Review breaking changes

Version 10 of the plugin introduces breaking changes to plugin logic and functionality. If you have any customizations based on logic that was removed or added by these breaking changes, it is your responsibility to verify that your customizations are still compatible.

Review the breaking changes in our [release notes](/plugins/release-notes) to learn if any of the changes affect your integration.

### Tab: Migrate to version 9

V9 introduces a new configuration page that makes it easier to configure your plugin. See the [release notes](/plugins/release-notes/#releaseNote=2023-10-23-adobe-commerce-9.0.1) for an overview of all changes.

## Step 1: Upgrade the plugin

Follow the [instructions to upgrade the plugin](/plugins/adobe-commerce/upgrade) to version 9.

## Step 2: Upgrade PHP

Adobe Commerce v2.4.4 [requires PHP 8.1 or later](https://experienceleague.adobe.com/docs/commerce-operations/installation-guide/system-requirements.html) to be installed on your server. Refer to the [PHP documentation](https://www.php.net/ChangeLog-8.php#8.1.23) to see the changes for this PHP version.

If you are running a PHP version earlier than 8.1, install the required version.

## Step 3: Check dependencies

Version 9.0.1 of the plugin uses [Checkout API version 70](/online-payments/release-notes?integration_type=api\&version=70) and [Components version 5.51.1](/online-payments/release-notes/?integration_type=web\&version=5.51.1). If you have customized the plugin, upgrading could cause issues in the implementation of your custom code. Check if your integration is compatible with the new versions of Checkout API and Components, and apply changes if needed.

We update our plugin dependencies regularly to make new features and fixes available. If you are upgrading to a version later than v9.0.1, check our [release notes](/plugins/release-notes) to see if the Checkout API or Web Components versions have changed.

## Step 4: Change your webhook server configuration

If you [set up your integration manually](/plugins/adobe-commerce/set-up-adyen-customer-area/?tab=manual_2), you have to change your webhook server configuration to ensure you continue to receive webhooks from us.

1. Log in to your [Customer Area](https://ca-test.adyen.com/).
2. Select **Developers** > **Webhooks**.
3. Next to the webhook you added when you [set up webhooks](/plugins/adobe-commerce/set-up-adyen-customer-area/?tab=manual_2#step-3-set-up-webhooks), select **> **Edit webhook**.
4. Under **General** > **Server configuration**, select the edit icon **.
5. Change the ending of the **URL** from `/process/json` to `/webhook`. For example, from `https://THE_URL_OF_YOUR_STORE/adyen/process/json` to `https://THE_URL_OF_YOUR_STORE/adyen/webhook`.
6. Select **Apply**.
7. Select **Save changes**.

## Step 5: Verify changes in payment methods

### Changes to payment methods and how they are shown

* All payment methods are now registered independently on the Adobe Commerce platform. Previously, the plugin grouped payment methods into cards and alternative payment methods. With the separation of payment methods to their own files, payment methods are sorted based on the order in your Customer Area.

* You can now enable all payment methods that you have enabled in your Customer Area by selecting a single button in Adobe Commerce.

  After upgrading your plugin, make sure that [you have enabled the payment methods](/plugins/adobe-commerce/set-up-the-payment-methods-in-adobe-commerce#enable-payment-methods-in-adobe-commerce).

* By default, the payment methods shown to shoppers during checkout are based on their billing address country/region. You can override this with the [**ISO Country Code** setting](/plugins/adobe-commerce/set-up-the-payment-methods-in-adobe-commerce#alternative-payment-methods).

**

### Changes for customized and headless integrations

* If you applied customizations to the way payment methods are handled in your plugin, upgrading may cause issues in the implementation of your custom code. Check if your custom code is compatible with the new payment method set up.

* For headless integrations:

  1. You now have to send the individual payment method names in your requests [when placing orders](/plugins/adobe-commerce/headless-integration#place-order).
  2. You no longer need to include `shippingAddress` object in your request to the [/paymentMethods](https://docs.adyen.com/api-explorer/Checkout/latest/post/paymentMethods) endpoint when [getting available payment methods](/plugins/adobe-commerce/headless-integration#get-payment-methods).

## Step 6: Verify changes to the gift card flow

Gift card payments have a new native flow.

Previously, shoppers were redirected to an Adyen-hosted payment page. In v9, gift card payments use the [Checkout API](https://docs.adyen.com/api-explorer/Checkout/latest/overview) [/orders](https://docs.adyen.com/api-explorer/Checkout/latest/post/orders) endpoint and shoppers can complete [partial gift card payments](/online-payments/partial-payments/) in one native flow.

If you previously set up gift card payments in your integration, using the new flow requires additional configuration on our end. Contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other).

## Step 7: Verify changes to tokenization

The plugin uses the [Adobe Commerce Vault](https://developer.adobe.com/commerce/php/development/payments-integrations/vault/) for tokenization. Previously, you could choose between storing token references in Adyen or Adobe Commerce.

If you use tokenization, you have to reconfigure the payment methods for which you want to enable tokenization, and specify a recurring processing model. Follow the instructions to [set up the Vault in Adobe Commerce](/plugins/adobe-commerce/set-up-tokenization#set-up-vault).

If you previously used Adyen tokenization, the tokens are migrated to the Adobe Commerce Vault automatically. To verify the migration, you can manually check if your token references are stored correctly.

## Next steps

[Troubleshoot](/plugins/adobe-commerce/troubleshooting/)

[Monitor your migration and follow the steps in our Troubleshooting guide if you experience any issues.](/plugins/adobe-commerce/troubleshooting/)
