PaymentMethods container

Use the PaymentMethods container to manage and display the available payment methods during the checkout process. Configuration options:

• Set the payment method automatically or manually (starting without a selected payment method)
• Show an icon beside of the label
• Display or hide the label
• Provide a specific handler to render the payment method

PaymentMethods configurations

The PaymentMethods container provides the following configuration options:

Option	Type	Req?	Description
displayTitle (*)	boolean	No	Displays the container title (default value is true).
active	boolean	No	Activates/deactivates the container (default value is true).
autoSync	boolean	No	Synchronizes/does not synchronize the container local state with the backend (default value is true).
onCartSyncError	function	No	A function that takes a PaymentMethod object and an error as arguments. It is called when the setPaymentMethodOnCart() API throws an error when a payment method is selected to be stored to the backend.
onSelectionChange	function	No	A function that takes a PaymentMethod object as an argument. It is called when a payment method is selected.
slots	object	No	Object with a list of configurations for existing payment methods.
UIComponentType	string	No	String with the UI component type to be used as selector (default value is 'ToggleButton').

(*) Properties inherited from TitleProps

These configuration options are implementing the PaymentMethodsProps interface:

PaymentMethodsProps interface

The PaymentMethods container receives an object as parameter which implements the PaymentMethodsProps interface with the following properties:

export type UIComponentType = 'ToggleButton' | 'RadioButton';

interface CartSyncError {
  method: PaymentMethod;
  error: Error;
}

export interface PaymentMethodsProps extends HTMLAttributes<HTMLDivElement>, TitleProps {
  active?: boolean;
  autoSync?: boolean;
  onCartSyncError?: (error: CartSyncError) => void;
  onSelectionChange?: (method: PaymentMethod) => void;
  slots?: {
    Methods?: PaymentMethodsSlot;
  } & TitleProps['slots'];
  UIComponentType?: UIComponentType;
}

• The displayTitle (*) property is inherited from the TitleProps interface. It is used to determine whether to display the title.

• Set the active property to true to have the container in reactive mode (it is visible and responds to system events). If it is set to false, the container is deactivated (it does not subscribe to system events and is not rendered).

• Set the autoSync property to true to automatically synchronize the container state changes with the backend via API calls. If it is set to false the container does not automatically synchronize its state, but still maintains local updates.

• The onCartSyncError property is a handler used to perform actions called when a payment method is selected and the setPaymentMethodOnCart() API throws an error. It could be used in the integration layer by the merchant to show errors.

• The onSelectionChange property is a handler used to perform actions called when a payment method is selected.

• The UIComponentType property is a string containing the name of the UI component type to be used as a selector for each payment method. The available UI components are: ToggleButton or RadioButton.

• The slots property is an object containing the following properties:

  • Use the Title (*) property to render a custom title. This property is inherited from TitleProps interface.
  • The Methods property is an object which implements the PaymentMethodsSlot interface:

  export interface PaymentMethodsSlot {
    [code: string]: PaymentMethodConfig;
  }

  It consists on a list of payment method codes providing a set of configurations to customize the payment method. Each payment method will have its own set of configurations implementing the PaymentMethodConfig interface:

  export type SlotProps<T = any> = (
    ctx: T & DefaultSlotContext<T>,
    element: HTMLDivElement | null
  ) => Promise<void> | void;
  
  export interface PaymentMethodRenderCtx {
    cartId: string;
    replaceHTML: (domElement: HTMLElement) => void;
  }
  
  export interface PaymentMethodConfig {
    displayLabel?: boolean;
    enabled?: boolean;
    icon?: string;
    autoSync?: boolean;
    render?: SlotProps<PaymentMethodRenderCtx>;
  }

  • The PaymentMethodConfig interface is composed by:
    • The displayLabel configuration hides the payment method label (for instance, if you only want to display the icon).
    • The enabled configuration allows merchants to individually hide payment methods filtering them from the available payment methods list (for instance, it is useful when a payment provider has enabled a payment method in the backend, which is configured with more than one payment option and you don’t want to display one of them).
    • The icon configuration specifies the name of the icon to be shown beside of the label. The icon name must exist within the list of available icons defined on Elsie.
    • The autoSync configuration sets the payment method automatically when it is selected. Only if a payment method is specifically set to false, the container will not automatically set the payment method to the cart when selected (for instance, if a payment method needs more information obtained during the place order action). This specific configuration has more priority than the generic one declared on the PaymentMethodsProps. In case this configuration is not provided, then it will be used the generic autoSync property.
    • The render configuration is a handler used to render and configure the payment method.

Example 1: Render the available payment methods with callbacks

The following example renders the PaymentMethods container on a checkout page, displaying the available payment methods in the element with the class checkout__payment-methods. It includes configurations to show a message if the chosen payment method is Credit Card, and show an error message in case there was an issue saving the selected payment method to the backend.

// Checkout Dropin
import PaymentMethods from '@dropins/storefront-checkout/containers/PaymentMethods.js';
import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';

// Payment Services Dropin
import { PaymentMethodCode } from '@dropins/storefront-payment-services/api.js';

const $paymentMethods = checkoutFragment.querySelector(
  '.checkout__payment-methods',
);

CheckoutProvider.render(PaymentMethods, {
  onCartSyncError: ({ method, error }) => {
    const paymentMsg = document.createElement('div');
    paymentMsg.style.color = 'red';
    paymentMsg.innerText = `Error selecting the Payment Method ${method.code} ${method.title}: ${error.message}`;
    $paymentMethods.appendChild(paymentMsg);
  },
  onSelectionChange: (method) => {
    if (method.code === PaymentMethodCode.CREDIT_CARD) {
      const paymentMsg = document.createElement('div');
      paymentMsg.innerText = 'Payment method not available for the country selected';
      $paymentMethods.appendChild(paymentMsg);
    }
  },
})($paymentMethods),

Example 2: Render with the displayLabel and icon configurations

The following example renders the PaymentMethods container on a checkout page, displaying the available payment methods in the element with the class checkout__payment-methods, providing an icon for checkmo and banktransfer, and hiding the label for banktransfer.

// Checkout Dropin
import PaymentMethods from '@dropins/storefront-checkout/containers/PaymentMethods.js';
import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';

const $paymentMethods = checkoutFragment.querySelector(
  '.checkout__payment-methods',
);

CheckoutProvider.render(PaymentMethods, {
  slots: {
    Methods: {
      checkmo: {
        icon: 'Wallet',
        render: (ctx) => {
          const $content = document.createElement('div');

          $content.innerText = 'Pay later with Checkmo config handler';
          ctx.replaceHTML($content);
        },
      },
      banktransfer: {
        displayLabel: false,
        icon: 'Card',
      },
    },
  },
})($paymentMethods),

Example 3: Render with the autoSync and render configurations

The following example renders the PaymentMethods container on a checkout page, displaying the available payment methods in the element with the class checkout__payment-methods, providing a specific handler for braintree payment method indicating it cannot be set to the cart when selected.

// Checkout Dropin
import PaymentMethods from '@dropins/storefront-checkout/containers/PaymentMethods.js';
import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';

import 'https://js.braintreegateway.com/web/dropin/1.43.0/js/dropin.min.js';

const $paymentMethods = checkoutFragment.querySelector(
  '.checkout__payment-methods',
);

let braintreeInstance;

CheckoutProvider.render(PaymentMethods, {
  slots: {
    Methods: {
      braintree: {
        autoSync: false,
        render: async (ctx) => {
          const container = document.createElement('div');

          window.braintree.dropin.create({
            authorization: 'sandbox_cstz6tw9_sbj9bzvx2ngq77n4',
            container,
          }, (err, dropinInstance) => {
            if (err) {
              console.error(err);
            }

            braintreeInstance = dropinInstance;
          });

          ctx.replaceHTML(container);
        },
      },
    },
  },
})($paymentMethods),

Example 4: Render with the enabled configurations

The following example renders the PaymentMethods container on a checkout page, displaying the available payment methods in the element with the class checkout__payment-methods, providing a specific handler for the credit card payment option but disabling the rest of payment options from PaymentServices payment method.

// Checkout Dropin
import PaymentMethods from '@dropins/storefront-checkout/containers/PaymentMethods.js';
import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';

// Payment Services Dropin
import CreditCard from '@dropins/storefront-payment-services/containers/CreditCard.js';
import { render as PaymentServicesProvider } from '@dropins/storefront-payment-services/render.js';
import { PaymentMethodCode } from '@dropins/storefront-payment-services/api.js';

const $paymentMethods = checkoutFragment.querySelector(
  '.checkout__payment-methods',
);

// Container and component references
const creditCardFormRef = { current: null };

// Adobe Commerce GraphQL endpoint
const commerceCoreEndpoint = await getConfigValue('commerce-core-endpoint');

CheckoutProvider.render(PaymentMethods, {
  slots: {
    Methods: {
      [PaymentMethodCode.CREDIT_CARD]: {
        render: (ctx) => {
          const $content = document.createElement('div');

          PaymentServicesProvider.render(CreditCard, {
            apiUrl: commerceCoreEndpoint,
            getCustomerToken: getUserTokenCookie,
            getCartId: () => ctx.cartId,
            creditCardFormRef,
          })($content);

          ctx.replaceHTML($content);
        },
      },
      [PaymentMethodCode.SMART_BUTTONS]: {
        enabled: false,
      },
      [PaymentMethodCode.APPLE_PAY]: {
        enabled: false,
      },
      [PaymentMethodCode.GOOGLE_PAY]: {
        enabled: false,
      },
      [PaymentMethodCode.VAULT]: {
        enabled: false,
      },
    },
  },
})($paymentMethods),

Example 5: Render with custom title and radio button as selector

The following example renders the PaymentMethods container on a checkout page to display a custom title and radio buttons instead of toggle buttons for selecting the payment options.

// Checkout Dropin
import PaymentMethods from '@dropins/storefront-checkout/containers/PaymentMethods.js';
import { render as CheckoutProvider } from '@dropins/storefront-checkout/render.js';

const $paymentMethods = checkoutFragment.querySelector(
  '.checkout__payment-methods',
);

CheckoutProvider.render(PaymentMethods, {
  UIComponentType: 'RadioButton',
  displayTitle: true,
  slots: {
    Title: (ctx) => {
      const content = document.createElement('div');
      content.innerText = 'Custom title';
      ctx.replaceWith(content);
    },
  },
})($paymentMethods),