Create widget session

Create a session for the embedded widgets

Creates a widget session on your backend to pre-configure the Pay or Deposit / Withdrawal widget — the mode, amount, allowed chains, and funding sources. Pass the returned id to the widget on your frontend.

Import

import { createWidgetSession } from "@paywithglide/glide-js";

Usage

index.ts

import { createWidgetSession } from "@paywithglide/glide-js";
import { config } from "./config";
 
const { id } = await createWidgetSession(config, {
  mode: "pay",
  amount: "5",
});
 
// Pass `id` to the useGlidePay hook on your frontend

Parameters

mode^*

'pay' | 'deposit'

The widget mode the session is for.

amount

nullable string

The amount, denominated in your preferred currency configured in the Glide Dashboard.

recipient

nullable string

The wallet address that receives the funds.

chainIds

nullable CAIP2[]

The chains the user can pay from. Defaults to the chains set in the config.

fundingSources

nullable string[]

The funding sources to offer: wallet, external_wallet, transfer, coinbase, coinbase_app, fiat, interac, onramp, or onramper.

excludeChainIds

nullable CAIP2[]

Chains to exclude from the payment options.

excludeCurrencyTiers

nullable ('tier1' | 'tier2' | 'tier3')[]

Currency tiers to exclude from the payment options.

excludeFundingSources

nullable string[]

Funding sources to exclude: transfer, coinbase, coinbase_app, fiat, interac, onramp, or onramper.

metadata

nullable string

Custom string metadata to attach to the session.

commissionRates

nullable CommissionRates

Commission rates per currency tier (tier1, tier2, tier3) paid out to the developer, as a percentage of the transaction amount (e.g., "0.5" = 0.5%).

maxSponsoredGasFeeUSD

nullable string

The maximum destination-chain gas fee, in USD, that will be sponsored.

enableRefundEmails

nullable boolean

When set to true, the payer will receive an email if their payment is refunded.

payerEmail

nullable string

The email address of the payer, used for refund notifications.

userPhoneNumber

nullable string

The phone number of the user.

stableDepositAddressKey

nullable string

An identifier for generating a stable deposit address across sessions.

Return Type

Returns a widget session object:

id^*

string

The unique identifier of the widget session. Pass this to the widget on your frontend.

mode^*

'pay'

The widget mode.

metadata

nullable string

The metadata attached to the session.

The widget session also echoes back the configuration it was created with (chainIds, excludeChainIds, excludeCurrencyTiers, excludeFundingSources, commissionRates, maxSponsoredGasFeeUSD, stableDepositAddressKey, widgetConfig).