# How to Customize the Display and Configuration of Payment Methods in Adyen Salesforce Commerce Cloud

> Customize Adyen Salesforce Commerce Cloud payment method display and configuration. Edit backend logic and frontend templates to tailor your checkout experience.

- Repository: [Adyen/adyen-salesforce-commerce-cloud](https://github.com/adyen/adyen-salesforce-commerce-cloud)
- Tags: how-to-guide
- Published: 2026-02-23

---

**You can customize payment method display and configuration in the Adyen Salesforce Commerce Cloud cartridge by editing the configuration layer for titles and descriptions, modifying the backend controller for filtering logic, and overriding the client-side rendering scripts or ISML templates for visual presentation.**

The adyen/adyen-salesforce-commerce-cloud repository provides a modular SFRA architecture that separates payment method data from presentation across four distinct layers. Understanding how to customize the display and configuration of payment methods requires working with specific configuration files, server-side scripts, client-side JavaScript modules, and ISML templates. This guide maps the exact file paths and override patterns implemented in the cartridge to help you tailor the checkout experience without breaking core functionality.

## Architecture Overview

The cartridge isolates payment method concerns into four layers, allowing you to modify specific aspects without affecting others.

### Configuration Layer

This layer defines the set of supported payment method identifiers, their titles, and optional descriptions. Key files include [`src/cartridges/int_adyen_SFRA/cartridge/adyen/config/constants.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/config/constants.js) which exports the `PAYMENTMETHODS` enum, [`src/cartridges/int_adyen_SFRA/cartridge/config/adyenPaymentMethodTitles.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/config/adyenPaymentMethodTitles.js) for locale-specific display names, and [`src/cartridges/int_adyen_SFRA/cartridge/adyen/config/paymentMethodDescriptions.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/config/paymentMethodDescriptions.js) for supplementary text.

### Backend Service Layer

The [`getCheckoutPaymentMethods.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/getCheckoutPaymentMethods.js) script at [`src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/payments/getCheckoutPaymentMethods.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/payments/getCheckoutPaymentMethods.js) calls Adyen's Checkout API and enriches the JSON payload with the titles and definitions from the configuration layer. This server-side controller determines which methods are available to the shopper based on merchant account settings and custom business logic.

### Frontend Rendering Layer

Client-side logic resides in [`src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/renderPaymentMethod.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/app_adyen_SFRA/cartridge/client/default/js/adyen/checkout/renderPaymentMethod.js). This module consumes the backend JSON, constructs the radio button list, injects images and titles, appends description paragraphs, and mounts Adyen Web Components into the DOM.

### ISML Template Layer

Static scaffolding is provided by `src/cartridges/app_adyen_SFRA/cartridge/templates/default/checkout/billing/paymentOptions.isml`. This template defines the container structure, hidden form fields, and CSS hooks that the JavaScript layer targets when injecting dynamic content.

## Customization Examples

### Add a Custom Title for an Existing Method

To override the display label for a payment method like Fastlane, edit the locale-specific configuration in [`adyenPaymentMethodTitles.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenPaymentMethodTitles.js).

```javascript
// src/cartridges/int_adyen_SFRA/cartridge/config/adyenPaymentMethodTitles.js
module.exports = {
  en_US: {
    fastlane: 'My Fastlane Checkout',   // Custom label
    // Retain existing entries
  },
};

```

The front-end reads this map during `renderCheckout` using the pattern `adyenPaymentMethodTitles?.[locale]?.[pm.type]`, automatically displaying your custom label in the radio list.

### Display a Description Underneath a Payment Method

Add supplementary text by editing [`paymentMethodDescriptions.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/paymentMethodDescriptions.js). The frontend injects this into a paragraph element when present.

```javascript
// src/cartridges/int_adyen_SFRA/cartridge/adyen/config/paymentMethodDescriptions.js
module.exports = {
  ideal: 'Fast, secure Dutch payment (iDEAL).',
  paypal: 'Pay with your PayPal account.',
  fastlane: 'Instant checkout for returning customers.',
};

```

In [`renderPaymentMethod.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/renderPaymentMethod.js), the `getListContents` function constructs the list item markup and appends `<p>${description}</p>` when the description value is truthy.

### Override HTML for Custom Icons

To replace the default image tag with a custom SVG for a specific method, create a client-side module that wraps the original renderer.

```javascript
// custom/adyen/checkout/customRender.js
import { renderPaymentMethod as originalRender } from '*/cartridge/client/default/js/adyen/checkout/renderPaymentMethod';

export async function renderPaymentMethod(paymentMethod, isStored, path, description, title) {
  const canRender = await originalRender(paymentMethod, isStored, path, description, title);
  if (canRender && paymentMethod.type === 'paypal') {
    const img = document.querySelector(`#lb_${paymentMethod.type} img`);
    if (img) img.src = '/images/custom/paypal.svg';
  }
  return canRender;
}

```

Update the import in [`checkout/adyenCheckout.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/checkout/adyenCheckout.js) to reference your custom function. The cartridge's AMD loader will prioritize your override while maintaining the original logic for all other methods.

### Modify the ISML Container Layout

Adjust the static template to add CSS classes or structural changes. Edit `paymentOptions.isml` to inject custom classes into the list container.

```html
<!-- src/cartridges/app_adyen_SFRA/cartridge/templates/default/checkout/billing/paymentOptions.isml -->
<ul class="nav nav-tabs nav-fill payment-options custom-payment-list" id="paymentOptions" role="tablist">

```

The frontend attaches the dynamic component list to the `paymentMethodsList` element inside the credit card selection container. Targeting `.custom-payment-list` in your CSS applies styles without modifying JavaScript logic.

### Filter Payment Methods by Country

Implement business rules in the backend controller to exclude specific methods based on geographic or other criteria. In [`getCheckoutPaymentMethods.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/getCheckoutPaymentMethods.js), filter the array before returning it to the frontend.

```javascript
// src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/payments/getCheckoutPaymentMethods.js
const filteredByCountry = paymentMethods.paymentMethods.filter(pm => {
  if (countryCode === 'DE' && pm.type === constants.PAYMENTMETHODS.AMAZONPAY) {
    return false; // Hide Amazon Pay for Germany
  }
  return true;
});

```

Update the response payload to use `paymentMethods: filteredByCountry`. The UI automatically hides excluded methods since they are omitted from the JSON feed.

## Summary

- **Configuration files** ([`adyenPaymentMethodTitles.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/adyenPaymentMethodTitles.js), [`paymentMethodDescriptions.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/paymentMethodDescriptions.js), [`constants.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/constants.js)) control what payment methods are available and how they are labeled.
- **Backend service** ([`getCheckoutPaymentMethods.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/getCheckoutPaymentMethods.js)) determines which methods reach the frontend and can filter them based on business logic.
- **Frontend rendering** ([`renderPaymentMethod.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/renderPaymentMethod.js)) constructs the DOM elements and mounts Adyen components.
- **ISML templates** (`paymentOptions.isml`) provide the structural container and CSS hooks.
- You can override specific methods, replace icons, modify layouts, or filter availability without modifying core cartridge files by leveraging the modular architecture and AMD module patterns.

## Frequently Asked Questions

### How do I change the display name of a payment method in the checkout?

Edit [`src/cartridges/int_adyen_SFRA/cartridge/config/adyenPaymentMethodTitles.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/config/adyenPaymentMethodTitles.js) and add or modify the locale-specific entry for that payment method type. The frontend automatically pulls the title from this configuration map when rendering the payment method list.

### Where is the logic that determines which payment methods appear to the shopper?

The server-side logic resides in [`src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/payments/getCheckoutPaymentMethods.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/scripts/payments/getCheckoutPaymentMethods.js). This script queries Adyen's API and can apply additional filters, such as removing specific methods for certain countries or customer groups, before sending the JSON payload to the browser.

### Can I customize the icons or HTML structure of individual payment methods?

Yes. Create a custom client-side module that imports the original `renderPaymentMethod` function from [`renderPaymentMethod.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/renderPaymentMethod.js), calls it to preserve default behavior, then manipulates the DOM elements (such as replacing image sources) based on the `paymentMethod.type`. Update your main checkout script to import this wrapper instead of the original.

### How do I add helper text or descriptions below payment method labels?

Add entries to [`src/cartridges/int_adyen_SFRA/cartridge/adyen/config/paymentMethodDescriptions.js`](https://github.com/adyen/adyen-salesforce-commerce-cloud/blob/main/src/cartridges/int_adyen_SFRA/cartridge/adyen/config/paymentMethodDescriptions.js). The `renderPaymentMethod` function checks for the presence of a description and injects a paragraph element containing your text directly beneath the payment method title in the radio list.