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

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 which exports the PAYMENTMETHODS enum, 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 for supplementary text.

Backend Service Layer

The getCheckoutPaymentMethods.js script at 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. 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.

// 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. The frontend injects this into a paragraph element when present.

// 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, 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.

// 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 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.

<!-- 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, filter the array before returning it to the frontend.

// 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, paymentMethodDescriptions.js, constants.js) control what payment methods are available and how they are labeled.
• Backend service (getCheckoutPaymentMethods.js) determines which methods reach the frontend and can filter them based on business logic.
• Frontend rendering (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 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. 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, 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}