Options and Methods

Information

The customization of the widget is a topic of constant improvement within our Front Team.
We provide additional variables and features on a weekly basis.

Methods and Options

The Purse widget offers a wide set of configuration options to personalize its behavior and visuals.
These allow merchants to adapt the checkout to their specific branding and UX requirements.

Example Setup

const widget = await widgetManager.createWidget({
  name: "my-widget",
  interface: "PAYMENT",
  preSelectMethod: "ACI",
  methods: (protocol) => protocol.partner === "illicado",
  sortProtocols: myFancyCustomSortFunction,
  autoSelectTokenStrategy: "none",
  forceTokenRegistration: false,
  tokenRegistrationDefaultValue: false,
  payload: {...},
  ui: {...}
})

About Tokens

In this page, "token" refers to saved payment methods, such as a credit card stored in the Purse vault system.
Learn more about how tokenization works here.

Options Table

Option	Type	Description	Example
name	string	Identifier of the widget. If not provided, an autogenerated name will be used.	"payment-widget"
interface	string	Defines the widget interface. See available types here.	"PAYMENT"
preSelectMethod	string	Sets a default selected payment method.	"aci"
methods	(protocol) => boolean	Filters payment methods.	protocol.method === "wallet"
sortProtocols	(a, b) => number	Custom sorting function for payment methods.	—
autoSelectTokenStrategy	"none", "fav_only", "fav_or_first"	Auto-select token logic.	"none"
forceTokenRegistration	boolean	Forces token registration even if the checkbox is unchecked.	true
tokenRegistrationDefaultValue	boolean	Defines whether the token checkbox is pre-checked.	false
payload	any	Loads a configuration object, such as for a simulator.	—
ui	WidgetUiOptions	Controls visuals and layout. See options here.	—
formatCurrency	({ amount, currency }) => string	Custom format for displaying currency values.	"${amount} ${currency}"

Widget Interfaces & Layout

export type WidgetUiOptions = {
  layout?: LayoutOptions, 
  themeID?: string,
  translations?: TranslationsOptions,
  stylesheet?: StylesheetOptions,
  assets?: AssetsOptions,
  payButtons?: PayButtonsOptions
};

You can split the checkout into modular blocks on your page.
Start with the PAYMENT interface, then explore more via Widget Interface and Widget Layout.

Listening to Events

This section has moved, you can find it here.

Update Session Data

To update billing/shipping information dynamically, use:

API V1

async function updateSession(newSessionData) {
  const updated = await fetch("https://api.purse-sandbox.com/payment/v1", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer YOUR_API_TOKEN"
    },
    body: JSON.stringify(newSessionData)
  }).then(res => res.json());

  await widgetManager.setPaymentSession(updated);
}

API V2

async function updateSession(newSessionData) {
		try {
			await widgetManager.setWidgetData(newSessionData.widget.data);
		} catch (e) {
			console.log('Error : ', e);
		}
}

Manager Methods

Method	Return / Action	Description
getIsPaymentFulfilled()	boolean	Tells whether the session is fully paid.
getRemainingAmountToPay()	number	Returns remaining amount in the session.
setPaymentSession(session) (API V1) setWidgetData(session.widget.data) (API V2)	void	Updates session information.
resetNavigation()	void	Resets widget selection to neutral state.