Create a payouts session

Overview

Manages authentication and creates payout elements. The PayoutsSession handles token management, element creation, and provides convenience methods for showing elements in modals.

Examples

Basic usage

const session = whopElements.createPayoutsSession({
  token: async () => {
    const response = await fetch("/api/token");
    const data = await response.json();
    return data.token;
  },
  companyId: "your-company-id",
  redirectUrl: "https://yourapp.com/callback",
});

session.on("ready", () => {
  console.log("Session is ready");
});

Creating elements

const balanceElement = session.createElement("balance-element", {});
balanceElement.mount("#balance-container");

const withdrawButton = session.createElement("withdraw-button-element", {
  onWithdraw: () => console.log("Withdrawal initiated"),
});
withdrawButton.mount("#withdraw-button");

// No args — the modal auto-closes on completion or dismiss
session.showWithdrawModal();

// Custom callback — runs your handler, then auto-closes
session.showWithdrawModal({
  onWithdraw: () => console.log("Withdrawal submitted"),
});

// preventDefault() opts out of auto-close
session.showWithdrawModal({
  onWithdraw: (ev) => {
    ev.preventDefault(); // modal stays open
    showConfirmation();
  },
});

Options

Property	Type	Required	Default	Description
`token`	`Token \| GetToken`	Yes	-	The token to use for the session. If a function is provided, it will be called and awaited to get the token. When a function is provided, the token will be refreshed automatically before it expires. if a string is provided, it will be used as the token and not refreshed automatically. However you can update the token at runtime by calling ‘updateOptions’ with a new token.
`currency`	`string \| undefined`	No	”USD”	The currency to use in the Elements
`companyId`	`string`	Yes	-	The company ID to use in the Elements
`redirectUrl`	`string`	Yes	-	URL to redirect to after identity verification is completed. This must be an absolute URL (e.g., “https://yourapp.com/callback”). Localhost URLs will not work - use ngrok for local development.

Events

Events emitted by the PayoutsSession. Listen to these events using the on() method.

`optionsUpdated`

Emitted when the session options are updated via updateOptions(). Callback signature: (options: ExpandedPayoutsSessionOptions) => void

`tokenRefreshed`

Emitted when the authentication token is refreshed. Callback signature: (token: string) => void

`tokenRefreshError`

Emitted when token refresh fails. Callback signature: (error: unknown) => void

`error`

Emitted when an error occurs during session operation. Callback signature: (error: unknown) => void

`ready`

Emitted when the session is ready and authenticated. Callback signature: (void) => void

Methods

`createElement(type, options)`

Create a new element instance.

Parameter	Type	Description
`type`	T \| { type: T; }	The element type (e.g., “balance-element”, “withdraw-button-element”)
`options`	PayoutsSessionElements[T][0]	Element-specific configuration options

Returns: PayoutsSessionElements[T][1]

const element = session.createElement("balance-element", {
  onReady: () => console.log("Element ready"),
});
element.mount("#container");

`updateOptions(options)`

Update the session options after initialization. Changes will be propagated to all active elements.

Parameter	Type	Description
`options`	Partial<PayoutsSessionOptions>	Partial options object with the values to update

`destroy()`

Destroy the session and clean up all mounted elements. Call this when you no longer need the session to free up resources.

`showWithdrawModal(options, force)`

Show the withdraw element in a modal overlay. By default, the modal auto-closes on completion (onWithdraw) or dismiss (onClose). Call ev.preventDefault() in a callback to prevent auto-close.

Parameter	Type	Description
`options`	`WithdrawElementOptions` \| ((modal: ModalContainer) => `WithdrawElementOptions`) \| undefined	Element options or a callback that receives the modal container
`force`	Force \| undefined	-