Hooks

Hooks let you tap into the Drop-in lifecycle to respond to events that require your application to act — such as refreshing an expired session.

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
  hooks: {
    onRefreshSession: async () => { /* your code */ },
  },
});

Refresh an Expired Session

When a payment session expires, the Drop-in displays an overlay. If you provide the onRefreshSession hook, a Refresh session button appears on that overlay. When the user clicks it, your hook is called.

The hook is fire-and-forget: the Drop-in does not expect a return value. Your responsibility is to create a new session on your backend and pass it to the Drop-in by calling dropin.setSession(). The overlay lifts automatically once the new session is ready.

If you do not provide the hook, the button is not shown and the session remains expired with no recovery path.

const dropin = await Purse.createDropinCheckout({
  session: clientSession.widget.data,
  hooks: {
    async onRefreshSession() {
      // Create a new session on your backend
      const newSession = await fetch('/api/payment-session', { method: 'POST' })
        .then(res => res.json());

      // Hand it back to the Drop-in
      await dropin.setSession(newSession.widget.data);
    },
  },
});

Overlay stays until setSession resolves

After onRefreshSession is called, the Drop-in shows a loading indicator on the button and waits. The expired overlay only disappears once dropin.setSession() completes successfully. If onRefreshSession throws, an error message is shown and the button re-enables so the user can retry.

Hook required to show the button

The Refresh session button is only rendered when onRefreshSession is provided. Without it, expired sessions show the overlay with no action available.

Hook Reference

Hook	When	Blocks UI	Use For
onRefreshSession	When the user clicks Refresh session on the expired overlay	Yes — loading state until setSession() resolves	Fetching a new session from your backend and handing it to the Drop-in