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");

// With options object
session.showWithdrawModal({
  onWithdraw: () => console.log("Withdrawal submitted"),
  onClose: () => console.log("Modal closed"),
});

// With callback for modal reference
session.showWithdrawModal((modal) => ({
  onWithdraw: () => {
    console.log("Withdrawal submitted");
    modal.close();
  },
  onClose: () => modal.close(),
}));

Options

Property	Type	Required	Default	Description
`token`	`string \| Promise<string \| null> \| GetToken \| null`	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.