Widget Layout

The layout determines how the widget interface is displayed. This includes visual orientation, token display, modal behavior, and more.

---

Layout Options Reference

export type LayoutOptions = {
  name: WidgetLayout;
  cardHolderPosition: CardHolderPosition;
  tooltips: FormField[];
  modalMode: ModalMode;
  consentMode: ConsentMode;
  useTokenName: boolean;
  noCVVForToken: boolean;
  hideOverlaysContent: boolean;
  saveTokenPosition: SaveTokenPosition;
  saveTokenCheckboxMode: SaveTokenCheckboxMode;
  vaultBrandSelectionMode: VaultBrandSelectionMode;
  merges: WidgetLayoutProtocolMerge[];
  responsive: boolean;
  breakpoints?: Record<Breakpoint, number>;
  tokenInline: {
    brandDisplay: BrandDisplay,
    contentOrientation: ContentOrientation,
    checkboxAppearance: CheckboxAppearance,
  }
};

---

Main Options

Option	Type	Description	Example
name	"ACCORDION" | "LIST" | "GRID"	Type of visual layout.	"GRID"
cardHolderPosition	"top" | "bottom" | "hidden"	Placement of the card holder field.	"bottom"
tooltips	"holder" | "expiry" | "pan" | "cvv" | "tokenName" | "phone" | "email"	Fields that display tooltips.	['pan', 'cvv']
modalMode	"centered" | "fixed-right" | "fixed-left"	Modal display behavior.	"centered"
consentMode	"checkbox" | "birthdate" | "none"	Required user consent format.	"birthdate"
useTokenName	boolean	Show token name in the list.	false
noCVVForToken	boolean	Skip CVV input for token-based payments.	true
hideOverlaysContent	boolean	Hide overlay texts and icons (e.g. suspension info).	false
saveTokenPosition	"top" | "bottom"	Placement of save token checkbox.	"top"
saveTokenCheckboxMode	"toggle" | "checkbox"	Toggle or checkbox mode.	"toggle"
vaultBrandSelectionMode	"select" | "inPanInput" | "hypertext" | "hidden"	Brand selector format.	"inPanInput"
responsive	boolean	Enables responsive design for tokens.	true
breakpoints	Record<Breakpoint, number>	Define breakpoints to switch layouts (for tokens only).	{ sm: 600, md: 800 }

Merges

The merges property allows you to group multiple payment methods under a single UI group.

export type WidgetLayoutProtocolMerge = {
  name: string;
  title?: string;
  subtitle?: string;
  emptyPlaceholder?: string;
  layout?: WidgetLayout;
  iconSrc?: string;
  filter: (p: WidgetPaymentMethod | WidgetPaymentToken) => boolean;
};

warning

If you set a single merge that includes all payment methods, they will become exclusive (except for giftcards, which remain combinable).

Example

function filterGiftcard(protocol) {
  return protocol.method === 'giftcard';
}

const widget = await widgetManager.createWidget({
  interface: 'PAYMENT',
  ui: {
    layout: {
      merges: [{
        name: 'SECONDARIES',
        filter: filterGiftcard,
        title: 'Use your giftcard',
        subtitle: 'Only for secondary payment',
      }]
    }
  }
});

Token Inline Display

You can also configure how tokens are displayed within the layout using the tokenInline property.

Option	Values	Description
brandDisplay	"icon" | "text"	Show token brand as text or icon
contentOrientation	"horizontal" | "vertical"	Layout of the token elements
checkboxAppearance	"radio" | "checkbox"	Style of selection control for token

Example

const widget = await widgetManager.createWidget({
  interface: 'PAYMENT',
  ui: {
    layout: {
      tokenInline: {
        brandDisplay: 'icon',
        contentOrientation: 'vertical',
        checkboxAppearance: 'radio'
      }
    }
  }
});