---
title: "Customization guide"
description: "Learn how to customize your checkout."
url: "https://docs.adyen.com/plugins/salesforce-commerce-cloud/sfra/customization-guide"
source_url: "https://docs.adyen.com/plugins/salesforce-commerce-cloud/sfra/customization-guide.md"
canonical: "https://docs.adyen.com/plugins/salesforce-commerce-cloud/sfra/customization-guide"
last_modified: "2025-06-19T15:36:00+02:00"
language: "en"
---

# Customization guide

Learn how to customize your checkout.

[View source](/plugins/salesforce-commerce-cloud/sfra/customization-guide.md)

##### Read more

Read more about customizing SFRA cartridges in [Salesforce documentation](https://developer.salesforce.com/docs/commerce/sfra/guide/b2c-customizing-sfra.html).

You can customize your shoppers' checkout experience by customizing checkout flows or payment methods. Custom code that you add in a separate cartridge will not be transpiled and will be preserved when you upgrade to a new cartridge version.

When you add custom code in a separate cartridge, you can continue to receive cartridge support from Adyen for [supported versions](/plugins/salesforce-commerce-cloud/#support-levels) . If you customize the default Adyen cartridge, we may be unable to provide cartridge support, and it becomes harder to upgrade and troubleshoot your integration.

Therefore, we strongly discourage making changes directly to the`/src/cartridges` directory. If you have already applied customizations to these directories, we recommend to [extract your custom code from the default cartridge](https://docs.adyen.com/plugins/salesforce-commerce-cloud/sfra/customization-guide/#extract-custom-code-from-the-default-cartridge)

There are two types of customizations you can apply:

* [Adding your custom code in a separate cartridge](#add-custom-code-in-a-separate-cartridge) to customize checkout flows.
* [Customizing payment methods](#customize-payment-methods) by adding custom configuration.
* [Implement your own pre-authorization checks](#implement-pre-authorization-checks)

## Add custom code in a separate cartridge

You can customize your integration by adding a separate cartridge before the Adyen cartridge to override default configurations.

This setup is available by default on [v23.2.1](https://github.com/Adyen/adyen-salesforce-commerce-cloud/releases/tag/23.2.1) or later, and enables you to temporarily remove custom code when upgrading or troubleshooting your integration.

To add custom code in a separate cartridge:

1. Create a new cartridge in your **/src/cartridges** directory and name it, for example: **int\_custom\_cartridge**.

2. Add your custom code to the new cartridge and update metadata if needed

3. Update the `name` property in the **package.json** file to the name you chose, for example **int\_custom\_cartridge**.

4. Run the following command to make sure all unit tests are passing:
   ```bash
   npm install
   ```

5. Run the following command:
   ```bash
   npm run build
   ```

6. Add the new cartridge to your [cartridge path](/plugins/salesforce-commerce-cloud/sfra/set-up-the-cartridge?plugin=Salesforce%20SFRA\&integration=cartridge#step-1-set-up-the-cartridge-path):

   1. Go to **Administration** > **Sites** > **Manage Sites** > **\[yourSite]** > **Settings**.
   2. In the **Cartridges** box, add the new cartridge before the Adyen cartridges.
   3. Select **Apply**.

7. Modify or add end-to-end tests as needed.

8. Run the end-to-end tests to make sure your custom code works correctly.

Watch how to customize your SFCC cartridge:

Embedded video (Vimeo): <https://player.vimeo.com/video/843123373>

## Extract custom code from the default cartridge

If you have customized the [source directory](#customize-the-source-directory) or the [cartridges directory](#customize-the-cartridges-directory), you can extract your custom code in a separate cartridge later to:

* [Upgrade your integration](/plugins/salesforce-commerce-cloud/sfra/upgrade/#customized-integration).
* Switch to the [recommended way to customize](#add-custom-code-in-a-separate-cartridge).

To extract your custom code:

1. In our [GitHub releases](https://github.com/Adyen/adyen-salesforce-commerce-cloud/releases), find the version that you currently use.

2. In your local project, locate your custom code. Your custom code may be in the `/src`, `/cartridges` or both directories.

3. Separate your custom code from the default cartridge code:

   1. Clone the public release with your current cartridge version into your local project:
      ```bash
      git checkout tag/YOUR_CURRENT_CARTRIDGE_VERSION
      ```

   2. Make sure that your main project has two nested folders for the cloned default Adyen cartridge and for your customized integration.

   3. Run the following command in your terminal to compare the Adyen default cartridge code and your integration code to locate all the file changes:

      ```bash
      diff -r FOLDER_1_NAME FOLDER_2_NAME
      ```

      If you are using Windows, use the following command instead:

      ```powershell
      comp /r FOLDER_1_NAME FOLDER_2_NAME
      ```

      Alternatively, to view the file changes in human readable format instead of machine readable format, you can use diff tools that are available on GitHub.

   4. Extract the custom code that you located.

4. [Add the custom code in a separate cartridge](#add-custom-code-in-a-separate-cartridge).

## Customize payment methods

The Adyen Salesforce Commerce Cloud (SFCC) checkout configuration integrates Adyen's wide range of payment methods seamlessly into Salesforce Commerce Cloud using the Storefront Reference Architecture (SFRA).

Each payment method can be configured individually, so that you can customize the checkout flow based on your needs. The payment methods that you can add custom configuration to are:

* Amazon Pay

* Apple Pay

* Bancontact (BCMC)

* Boleto

* Card (credit/debit)

  * Stored Cards
  * Click to Pay

* Cash App

* Gift Cards

* Google Pay

* Klarna

* PayPal

* UPI (India)

### Featured configuration options

Each payment method can be customized with the following featured configuration parameters.

| Parameter       | Description                                                                         |
| --------------- | ----------------------------------------------------------------------------------- |
| `showPayButton` | Set to **false** to hide the payment button in the checkout form.                   |
| `environment`   | The front-end environment. Possible values: - **test** - **live**                   |
| `onSubmit`      | Called when the shopper selects the pay button to submit their payment information. |
| `onError`       | Called when an error occurs during the payment.                                     |
| `onAuthorised`  | Called when the payment is successfully authorized.                                 |

For the full list of configuration options for each payment method, go to the Web Component page for the [payment method](/payment-methods). For example, for card, go to the [Card Web Component page](/payment-methods/cards/web-component).

You can use these configuration options to optimize usability and compliance based on region, shopper preferences, or business rules.

### How to customize

To customize the configuration for a payment method:

1. In the cartridge, go to: `/src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/paymentMethodsConfiguration`.
2. Open the corresponding file for the payment method. For example: `card.js` for card, `paypal.js` for PayPal, or `klarna.js` for Klarna.
3. Edit the configuration.

If applicable:

4. Rebuild your code.
5. Deploy the changes to your Salesforce Commerce Cloud environment.

The following example shows configuration for the card payment method.

**Example card configuration**

```javascript
const cardConfiguration = {
  hasHolderName: true,
  holderNameRequired: false,
  enableStoreDetails: true,
  clickToPayConfiguration:  {
                // Settings for Click to Pay.
            },
  exposeExpiryDate: true,
  onChange: function(state, component) {
                // Handle the state change.
            },
  onSubmit: function(state, component) {
                // Handle submitting the payment details.
            },
  onFieldValid: function(fieldType, isValid) {
                // Field validation.
            },
  onBrand: function(brandObject) {
                // Detect the card brand.
            }
};
```

## Implement pre-authorization checks

On v25.4.0 or later versions of the cartridge, you can implement your own pre-authorization checks. This lets you, for example, to make a request to your third-party risk provider for risk checks before the Adyen cartridge makes a [/payments](https://docs.adyen.com/api-explorer/Checkout/latest/post/payments) request to authorize the payment.

To add your own pre-authorization logic:

1. In the cartridge, go to `/src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/hooks/payment/preAuthorizationHandling.js`.

2. Using the `app.payment.pre.auth` pre-authorization hook, add your custom logic.

3. To let the cartridge proceed or stop with payment authorization after your checks:

   * Return `error`: **true** to prevent the cartridge from making the payment request if your pre-authorization checks fail.
   * Return `error`: **false** to proceed with the payment request if your pre-authorization checks succeed.

## Troubleshoot common issues

* Payment method display issues:

  * Make sure that you set `showPayButton`: **true**.
  * Make sure that the payment method is enabled in [live Customer Area](https://ca-live.adyen.com/).

* API errors: make sure that your Adyen API credentials are configured correctly in your SFCC Business Manager.

* Customization issues: make sure that configuration files have been modified and deployed correctly.

## See also

* [Troubleshooting your integration](/plugins/salesforce-commerce-cloud/sfra/troubleshooting)
* [Upgrade your cartridge](/plugins/salesforce-commerce-cloud/sfra/upgrade)
