Skip to main content

Widget Interfaces

We provide different types of widgets to handle specific parts of the payment UI.
This allows merchants to split the UI across the webpage and match their design vision.

Payment Widget​

A supervised combination of the SELECTION and FORM types.
This is the quickest way to implement a full payment widget.

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-payment

const widget = await manager.createWidget({
  interface: "PAYMENT",
  ui: {
    layout: 'ACCORDEON'
  }
});
await widget.mount("widget-payment"); // can be called whenever you want
info

PAYMENT is a supervised combination of the SELECTION and FORM types

Selection Widget​

Displays the list of available payment methods.
This widget does not handle forms, only the selection UI.

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-selection

const widget = await manager.createWidget({
    interface: "SELECTION",
    ui:{
        layout:"GRID"
    }
    methods:(protocol)=>protocol.method !== "giftcard"
});
await widget.mount("widget-payment"); //can be called whenever you want

Form Widget​

Displays the payment form for a method selected with a SELECTION widget.

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({
    ui: {
        layout: {
            name: 'ACCORDION',
        },
    },
    methods: (protocol) => {
        return protocol.method !== "giftcard"
    }, preSelectMethod: "creditcard",
    interface: "FORM"
});
await widget.mount("widget-form"); //can be called whenever you want

Pay Button​

Mandatory for some payment partners.
It handles internal triggers or partners' own 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-button

const payButton = await manager.createWidget({
    ui: {
        translations: {
            overrides: {
                WIDGET_PAY_BUTTON_TEXT: "Proceed to payment"
            }
        },
        stylesheet: {
            overrides:{
                "usp-pay-button-use-partner-ui":true, // false if you want to display our button in every case (allowing customisation)
            }
        }
    },
    interface: "PAY_BUTTON"
});
await payButton.mount("widget-button");

XPay Buttons​

Used to display Apple Pay, Google Pay, PayPal, etc., as independent 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 available options​

To configure the XPay buttons, you can use the following options in the ui.payButtons option of the interface:

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 implementation

Please note that for all Lyra button implementations (such as Payzen for example) :

  • The GooglePay and ApplePay buttons are displayed together in the same button. It is a limitation of the Lyra SDK. This might require you to segregate Applepay and Googlepay apart from other X-pays to setup them as you want. For example, if you want to display PayPal as an x-pay-button, you will need to create a separate widget that does not include any Lyra payment methods.
  • Only the buy button type is available for the ApplePay button.
  • Only the buy button type is available for the GooglePay button.

Amount Widget​

Displays the session amount and its breakdown between payment partners.

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

Wallet Widget​

Lists all session tokens in a horizontal list for management 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-wallet

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

Tokens Widget​

Lists session tokens in a horizontal list for reusability.

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'
				}
			}
		});
await widgetToken.mount("widget-token");

Visual representation of a list of tokens

Loan Simulation Widget​

Displays marketing offers like 3xCB or 4xCB.
Does not require a session, so it can be used on product pages.

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

Get Simulation Programmatically​

You can call internal methods from the widget manager to simulate loans without UI.

Get 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 for a candidate​

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"
  }
}