---
title: "Manually set up the package"
description: "Manually set up and configure your Adyen Salesforce OMS package"
url: "https://docs.adyen.com/plugins/salesforce-order-management-system/install-and-set-up-the-package/manual-setup"
source_url: "https://docs.adyen.com/plugins/salesforce-order-management-system/install-and-set-up-the-package/manual-setup.md"
canonical: "https://docs.adyen.com/plugins/salesforce-order-management-system/install-and-set-up-the-package/manual-setup"
last_modified: "2025-10-14T12:10:00+02:00"
language: "en"
---

# Manually set up the package

Manually set up and configure your Adyen Salesforce OMS package

[View source](/plugins/salesforce-order-management-system/install-and-set-up-the-package/manual-setup.md)

This page explains how to manually integrate with our OMS package to manage orders for your Salesforce Commerce Cloud store that uses the Adyen payments cartridge.

For Salesforce OMS v3.3.0 and later, the default setup is through the [guided configuration](/plugins/salesforce-order-management-system/install-and-set-up-the-package?plugin=Salesforce%20OMS\&integration=package#guided-configuration).

Use the instructions on this page if you want to set up your Salesforce OMS package manually.

## Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

| Requirement                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------------------------- |   |
| **Integration type**                            | Make sure that you have a Salesforce Commerce Cloud (SFCC) storefront that uses the [Adyen payments cartridge](/plugins/salesforce-commerce-cloud).                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **[Webhooks](/development-resources/webhooks)** | Subscribe to the Standard webhooks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| **Setup steps**                                 | Before you begin:- Create a Salesforce OMS Org.
- Connect your SFCC storefront and OMS Org. Refer to [the documentation from Salesforce](https://resources.docs.salesforce.com/latest/latest/en-us/sfdc/pdf/sfom_impl_b2ce.pdf) to read more about connecting B2C Commerce and Order Management.
- [Enable manual capture](/online-payments/capture/#enable-manual-capture) in your Customer Area.
- Install the base dependent [`API Library Apex Adyen` package](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000PraxuEAB) with the installation key **Payments\@Adyen**. |

## How it works

With our Salesforce OMS package, you handle captures and refunds for the payments of your [Salesforce Commerce Cloud storefront](/plugins/salesforce-commerce-cloud). The package keeps the Adyen and Salesforce systems in sync, so that you can seamlessly manage your order and payment flows.

To set up the package:

1. [Install the package](#install-the-app).
2. [Configure package components](#set-up-payment-gateway) in your OMS Org.
3. [Set up the payment gateway](#configure-package-components) in your OMS Org.
4. [Set up webhooks](#set-up-webhooks) in your OMS Org and the Adyen Customer Area.
5. [Set up alternative payment methods](#set-up-alternative-payment-methods) in your OMS Org.
6. [Configure capture settings](#configure-capture-settings) in your SFCC Business Manager.

## Install the app

1. In your Salesforce OMS Org, [enable multiple currencies](https://help.salesforce.com/s/articleView?id=sf.comm_currency_considerations.htm\&type=5).
2. Install the [Adyen Payments for Salesforce Order Management (SOM) app](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3u00000ON7RtEAL\&tab=d) with the installation key **Payments\@Adyen**.
3. Follow the instructions on the [Salesforce Application Installation Guide](https://developer.salesforce.com/docs/atlas.en-us.appExchangeInstallGuide.meta/appExchangeInstallGuide/appexchange_install_installation.htm).

## Set up the Payment Gateway

To set up the Payment Gateway:

1. [Create a Payment Gateway record](#create-payment-gateway).
2. Only if you process [in-person payments with endless aisle](/plugins/salesforce-commerce-cloud/sfra/set-up-the-cartridge?plugin=Salesforce%20SFRA\&integration=cartridge\&version=latest#set-up-in-person-payments), [create a payment gateway record for in-person payments](#create-pos-payment-gateway).

### Create a Payment Gateway record

Create a Payment Gateway record in Salesforce:

1. In the **App Launcher**, search for **Payment Gateways** and select it.

2. Select **New** and enter the following values into the corresponding fields:

   | Field                    | Value                                                                                                                                                                                                                                                                                                                                                           |
   | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | Payment Gateway Name     | **Adyen**                                                                                                                                                                                                                                                                                                                                                       |
   | Payment Gateway Provider | Select **Adyen OMS Provider**.                                                                                                                                                                                                                                                                                                                                  |
   | Merchant Credential      | Select **AdyenCheckout**.Due to a [known Salesforce issue](https://issues.salesforce.com/issue/a028c00000zLQG6AAO/), you may not be able to select **AdyenCheckout**. If you experience this, go to **Setup** > **Named Credentials**, and select **Adyen Checkout**. Then, go back to the **Adyen** Payment Gateway record, select **Refresh**, and try again. |
   | Status                   | **Active**                                                                                                                                                                                                                                                                                                                                                      |
   | External Reference       | **Adyen\_Component**. This value must match your SFCC B2C Payment Processor ID.                                                                                                                                                                                                                                                                                 |

3. Select **Save**.

### Create a Payment Gateway record for in-person payments

This step is only required if you process [in-person payments with endless aisle](/plugins/salesforce-commerce-cloud/sfra/set-up-the-cartridge?plugin=Salesforce%20SFRA\&integration=cartridge\&version=latest#set-up-in-person-payments).

Create a Payment Gateway record in Salesforce:

1. In the **App Launcher**, search for **Payment Gateways** and select it.

2. Select **New** and enter the following values into the corresponding fields:

   | Field                    | Value                                                                     |
   | ------------------------ | ------------------------------------------------------------------------- |
   | Payment Gateway Name     | **AdyenPos**                                                              |
   | Payment Gateway Provider | Select **Adyen OMS Provider**.                                            |
   | Merchant Credential      | Select **AdyenCheckout**.                                                 |
   | Status                   | **Active**                                                                |
   | External Reference       | **Adyen\_POS**. This value must match your SFCC B2C Payment Processor ID. |

3. Select **Save**.

## Set up webhooks

Adyen uses webhooks to send you updates on payment statuses. To enable receiving these webhooks:

1. [Expose a Salesforce site endpoint](#expose-salesforce-site-endpoint). You need to expose different Salesforce site endpoints to receive default payment status updates, and updates related to payment modifications initiated from the Adyen Customer Area.
2. [Update the Site URL](#update-site-url-for-the-named-credential) for your Named Credential.
3. [Configure webhooks](#configure-webhook) in the Customer Area, for each of your Salesforce site endpoints.
4. [Test your webhook configuration](#test-webhook).

### Expose the Salesforce site endpoint

1. In your Salesforce OMS Org, go to **Setup** > **User Interface** > **Sites and Domains** - **Sites**, and then select **Sites**.
2. Select **New**.
3. Enter a label, for example **Adyen**.
4. Enter a unique value for the default web address, for example `http://dev-myorganization--sandbox.cs17.force.com/adyen`.
5. Select **Active**.
6. Select an **Active Site Home Page**, for example, **UnderConstruction**.
7. Select **Guest Access to the Payments API**.
8. Select **Save** to save your changes and make sure the site is active.

**Webhook endpoint URL format**

```text
YOUR_SALESFORCE_SITE_URL/adyen/services/apexrest/adyen_payment/adyenNotification/v1
```

For example:

**Example Webhook endpoint URL**

```text
https://dev-clientname.cs17.force.com/adyen/services/apexrest/adyen_payment/adyenNotification/v1
```

Save the endpoint URL in your system, you will need it when you [configure webhooks in the Customer Area](#configure-webhook).

#### Configure permissions for the site endpoint

1. From the **Site details** page, click **Public Access Settings**.
2. Configure Custom Metadata Type Access:
   * Under **Apps**, select **Custom Metadata Type Access**, click **Edit** and enable the Adyen Adapter metadata type by moving it to the **Enabled** column, then **Save**.
3. Configure Apex Class Access:
   * Under **Apps**, select **Apex Class Access**, click **Edit**, and add **AdyenWebhookNotificationHandler** & **NonPaymentWebhookHandler** to **Enabled Apex Classes**, then **Save**.
4. Configure External Credential Principal Access:
   * Under **Apps**, select **External Credential Principal Access**, click **Edit**, add **NoAuthCredential** to **Enabled External Credential Principals**, then **Save**.

### Update Site URL for the Named Credential

1. Go to **Setup** > **Security** > **Named Credentials**, and select **AdyenWebhookEndpoint**.
2. On the Named Credential page, select **Edit**.\
   This opens a modal window.
3. For the **URL**< enter your Salesforce site URL. For example: <https://dev-clientname.cs17.force.com/adyen>.
4. Select **Enable for Callouts**.
5. Select **Save**.

### Configure webhooks in the Customer Area

Configure webhooks for each of the Salesforce site endpoint URLs you exposed.

To configure a webhook:

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

   We [recommend to configure webhooks for your company account](/development-resources/webhooks/configure-and-manage#configuring-a-webhook). This ensures that you do not have duplicate webhook configurations, and improves performance.

2. Select ****Webhook**.

3. From the list of webhooks, next to **Standard webhook**, select **Add**.

4. Under **General**, configure the following:

   | Setting               | Description                                                                                                        |
   | --------------------- | ------------------------------------------------------------------------------------------------------------------ |
   | **Enabled**           | Select the toggle to enable or disable the webhook.                                                                |
   | **Version**           | The webhook version.                                                                                               |
   | **Description**       | Your description of the webhook.                                                                                   |
   | **Merchant accounts** | You can apply the webhook to all merchant accounts under a company account, or only to specific merchant accounts. |

5. Under **Server configuration**, configure the following:

   | Setting                 | Description                             |
   | ----------------------- | --------------------------------------- |
   | **URL**                 | Your webhook endpoint URL.              |
   | **Method**              | **JSON**                                |
   | **Encryption protocol** | The latest **TLS version** in the list. |

6. Under **Security**, configure the following:

| Setting      | Description                                                                                                                                                                                                                                                                   |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HMAC Key** | [Generate the HMAC Key](/development-resources/webhooks/secure-webhooks/verify-hmac-signatures#enable-hmac-signatures), copy it, and store it securely in your system. You need to enter the HMAC key when you [configure package components](#configure-package-components). |

1. Under **Events**, in addition to the default events that are selected, select the following events:

   * **CAPTURE**, **CAPTURE\_FAILED**, **REFUND**, and **REFUND\_FAILED**.
   * For [Authorization Reversal](/plugins/salesforce-order-management-system/authorization-reversal), select **CANCELLATION**.
   * For [Order on Behalf Of](/plugins/salesforce-order-management-system/set-up-oobo), select **AUTHORISATION**.

2. Select **Save configuration**.

Rarely, a refund or capture can fail after you have received a **REFUND** or **CAPTURE** webhook with `success:` **true**. After a payment is processed in Salesforce, the status cannot be changed. Therefore, we recommend to monitor these cases in the `GatewayResultCode` field of the [PaymentGatewayLog](https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_paymentgatewaylog.htm) object in Salesforce. When a refund or capture fails, the `GatewayResultCode` is marked with **CAPTURE\_FAILED**, or **REFUND\_FAILED**. Learn more in our [Capture](/online-payments/capture#failed-capture) and [Refund](/online-payments/refund#refund-failed) documentation.

### Test your webhook configuration

Before you can test your webhook configuration, you have to add your HMAC key in your [Salesforce custom metadata configuration](#configure-adyen-custom-metadata).

1. In your [Customer Area](https://ca-test.adyen.com/), go to **Developers** > **Webhooks**.
2. Next to **Standard webhook**, select the edit webhook icon **.
3. Select **Test Configuration**.
4. If you are on a [company account](/account/account-structure#company-account), select a **Merchant account** from the dropdown list.
5. In the **Event** dropdown list, select the [event code](/development-resources/webhooks/webhook-types#event-codes).

If your webhook configuration is correct, it shows a [successful HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses), for example `ResponseCode`: **200**.

## Configure package components

In your Salesforce OMS Org, configure package components:

1. [Add new Adyen fields to the layout](#add-adyen-fields-to-layout).
2. [Set up the Principal Credential](#set-up-the-principal-credential).
3. [Configure Adyen custom metadata type](#configure-adyen-custom-metadata).
4. Optionally, [configure a merchant account for a sales channel](#configure-sales-channel).

### Add new Adyen fields to the layout

1. From **Setup**, go to **Object Manager**.
2. Search for and click on the **Sales Channel** object.
3. Click on **Page Layouts** and select the page layout that you want the new **Adyen Merchant Account** field to appear in.
4. Drag and drop the field to your selected layout.
5. Click **Save**.

Repeat these steps for the **Payment** and **Payment Authorization** objects by adding the **Adyen Payment Method** and **Adyen Payment Method Variant** fields.

### Set up the Principal Credential

The package uses Named Credentials to perform authentication between the Salesforce OMS and Adyen. When you [install the app](#install-the-app), the [Named Credential](https://help.salesforce.com/s/articleView?id=sf.named_credentials_about.htm\&type=5) is set up automatically.

You must also set up a [Principal Credential](https://help.salesforce.com/s/articleView?id=sf.nc_enable_ext_cred_principal.htm\&type=5).

[Legacy Named Credentials ](https://help.salesforce.com/s/articleView?id=sf.named_credentials_legacy_about.htm\&type=5)are deprecated by Salesforce and are not used in our package from this version onwards.

These steps below are based on the [Salesforce Enhanced Profile User Interface](https://help.salesforce.com/s/articleView?id=sf.users_profiles_about_enhanced_ui.htm\&type=5). If you use the old view, the steps you have to take may differ.

In addition to the Named Credential, you need to set up a Principal Credential. To do this, in your OMS Org:

1. Go to **Setup** > **Security** > **Named Credentials**.

2. Under **External Credential**, select **Adyen API**.

3. Under **Principals**, next to the **AdyenParameterKey**, select the **Actions** button, and then select **Edit**.\
   This opens a modal window.

4. Select **Add**, and add an authentication parameter with the following properties:

   * **Name**: **ApiKey**
   * **Value**: [Your API key](/development-resources/api-credentials/#generate-api-key)

After setting up the Principal, give access to this Principal with a permission set:

1. Go to **Setup** > **Users** > **Permission Sets**.

2. Select **New**.

3. In the **Label** field, enter a name, and select **Save**.

4. Select **External Credential Principal Access**.

5. Select **Edit** and enable the Principal you have set up by moving it from the **Available** to the **Enabled** column.

6. Go back to the permission set, and select **Object Settings**.

7. Select **User External Credentials**, and select **Edit**.

8. Next to **Read**, select the checkbox to give read access.

9. Assign the permission set you have created to the **Automated Process** user. This user is a hidden Salesforce user that runs scheduled flows and other automated processes, including the payment flows. If you have modified [your process automation settings ](https://help.salesforce.com/s/articleView?id=sf.wf_approval_settings.htm\&type=5), this user may differ.

   1. Select **Manage Assignments**, and then select **Add Assignment**.
   2. In the user list, select the **Automated Process** user, and select **Next**.\
      If the user is not visible in the list, switch to the **All Users** list view and search for **auto**,
   3. Select **Assign**.

   Alternatively, you can assign also assign the permission set to the **Automated Process** user by:

   1. In your Developer Console, query the Profile Id for this user with the following:

      ```txt
      SELECT ProfileId FROM User WHERE Alias = 'autoproc'
      ```

   2. Construct a URL to access the page where you can edit permissions.

      ```txt
      YOUR_SF_ORG_URL/_ui/system/user/ProfileExternalCredentialPrincipalPermissionEdit/e?profile_id=PROFILE_ID
      ```

      * `YOUR_SF_ORG_URL`: Your Salesforce Org Url.
      * `PROFILE_ID`: The profile Id you received as a result to the query.

   3. Navigate to the URL that you constructed.

   4. Select **Edit** and enable the Principal you have set up by moving it from the **Available** to the **Enabled** column.

   5. Select **Save**.

### Configure Adyen custom metadata type

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

2. Next to **Adyen Adapter**, select **Manage Records**.

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

4. Fill the following fields:

   * **Merchant Account**: your [Adyen merchant account name](/account/account-structure#merchant-accounts). This field is case-sensitive.
   * **HMAC Key**: your [HMAC key](#set-up-webhooks).
   * **Webhook ID**: your [Webhook](/development-resources/webhooks/configure-and-manage#set-up-webhooks-in-your-customer-area) ID.

5. Select **Save**.

After you have added your HMAC key in Salesforce, [test your webhook configuration](#test-webhook).

### (Optional) Configure sales channels

Optionally, you can link your [sales channels ](https://help.salesforce.com/s/articleView?id=sf.om_sales_channel_fields.htm\&type=5)to use specific Adyen merchant accounts. Sales channels that are not linked to a specific merchant account use the merchant account you [configured in the **Adyen Default** custom metadata record](#configure-adyen-custom-metadata).

Before you can link an Adyen merchant account to a sales channel, make sure that:

* The merchant account has [API permissions](/development-resources/api-credentials/#api-permissions).
* There is a [custom metadata record](#configure-adyen-custom-metadata) with the merchant account name in the **Adyen Adapter** custom metadata object.

To link an Adyen merchant account to a sales channel:

1. In your OMS Org, go to the App Launcher, , search for **Sales Channels**.
2. Select the **Sales Channel** that you want to configure a merchant account for.
3. Set the **Adyen Merchant Account** field to the name of the merchant account that you want to link to this sales channel.

## Set up alternative payment methods

To set up alternative payment methods, add permissions in Salesforce:

1. In your Salesforce OMS Org, go to **Setup** > **Permission Sets** > **Order Management B2C service** > **Object Settings** > **Alternative Payment Methods** > **Edit**.
2. Under **Record Type Assignments** > **Alternative Payment Method record type**, select the **Assigned Record Types** checkbox.
3. Click **Save**.
4. Go back to **Object Settings** and go to **Payment Authorizations** > **Edit**.
5. Under **Field Permissions**, add **Edit access** for the **Adyen Payment Method** and **Adyen Payment Method Variant** fields.
6. Click **Save**.
7. Go back to **Object Settings** and go to **Payments** > **Edit**.
8. Under **Field Permissions**, add **Edit access** for the **Adyen Payment Method** and **Adyen Payment Method Variant** fields.
9. Click **Save**.

## Configure capture settings

With our OMS package, you can capture payments at any step in your order fulfillment flow. The steps you need to follow to configure captures in SFCC depends on your capture setting in the Adyen Customer Area:

* [**Manual capture** ](/online-payments/capture/#manual-capture): you can capture payments from the OMS after they have been authorized.
* [**Automatic capture** ](/online-payments/capture): payments are captured automatically after authorization. You do not have to manually capture payments from the OMS. Our OMS package handles the automatic captures without disrupting the payment flow. If you have set up automatic capture in your Customer Area, follow the steps to [enable automatic captures with OMS](#enable-automatic-captures).

Regardless of your setting, payments for some payment methods are captured immediately after authorization. You must [specify these payment methods](#payment-methods-without-capture) in your Salesforce Business Manager to prevent duplicate capture requests.

### Enable automatic captures

To prevent OMS from making duplicate capture requests to Adyen when you have set up [automatic captures](/online-payments/capture) in your Adyen Customer Area, follow the steps below.

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

2. Select **Adyen Adapter**.

3. Scroll down to **Adyen Adapter Layout**, and select **Edit**.

4. Drag and drop the **Auto Capture Enabled** and **Manual Capture Payment Methods** fields to the **Adyen Adapter Layout**.

5. Select **Save**.

6. Select **Manage Adyen Adapters**.

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

8. Select the checkbox next to **Auto Capture Enabled**.\
   When you have set this up, OMS will process the payment record without an additional capture request, and the following payment gateway log will be created:

   ```text
   [capture-complete] Auto Capture enabled
   ```

9. For some payment methods, manual captures are required even when you have set up automatic captures in your Adyen Customer Area. In the **Manual Capture Payment Methods** field, specify the payment methods that require manual capture, using the [`paymentMethodVariant` ](/development-resources/paymentmethodvariant/)for each payment method. Separate each variant with a comma, for example:

   ```text
   klarna, klarna_account
   ```

10. Select **Save**.

### Specify payments without separate captures in SFCC

Payments for some payment methods are captured immediately after authorization regardless of your capture settings. You need to specify these payment methods that you enabled in the Adyen Customer Area in your Salesforce Business Manager. This prevents OMS from initiating duplicate capture requests.

1. In your [Salesforce Business Manager](/plugins/salesforce-commerce-cloud/sfra/set-up-the-cartridge/?plugin=Salesforce%20SFRA\&integration=cartridge\&version=latest#set-up-the-business-manager), go to **Merchant Tools** > **Site Preferences** > **Adyen settings** > **Local payment method settings**.
2. In the **Payment methods without separate capture** field, specify the payment methods that you added in your Customer Area. Separate each variant with a comma, for example:
   ```text
   ideal, paypal, applepay, visa_applepay, mc_applepay, amex_applepay, klarna_paynow, twint, sepadirectdebit, bcmc, wechatpay, multibanco, blik, mbway, pix, onlineBanking_PL
   ```
3. Select **Save Changes**.

## Go live

When you are ready to go live, [apply for a live account](/get-started-with-adyen/application-requirements). Review the process to start accepting payments on [Get started with Adyen](/get-started-with-adyen).

When you get your live account:

1. Follow our [SFCC go-live checklist](/plugins/salesforce-commerce-cloud/go-live-checklist). You do not need to follow the steps to [configure the SFCC Business Manager](/plugins/salesforce-commerce-cloud/go-live-checklist#business-manager) in the checklist.

2. Update the Adyen credentials you used to set up your Salesforce OMS Org:

   * In the [custom metadata record](#configure-adyen-custom-metadata):

     1. Update your HMAC key.
     2. If you are using a different merchant account in the live environment, update the merchant account name.

3. Switch the URL for the **Adyen Checkout** named credential to your live URL:

   1. In your OMS Org, go to **Setup** > **Security** > **Named Credentials**.
   2. Select the **Adyen Checkout** named credential.
   3. Replace the test URL with `https://[YOUR_LIVE_PREFIX]-checkout-live.adyenpayments.com/checkout`. [Get your live prefix](/development-resources/live-endpoints/#live-url-prefix) from the live Customer Area.

4. Switch your test API key to your live API Key:

   1. Select the **External Credential** linked to your **Adyen Checkout** named credential.
   2. Under **Principals**, update your API key authentication parameter to your live API key.

## Next steps

[Set up Order on Behalf Of](/plugins/salesforce-order-management-system/set-up-oobo)

[Enable your customer service employees to place orders on behalf of shoppers.](/plugins/salesforce-order-management-system/set-up-oobo)

[Enable Auhtorization Reversals](/plugins/salesforce-order-management-system/authorization-reversal)

[Handle situations where you need to reverse an authorization.](/plugins/salesforce-order-management-system/authorization-reversal)
