---
title: "Set up the cartridge"
description: "Set up the cartridge in the Adyen Customer Area and in the Salesforce Business Manager."
url: "https://docs.adyen.com/plugins/salesforce-commerce-cloud/sfra/set-up-the-cartridge"
source_url: "https://docs.adyen.com/plugins/salesforce-commerce-cloud/sfra/set-up-the-cartridge.md"
canonical: "https://docs.adyen.com/plugins/salesforce-commerce-cloud/sfra/set-up-the-cartridge"
last_modified: "2026-06-01T15:33:15+02:00"
language: "en"
---

# Set up the cartridge

Set up the cartridge in the Adyen Customer Area and in the Salesforce Business Manager.

[View source](/plugins/salesforce-commerce-cloud/sfra/set-up-the-cartridge.md)

## Salesforce SFRA cartridge

Use our SFRA cartridge for accepting payments

### Before You Begin

## Requirements

Before you begin, make sure that you have performed the following steps:

1. [Create a test account with Adyen](/get-started-with-adyen). With this, you will be able to access the [test Customer Area](https://ca-test.adyen.com/), and apply for a live account. While you wait for your live account credentials, you can start integrating by using your test account.

2. Finish the [metadata import](/plugins/salesforce-commerce-cloud/sfra/install-the-cartridge-and-import-the-metadata).

3. In Salesforce Commerce Cloud, [enforce HTTPS](https://documentation.b2c.commercecloud.salesforce.com/DOC1/index.jsp?topic=%2Fcom.demandware.dochelp%2Fcontent%2Fb2c_commerce%2Ftopics%2Fadmin%2Fb2c_configure_enforce_https_global_preference.html).

   To be compatible with the Chrome v80 Cookie policy, you need to enforce the use of HTTPS for all sites.

    

### Account structure

With Adyen, you have a single [company account](/account/account-structure#company-account), and one or more sub-accounts called [merchant accounts](/account/account-structure#merchant-accounts). However, in Salesforce, you can only have one merchant account for each storefront.

### Set Up The Cartridge Path

## Step 1: Set up the cartridge path

To set up the cartridge path in the Business Manager: 

1. Go to **Administration** > **Sites** > **Manage Sites&#xA0;**>**&#xA0;\[yourSite]&#xA0;**>**&#xA0;Settings.&#xA0;**

2. In th&#x65;**&#xA0;Cartridges&#xA0;**&#x62;ox, enter:\
   **app\_adyen\_SFRA:int\_adyen\_SFRA:int\_adyen\_webhooks:app\_storefront\_base**

   If you are using any form of customizations, make sure to follow our [customization guide](/plugins/salesforce-commerce-cloud/sfra/customization-guide) on best practices around customizations.

3. Select **Apply**.

### Enable Bm Page

## Step 2: Enable the Salesforce Business Manager configuration page

To show the **Adyen Settings** menu item in your Salesforce Business Manager:

1. Go to **Administration** > **Sites** > **Manage Sites** > **Business Manager - Settings**.
2. In the **Cartridges** box, enter **bm\_adyen:int\_adyen\_SFRA:app\_storefront\_base**. Select **Apply**.
3. Go to **Administration** > **Organization** > **Roles & Permissions** > **Administrator - Business Manager Modules**.
4. In the dialogue box, select the site you want to enable Adyen for or select the **Sites** box to select all. Select **Apply**.
5. Under **Site Preferences**, find **Adyen Settings** in the list and select the checkbox in the right column. At the bottom of the page, select **Update**.

### Generate An Api And Client Key

## Step 3: Generate an API key and client key

To connect your Commerce Cloud store to the Adyen API, you need to [generate an API key in your Customer Area](#api-key-customer-area) and add it to your Salesforce Business Manager.

To authenticate requests from your payment environment, the cartridge also needs [a client key](/development-resources/client-side-authentication#page-introduction). You need to [generate a client key in your Customer Area](#client-key-customer-area) and add it your Salesforce Business Manager.

### Generate an API key in your Customer Area

1. Log in to your [Customer Area](https://ca-test.adyen.com/) and select your **Company** account.

2. Go to **Developers** > **API credentials**.

3. Select the **Payments** or **Platforms** tab, depending on your integration type.

4. Select the credential username.

5. Under **Server settings** > **Authentication** select the **API key** tab.

6. Select **Generate API key**.

7. Select the copy icon **and store your API key securely in your system.

   You cannot copy the API key again after you leave the page.

8. Select **Save changes**.

### Generate a client key in your Customer Area

1. Log in to your [Customer Area](https://ca-test.adyen.com/).
2. Go to **Developers** > **API credentials**, and select the credential username for your integration, for example **ws\@Company.\[YourCompanyAccount]**.
3. Under **Client settings** > **Authentication** select the **Client key** tab.
4. Select **Generate client key**.
5. Select the copy icon **and store your client key securely in your system.
6. Under **Add allowed origins**, enter your [domains](/development-resources/client-side-authentication#allowed-origins) and select **Add**.
7. Select **Save changes**.

After generating both keys, add them to your Salesforce Business Manager:

1. In your Salesforce Business Manager, go to **Merchant Tools** > **Site Preferences** > **Adyen settings** > **Account settings**.
2. Under **Adyen Client Key**, enter the [client key that you generated](#client-key-customer-area).
3. Under **API key of webservice**, enter the [API key that you generated](#api-key-customer-area).
4. Select **Save Changes**.

### Set Up Account Settings

## Step 4: Set up account settings

1. In your Salesforce Business Manager, go to **Merchant Tools** > **Site Preferences** > **Adyen settings** > **Account settings**, and fill the following fields:

   | Field                                                         | Description                                                                                                                                                                             |
   | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Environment**                                               | Select **Test** for setting up and testing your integration. When [going live](/plugins/salesforce-commerce-cloud/sfra/go-live-checklist), you need to change this setting to **Live**. |
   | **Adyen Client Key**                                          | The [client key that you generated](#client-key-customer-area).                                                                                                                         |
   | **Storefront Reference Architecture (SFRA) - version 6 or 7** | Only if you are using SFRA version 6 or 7, select **Enable**.                                                                                                                           |
   | **Merchant Account**                                          | The name of your [Adyen merchant account](/account/account-structure/#merchant-accounts).                                                                                               |
   | **API key of webservice**                                     | The [API key that you generated](#api-key-customer-area).                                                                                                                               |

   The **Adyen Live Prefix** and **Front-end resources region** fields are only relevant after you have set up and tested your integration, and are ready to go live. Find the information for these fields in our [go-live checklist](/plugins/salesforce-commerce-cloud/sfra/go-live-checklist/#salesforce-business-manager).

2. Select **Save Changes**.

### Set Up Webhooks

## Step 5: Set up webhooks

To inform your Commerce Cloud store of payment status changes, Adyen uses [webhooks](/development-resources/webhooks), sent as HTTP callbacks to endpoints on your server. To receive webhooks, you need to enter your server's details in the Customer Area, and add the webhooks credentials to the Salesforce Business Manager.

### 1. Set up webhooks in the Customer Area

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). 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 for a company account, include only specific merchant accounts, or exclude specific merchant accounts for your company account. |

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

   | Setting                 | Description                                                                                                                                                                                                         |
   | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **URL**                 | - **URL**: Your webhook server's URL, adding **/Adyen-Notify** at the end, for example: `https://zzft-xx.sandbox.XXXX.dx.commercecloud.salesforce.com/on/demandware.store/Sites-RefArch-Site/default/Adyen-Notify`. |
   | **Method**              | **HTTP POST**                                                                                                                                                                                                       |
   | **Encryption protocol** | **TLSv.1.3**                                                                                                                                                                                                        |

   Under **Security**, configure the following:

   | Setting                  | Description                                                                                                                                                                                                                                                                                                                                                 |
   | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | **Basic authentication** | Enter your server's username and password. You need to enter these credentials in the Salesforce Business Manager later.                                                                                                                                                                                                                                    |
   | **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 in the Salesforce Business Manager later. We strongly recommend that you use HMAC signatures to protect your server from unauthorised webhook events. |

6. Under **Events** settings, select the [event codes](/development-resources/webhooks/webhook-types/#event-codes) for this webhook. Some webhook types do not support more than one event code, so this setting does not appear.

7. If the **Additional settings** section is available, optionally select the additional information you want to receive in this webhook. Some webhook types do not support more than one event code, so this section does not appear.

8. Select **Save configuration**.

### 2. Add webhook credentials to the Salesforce Business Manager

1. In the Salesforce Business Manager, go to **Merchant tools** > **Site Preferences** > **Adyen Settings** > **Webhook settings**.
2. Enter the **Webhook username** and **Webhook password** from your [Customer Area](https://ca-test.adyen.com/).
3. Optionally, enter your **HMAC Key**.
4. Select **Save changes**.

### 3. Test webhooks

To test your webhooks:

Your server must [acknowledge webhooks with a successful HTTP response status code (like **202**)](#accept-webhooks).

1. Log in to your [Customer Area](https://ca-test.adyen.com/).
2. Select **Developers** > **Webhooks**.
3. Select the webhook to test.\
   The **Webhook details** panel includes information about the configuration. Under **Events**, you can find the configured event types that you can test for this webhook.
4. Select the edit **icon
5. Select **Test configuration**.
6. If you are on a [company account](/account/account-structure#company-account), select a **Merchant account** from the dropdown list.
7. In the **Event** dropdown list, select the [event type](/development-resources/webhooks/webhook-types#event-codes) to test webhooks for.

If the test webhook failed, you get an error message with the reason. [Troubleshoot the problem](/development-resources/webhooks/troubleshoot).

### 4. Configure scheduled jobs

Webhooks are stored in Commerce Cloud as custom object instances to be processed by scheduled jobs.

After the metadata import, a scheduled job with ID **Process** is added to the Salesforce Business Manager:  **Administration** > **Operations** > **Jobs**. This scheduled job has two steps (you can check this in the **Job Steps** tab): 

* **Process** – Processes the webhook and updates the payment status of the order.
* **Clean** –  Deletes the custom object instance, once it has been processed.

To optimize the processing of your instances, we recommend that you set the frequency of this scheduled job to 1 minute: 

1. Go to the **Schedule and History** tab for the **Process** scheduled job.
2. Set **Trigger** to **Recurring Interval**.
3. In the **Run Time** pane, set **Amount** to **1**, and **Interval** to **Minutes**. 

### Store Shopper Details

## Step 6: Store shopper details

Optional

With Adyen [tokenization](/online-payments/tokenization), you can securely store payment details of your shoppers. This allows you to offer a faster checkout experience by using their stored card.

To set this up:

1. In the Salesforce Business Manager, go to **Merchant tools** > **Site Preferences** > **Adyen Settings**.
2. In the **Additional settings** section, under **Tokenisation**, select **Enable**.
3. In the **Local payment method settings** section, under **Store shopper details: one-click**, select **Enabled** to securely store the payment details of your shoppers for later payments, where the shopper needs to enter their CVC/CVV to complete the payment.
4. Select **Save Changes**.
5. To store payment details of guest users, go to **Site Preferences** > **Order** > **Generate Customer No. for Guest Orders**, and select **Yes**.
6. Select **Apply**.

Payment details are stored in shopper accounts in the Salesforce platform. To be able to delete saved payment details from a shopper's account, you have to configure an additional setting. To set this up, contact our [Support Team](https://ca-test.adyen.com/ca/ca/contactUs/support.shtml?form=other).

### In Person Payments

## Step 7: Set up in-person payments

Optional

You can set up [endless aisle](/unified-commerce/endless-aisle/) for your physical stores to let your shoppers place ecommerce orders in your stores using payment terminals. We recommend to:

* Create a separate merchant account for ecommerce and in-person payments channels that contains the stores where you will offer endless aisle. See [set up your account for in-person payments](/point-of-sale/design-your-integration/determine-account-structure/) to learn more about account structures.
* Create a new SFCC site, and link it to the merchant account you created to process endless aisle payments. You can link only one SFCC site to for each merchant account.
* Add authentication credentials for the SFCC site you created for endless aisle payments. This lets you track the store employees that are using the feature.

To process payments in your Commerce Cloud stores using payment terminals:

1. [Enable in-person payments](#enable-in-person-payments) in your Salesforce Business Manager.
2. [Configure services](#configure-services) in your Salesforce Business Manager.
3. [Create a Store ID](#create-store-id) in your Adyen Customer Area.
4. [Enable Terminal API](#enable-terminal-api-for-stores) for the store you created in your Salesforce Business Manager.

### Enable in-person payments

1. In the Salesforce Business Manager, go to **Merchant Tools** > **Ordering** > **Payment methods**.
2. Select **AdyenPOS**.
3. Select **Yes** in the **Enabled** column.
4. From the **Payment Processor** drop-down in the **AdyenPOS Details** section, select **Adyen\_POS**.

### Configure services

1. In the Salesforce Business Manager, go to **Administration** > **Operations** > **Services**.
2. Under **Services**, select **AdyenPosPayment**.
3. In the **Name** box, enter **AdyenPosPayment**.
4. In the **Profile** dropdown, select **AdyenPOS**.
5. Under **Profiles**, select **AdyenPOS**.
6. In the **Connection Timeout (ms)** box, enter **100.000**.
7. Make sure that the **Enable Circuit Breaker** checkbox is not selected.

### Create Store ID

In your Adyen Customer Area, [create a Store ID](/point-of-sale/design-your-integration/determine-account-structure#create-stores).

You can create multiple store IDs if you are going to offer endless aisle in more than one store.

### Enable Terminal API for your stores

1. In the Salesforce Business Manager, go to **Merchant tools** > **Site Preferences** > **Adyen Settings** > **In-person payments settings**.
2. Select **StoreID for Terminal API**, and select the ID for the [store you created](#create-store-id).

If you add new stores in your Customer Area later, you must follow the steps again to enable in-person payments for the new stores you created.

### Donations

## Step 8: Set up donations with Adyen Giving

Optional

Adyen Giving is enabled by default in your Salesforce Business Manager settings.

If a [donation campaign](/online-payments/donations/#managing-donation-campaigns) is set up and active in your [test Customer Area](https://ca-test.adyen.com/) merchant account, shoppers can donate when they use a payment method that supports donations.

### Test and go live with Giving

Test your integration by doing the following:

1. [Create and activate a test donation campaign](/online-payments/donations/testing/#create-and-activate-a-test-donation-campaign).
2. Use our [test cards](/online-payments/donations/testing/#test-cards) to make a donation.
3. Get the [**DONATION** webhook](/development-resources/webhooks/webhook-types#other-webhooks) for the donation.

When you are ready to go live with Giving, enable the [Adyen Giving merchant webhook](/development-resources/webhooks/webhook-types#other-webhooks), and [create and activate a live donation campaign](/online-payments/donations/testing/#create-and-activate-a-live-donation-campaign) in your [live Customer Area](https://ca-live.adyen.com/).

When you make live donations, you can verify the outcome by either:

* Finding the donation in a [Giving report or dashboard](/reporting/monitor-donations).
* Getting the [**DONATION** webhook](/development-resources/webhooks/webhook-types#other-webhooks) for the donation.

### Risk Management

## Step 9: Use risk management features

Optional

Our cartridge gives you access to various [risk management](/risk-management/) features that Adyen offers, to let you detect, handle, mitigate, analyze and monitor fraud.

### Basket fields

You can create [custom risk rules](/risk-management/configure-manual-risk/configure-custom-risk-rules) to influence the risk score of a transaction. Custom risk rules are a [RevenueProtect](/risk-management/configure-manual-risk?tab=1#risk-rule-types) premium feature.

You can use Basket fields for [custom risk rules](/risk-management/configure-custom-risk-rules). To include the Basket fields in your payment request:

1. In the Business Manager, go to **Merchant tools** > **Site Preferences** > **Adyen Settings** > **Additional Settings**.
2. Under **Basket fields**, select **Enable**.
3. Select **Save Changes**.

### Case management

For an extra layer of fraud protection, you may want to manually review a transaction before it is captured. A transaction can be sent to [case management](/risk-management/case-management) for manual review when it reaches a certain risk score, or triggers a specific risk rule.

You have to enable [RevenueProtect](/risk-management) premium, and configure manual review settings to use case management.

Set up case management in the Adyen Customer Area:

1. Log in to your Adyen [Customer Area](https://ca-test.adyen.com/) with your company account.
2. [Assign roles](/risk-management/case-management/#set-roles) to users for manual review.
3. [Set a trigger for manual review](/risk-management/case-management/#set-triggers).
4. [Configure actions and webhooks](/risk-management/case-management#case-management-settings).\
   These are the recommended **Case management behavior** settings for the cartridge:\
   **Accept**: Select **None** and then select **Send notification**.\
   **Reject**: Select **Cancel** and then select **Send notification**.\
   **Expire**: Select **Cancel**, and then select **Reject** under **Notification**.
5. Select **Save configuration**.

### Data collection

The cartridge [collects risk data](/risk-management/fraud-data-collection/#data-collection-components) on the checkout page and sends it to Adyen by default.

In addition to the data that you send when the shopper checks out, you can also optionally collect data to on any of your [Salesforce ISML templates](https://developer.salesforce.com/docs/commerce/b2c-commerce/guide/b2c-working-with-templates.html) that generate your storefront pages to detect fraud outside of your checkout page.

Refer to [Collect additional data outside of the checkout page](/risk-management/fraud-data-collection/#collect-additional-data) to set up data collection on any of your web pages.

### Level 2 3 Data

## Step 10: Send Level 2/3 data for cards

Optional

Sending Level 2 or Level 3 Enhanced Scheme Data allows you to cut your interchange rates on US domestic transactions by up to 90 basis points. At the same time, your shoppers will see additional information about their purchase on their credit card statement.

Not all businesses can submit Level 2/3 data. Refer to [What is Enhanced Scheme Data?](https://help.adyen.com/knowledge/ecommerce-integrations/integrations-basics/enhanced-scheme-data) for more information.

Sending Level 2/3 data is supported from [v20.1.3](https://github.com/Adyen/adyen-salesforce-commerce-cloud/releases/tag/20.1.3) of the cartridge.

To send Level 2/3 data:

1. In the Salesforce Business Manager, go to **Merchant tools** > **Site Preferences** > **Adyen Settings** > **Additional settings**.
2. Under **Level 2/3 Data**, select **Enabled**.
3. Under **Commodity code**, enter the [UNSPSC commodity code](https://www.unspsc.org/search-code) for your products or services.
4. Select **Save Changes**.

### Add Si Info

## Step 11: Add system integrator info

Optional

If your integration with Adyen is built by a system integrator let us know their name, so that we can offer you better support.

Adding system integrator info is supported from [v20.1.3](https://github.com/Adyen/adyen-salesforce-commerce-cloud/releases/tag/20.1.3) of the cartridge.

1. In the Salesforce Business Manager, go to **Merchant tools** > **Site Preferences** > **Adyen Settings** > **Additional Settings**.
2. Under **System integrator**, enter the name of your system integrator.

### Configure Localization

## Step 12: Configure localization

Optional

Localization is supported in the SFCC cartridge. You can add translations for multiple locales by doing the following.

1. Open the translation file: `int_adyen_SFRA/config/adyenTranslations.js`.

2. For each key-value pair, add your translation. Your checkout form uses the translations for each corresponding locale.

   * You must not change the keys.
   * Refer to our [`en-US` translations file](https://github.com/Adyen/adyen-web/blob/main/packages/server/translations/en-US.json) to make sure that your keys are correct.

To support multiple locales, you must add the translation data for each locale within the `adyenTranslations.js` file.

Below is an example of how your translations file could look like:

**Example adyenTranslations.js file**

```js
module.exports = {
 'en-US': {
   payButton: 'YOUR_TRANSLATION_STRING',
 },
};
```

### Cartridge Analytics

## Step 13: Configure performance analytics

Optional

We use anonymized usage data to monitor system performance and ensure cartridge stability. This does not impact checkout performance, and no personal or payment data is included in these analytics.

To enable analytics, do the following.

1. In your Salesforce Business Manager, go to **Adyen Settings** > **Local Payment Method settings** > **Adyen Plugin Performance Monitoring**.
2. Select **Enable**, and save your settings.

This feature collects anonymized information about the cartridge health and reports unexpected failures to Adyen. When enabled, a scheduled job with ID **ProcessAnalytics** is added to the Salesforce Business Manager. [Configure this scheduled job](#configure-scheduled-jobs).

Disabling analytics does not impact your access to core features, but it can limit our ability to detect issues or provide tailored support.

### Csc Orders

## Step 14: Accept Customer Service Center orders

Use [Adyen payment links](/unified-commerce/pay-by-link) to process orders in the Salesforce Customer Service Center (CSC). This allows your customer service agents to create orders on behalf of shoppers and provide a secure link for payment.

Customer Service Center orders are enabled by default, to place an order:

1. In your Salesforce Business Manager, go to **Merchant Tools** > **Ordering** > **Customer Service Center**.

2. Complete all required order details for the shopper, select the option to authorize the full order amount and submit the order.

3. In the pending payment pop-up that appears, locate the generated payment link and share it with your shopper.

   The pending payment error message indicates that a pending payment needs to be fulfilled before the order can be processed. You can close the error dialogue after you have shared the link with the shopper.

After your shopper completes the payment, the order will be processed. To check the status of a payment, you can [view the payment link in your Customer Area](/unified-commerce/pay-by-link/create-payment-links/customer-area#view-links). You can also find the payment link in the **Order Notes** section in the Salesforce Business Manager.

![](/user/pages/filters/checkout-web-component/github/github-mark.png)

## Next steps

[required](/plugins/salesforce-commerce-cloud/sfra/set-up-payment-methods)

[Set up payment methods](/plugins/salesforce-commerce-cloud/sfra/set-up-payment-methods)

[Configure the payment methods that you want to offer in your Salesforce Commerce Cloud store.](/plugins/salesforce-commerce-cloud/sfra/set-up-payment-methods)

[required](/plugins/salesforce-commerce-cloud/sfra/go-live-checklist)

[Configure your live account](/plugins/salesforce-commerce-cloud/sfra/go-live-checklist)

[Follow this checklist before you start accepting live payments.](/plugins/salesforce-commerce-cloud/sfra/go-live-checklist)
