---
title: "Upgrade to Adyen Payments for Salesforce OMS v3"
description: "Learn how to upgrade your Adyen Salesforce OMS package from v2 to v3."
url: "https://docs.adyen.com/plugins/salesforce-order-management-system/upgrade"
source_url: "https://docs.adyen.com/plugins/salesforce-order-management-system/upgrade.md"
canonical: "https://docs.adyen.com/plugins/salesforce-order-management-system/upgrade"
last_modified: "2024-08-20T13:11:00+02:00"
language: "en"
---

# Upgrade to Adyen Payments for Salesforce OMS v3

Learn how to upgrade your Adyen Salesforce OMS package from v2 to v3.

[View source](/plugins/salesforce-order-management-system/upgrade.md)

This page explains the steps to upgrade your [Adyen Salesforce Order Management System (OMS) package](/plugins/salesforce-order-management-system) from earlier versions to v3 of the package. See our [release notes](/plugins/release-notes) to learn what has changed in later versions.

### Tab: Migrate from v2

To migrate from v2 of the package to v3, follow the steps below.

## 1. Update your Payment Gateway configuration

The package now includes a Payment Gateway Provider Record, and you no longer need to [create your own](/plugins/salesforce-order-management-system/install-and-set-up-the-package/?plugin=Salesforce%20OMS\&integration=package\&version=2.1.2#create-payment-gateway-provider). To use the new record with your integration:

1. In your Salesforce OMS Org, go to **App Launcher**, enter **Payment Gateways** in the search field, and select it.

2. On the **Payment Gateways** page, select **Adyen**.

3. Update the following fields in the Payment Gateway record:

   | Field                    | Value                                                                                                                                                                                                                              |
   | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | Payment Gateway Provider | Select **Adyen OMS Provider**.                                                                                                                                                                                                     |
   | Merchant Credential      | Select **AdyenCheckout**.If you cannot select **AdyenCheckout**, go to **Setup** > **Named Credentials**, and select **Adyen Checkout**. Then, go back to the **Adyen** Payment Gateway record, select **Refresh**, and try again. |

4. Select the **Adyen OMS Provider** hyperlink.\
   This opens the Payment Gateway Provider page.

5. In the **Site URL**, find the ID, starting with **0cJ**.

6. Save this ID in your system, you will need it when you [update your webhook configuration](#update-your-webhook-configuration).

## 2. Update your webhook configuration

In v3:

* It is mandatory to [verify HMAC signatures](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures/).

* The following webhooks are enabled:

  * **REFUND\_FAILED**
  * **CAPTURE\_FAILED**

To make sure your integration can handle the changes introduced in this version:

1. [Update your webhook configuration in the Adyen Customer Area](#update-your-webhook-configuration-in-the-adyen-customer-area).
2. [Add your HMAC key in Salesforce](#add-your-hmac-key-in-salesforce).

After you have completed the steps, [test your new webhook configuration](/plugins/salesforce-order-management-system/install-and-set-up-the-package/?plugin=Salesforce%20OMS\&integration=package\&version=3.0.0#test-webhook) to make sure it works correctly.

### Update your webhook configuration in the Adyen Customer Area

Update your [existing webhook configuration](/plugins/salesforce-order-management-system/install-and-set-up-the-package/?plugin=Salesforce%20OMS\&integration=package\&version=2.1.2#configure-webhook) to add your new webhook endpoint URL and enable new events:

1. In your [Customer Area](https://ca-test.adyen.com/), go to **Developers** >  **Webhooks**.

2. Select the webhook that you have configured for the package.

3. Select the pencil icon **to edit this webhook.

4. Under **Server Configuration**, update the **URL** with your [Payment Gateway ID that you saved when you updated your Payment Gateway configuration](#update-your-payment-gateway-configuration). Use the following format:

   **Webhook endpoint URL format**

   ```text
   YOUR_SALESFORCE_SITE_URL/services/data/v60.0/commerce/payments/notify?provider=YOUR_PAYMENT_GATEWAY_PROVIDER_ID
   ```

   For example:

   **Example Webhook endpoint URL**

   ```text
   https://dev-clientname.cs17.force.com/adyen/services/data/v60.0/commerce/payments/notify?provider=0cJ4W000000XWnuUAG
   ```

5. Under **Security**, [generate a HMAC Key](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures#enable-hmac-signatures), copy it, and store it securely in your system.

6. Under **Events**, select **CAPTURE\_FAILED**, and **REFUND\_FAILED**.

7. Select **Save configuration**.

### Add your HMAC key in Salesforce

1. In your Salesforce B2B Org, go to **Setup** > **Custom Code** > **Custom Metadata Types**.

2. Select **Adyen Adapter**.

3. Add your HMAC key to the Adyen Adapter Layout:

   1. Scroll down to **Adyen Adapter Layout**, and select **Edit**.
   2. Drag the **HMAC Key** field, and drop it into the layout.
   3. Select **Save**.

4. Select **Manage Adyen Adapter**.

5. Next to **Adyen Default**, select **Edit**.

6. Set the **HMAC Key** field to the HMAC key you generated in the Adyen Customer Area.

7. Select **Save**.

## 3. Verify your sales channel setup

In v3, we changed how the Adyen merchant account field is populated for Salesforce sales channels. Choose one of the following options:

* Use the merchant account that you [configured in the **Adyen Default** custom metadata record](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package\&version=3.0.0#configure-adyen-custom-metadata).\
  For this option, leave the merchant account field empty in the sales channel object:

  1. In your OMS Org, go to the App Launcher, and search for **Sales Channels**.
  2. Select a sales channel.
  3. Leave the **Adyen Merchant Account** field empty.

* Link a specific merchant account to one of your sales channels.\
  For this option, follow the steps to [configure sales channels](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package\&version=3.0.0#configure-sales-channel).

We recommend to update the help text that appears for the merchant account field in the Sales Channel object:

1. In your Salesforce OMS Org, go to **Setup** > **Object Manager**.

2. Select **Sales Channel**.

3. Select **Fields & Relationships**, and then select **Adyen Merchant Account**.

4. Select **Edit** to replace the help text that appears for this field. For example:

   ```text
   The Adyen merchant account name used for this Sales Channel. When you leave this field empty, the merchant account configured for the Adyen Default custom metadata record will be used.
   ```

5. Select **Save**.

## 4. Update your Named Credential setup

The package includes the Named Credential by default, and uses API keys for authentication instead of [basic authentication](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package\&version=2.1.2#configure-named-credential).

To enable the new Named Credential in your integration, follow the steps to [set up a Principal Credential](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package\&version=3.0.0#configure-named-credential).

### Tab: Migrate from v1

If you are migrating from v1 to a later version of the package, we strongly recommend to migrate directly to [v3.2.0](/plugins/release-notes/?title%5B0%5D=Salesforce%20Order%20Management%20System). This version introduces changes and features that enable a better shopper and integration experience, such as better refund tracking, and Pay by Link payments.

To migrate form v1 to v3.2.0, follow the steps below.

## 1. Install the new version of the app

V3.2.0 of the package has a [separate namespace](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_unlocked_pkg_plan_namespaces.htm). Therefore, you can install it with your existing integration.

Install the [Adyen Payments for Salesforce Order Management (SOM)](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000ON7RtEAL\&tab=d) with the installation key **Payments\@Adyen**.

## 2. Set up the new version of the package

Follow the steps to [set up the package](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package\&version=3.2.0#how-it-works) for v3.2.0. You do **not** have to:

* [Create a new Payment Gateway record](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package\&version=3.2.0#set-up-payment-gateway). Instead, you can use your existing record and update it. To make your existing record compatible with the latest version:

  1. In your Salesforce Org, navigate to the existing Payment Gateway record you created for Adyen.

  2. Switch the following fields to the new values:

     | Field                    | Value                  |
     | ------------------------ | ---------------------- |
     | Payment Gateway Provider | **Adyen OMS Provider** |
     | Merchant Credential      | **AdyenCheckout**      |

  3. Select **Save**.

* [Create a new Salesforce site endpoint](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package\&version=3.2.0#expose-salesforce-site-endpoint). Instead, you can use your existing site endpoint and update the access settings. To make your existing site endpoint compatible the latest version:

  1. In your Salesforce OMS Org, navigate to the existing site you created for Adyen.
  2. Make sure that the site has **Guest Access to the Payments API**.
  3. Go to **Public Access Settings** > **Custom Metadata Type Access**.
  4. Make sure that the **Adyen Adapter** metadata type is in the **Enabled** column.
  5. Select **Save**.

## 3. Run the migration script

To copy payment method data to the new custom fields included in the new version, run the [`BatchAdyenOMSMigration.cls` ](https://github.com/Adyen/adyen-salesforce-oms/blob/develop/scripts/BatchAdyenOMSMigration.cls)migration script. This script copies your package's custom attribute values from your existing OMS version to the new version.

1. Add the script to your Salesforce Org by either:

   * Creating a new Apex class in your Salesforce Developer Console, and paste the script.
   * Deploying the Apex class in your Salesforce Org using the Salesforce CLI.

2. In your **Developer Console**, go to **Debug**> **Open Execute Anonymous Window**.

3. Enter the following code in the **Enter Apex Code** window and execute:

   ```java
   Id batchprocessid = Database.executeBatch(new BatchAdyenOMSMigration());
   ```

You receive an email when the batch process is completed.

## 4. Uninstall the older version

After you have completed the steps to upgrade, test your integration to make sure everything works as expected. Then, [uninstall the package for the older version from your Salesforce Org.](https://help.salesforce.com/s/articleView?id=000392277\&language=en_US\&type=1)

If you experience issues while uninstalling the package, remove the migration script from your Salesforce Org, and try again.

## Go live

After you have completed your upgrade, follow the [steps to go live](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package\&version=latest#go-live) with the version you migrated to.
