Skip to main content

Widget Interfaces

The Checkout widget provides multiple interfaces, each designed to handle a specific part of the payment UI.

Use these interfaces to split the UI across your page and create a seamless integration with your design system.

Good to know

You can create multiple widget instances with different interfaces to achieve complex layouts. For example, you can insert custom elements between the selection and form widgets, or separate gift cards and credit cards into distinct widget instances.

Payment Widget​

The fastest way to render a complete payment flow. This widget combines both the SELECTION and FORM interfaces into a single, unified component.

Widgets mount to a container using the HTML id attribute. The examples below assume a DOM element with the id widget-payment.

const widget = await manager.createWidget({
  interface: "PAYMENT",
  ui: {
    layout: 'ACCORDION'
  }
});
await widget.mount("widget-payment"); // mount when the container is in the DOM

Available Layouts​

Choose from three layout options to match your design requirements:

Collapsible sections for the full payment flow.

Selection Widget​

Displays the list of available payment methods for customer selection.

This widget handles only the selection UI, not payment forms. Pair it with the FORM widget to display the form for the selected payment method.

Like other widgets, the Selection widget mounts to a container using an HTML id attribute. The examples below assume a DOM element with the id widget-payment.

Available Layouts​

Choose from two layout options:

Card grid of methods.

Form Widget​

Displays the payment form for a specific payment method. Use it in combination with a SELECTION widget, or in standalone mode by specifying the preSelectMethod option.

The widget uses the id html artibutte to target its rendering place. Here we assume that the DOM contains an element with the id widget-form

const widget = await manager.createWidget({
    interface: "FORM",
    preSelectMethod: "creditcard"
});
await widget.mount("widget-form"); //can be called whenever you want

Pay Button​

The PAY_BUTTON widget provides a submit button to trigger the payment flow.

This button automatically reflects the payment session state (enabled, disabled) and only becomes active when a payment method is selected and the form validation passes.

Good to know

For payment methods that require native buttons (such as Apple Pay, Google Pay, or PayPal), use the X_PAY_BUTTONS interface instead.

The widget uses the ID HTML attribute to target its rendering place. Here, we assume that the DOM contains an element with the id widget-button

const payButton = await manager.createWidget({
    ui: {
        translations: {
            overrides: {
                WIDGET_PAY_BUTTON_TEXT: "Proceed to payment"
            }
        }
    },
    interface: "PAY_BUTTON"
});
await payButton.mount("widget-button");

XPay Buttons​

Displays native payment buttons for Apple Pay, Google Pay, PayPal, and other express checkout methods as independent, standalone buttons.

The widget uses the ID HTML attribute to target its rendering place. Here, we assume that the DOM contains an element with the id widget-x-pay-buttons

const payButton = await manager.createWidget({
    interface: "X_PAY_BUTTONS",
    ui:{
        payButtons:{
            google: {
              buttonSizeMode: 'fill',
              buttonColor: 'black',
              buttonType: 'plain'
            }
        },
        translations:{
            overrides:{
            }
        }
    }
});
await payButton.mount("widget-x-pay-buttons");

XPay Button Configuration​

Customize XPay buttons using the ui.payButtons option. The following configuration options are available:

export type PayButtonsOptions = 
{
    google?: {
      buttonColor?: 'default' | 'black' | 'white';
      buttonType?: 'book' | 'buy' | 'checkout' | 'donate' | 'order' | 'pay' | 'plain' | 'subscribe';
      buttonSizeMode?: 'static' | 'fill';
      buttonRadius?: number;
    };
    apple?: {
      type?:
              | 'plain'
              | 'buy'
              | 'donate'
              | 'check-out'
              | 'book'
              | 'subscribe'
              | 'add-money'
              | 'contribute'
              | 'order'
              | 'reload'
              | 'rent'
              | 'support'
              | 'tip'
              | 'top-up';
      buttonstyle?: 'black' | 'white' | 'white-outline';
      buttonRadius?: number;
      buttonHeight?: number;
    };
    paypal?: {
      layout?: 'vertical' | 'horizontal';
      color?: 'silver' | 'white' | 'black' | 'gold' | 'blue';
      shape?: 'rect' | 'pill';
      height?: number;
      label?: 'paypal' | 'checkout' | 'buynow' | 'pay' | 'installment';
    };
};
Lyra Method Limitations

When using Lyra-based implementations (such as Payzen), be aware of the following limitations:

  • GooglePay and ApplePay buttons are combined into a single button due to Lyra SDK constraints. You may need to separate Apple Pay and Google Pay from other express payment methods to achieve your desired layout.
  • If you want to display PayPal as an XPay button alongside Lyra methods, create a separate widget instance that excludes Lyra payment methods.
  • Only the buy button type is supported for both ApplePay and GooglePay buttons.

Amount Widget​

Displays the total session amount and provides a breakdown showing how the payment is distributed across payment partners.

const widgetAmount = await manager.createWidget({
  ui: {
    translations: {
      locale: 'en-US'
    }
  },
  interface: "AMOUNT"
});
await widgetAmount.mount("widget-amount");

Wallet Widget​

Displays all saved payment tokens in a horizontal list, allowing customers to manage their stored payment methods.

The widget uses the ID HTML attribute to target its rendering place. Here, we assume that the DOM contains an element with the id widget-wallet

const widgetToken = await widgetManager.createWidget({
			interface: 'WALLET',
			name: 'widget-wallet',
			ui: {
				translations: {locale:"en-us"}
			}
		});
await widgetToken.mount("widget-wallet");

Tokens Widget​

Displays saved payment tokens in a horizontal list, enabling customers to reuse previously stored payment methods.

This widget supports two layout options: ACCORDION and LIST.

The widget uses the ID HTML attribute to target its rendering place. Here, we assume that the DOM contains an element with the id widget-token

const widgetToken = await widgetManager.createWidget({
			interface: 'TOKENS',
			name: 'widget-token',
			ui: {
				translations: {locale:"en-us"},
				layout: {
					name: 'ACCORDION' // or 'LIST'
				}
			}
		});
await widgetToken.mount("widget-token");

Visual representation of a list of tokens

Loan Simulation Widget​

Displays installment payment offers such as 3x or 4x installments.
This widget does not require a payment session, making it ideal for product pages and marketing purposes.

The widget uses the ID HTML attribute to target its rendering place. Here, we assume that the DOM contains an element with the id widget-loan-simulation 

const widgetSimu = await manager.createWidget({
    interface:"LOAN_SIMULATION",
    payload:{
        partner: 'floa',
        method: 'cb3x',
        product:{
            amount:200,
            shipments: [],
            currency_code:"EUR"
        }
    }
});
await widgetSimu.mount("widget-loan-simulation"); //can be called whenever you want

Programmatic Loan Simulation​

Retrieve loan simulation data programmatically without rendering UI components by calling methods directly from the widget manager.

Get Available Candidates​

const candidates = await checkout.getSimulationCandidates({ product: { amount: 100, shipments: [] } });

Response:

[
  { "method": "cb3x", "partner": "oney" },
  { "method": "cb4x", "partner": "oney" },
  { "method": "cb10x", "partner": "oney" },
  { "method": "cb3x", "partner": "floa" },
  { "method": "cb12x", "partner": "oney" }
]

Get Simulation Details​

const simulation = await checkout.getSimulation({ partner: "floa", method: "cb3x", product: { amount: 100, shipments: [] } });

Response:

{
  "partner": "floa",
  "method": "cb3x",
  "plugin_result": {
    "instalment_number": 2,
    "instalment_amount": 33.86,
    "total_cost": 1.59,
    "initial_instalment_amount": 33.87,
    "final_instalment_amount": 33.86,
    "legal_url": "http://urltolegal.fr",
    "legal_text": "text from psp",
    "legal_html": "html from psp"
  }
}