@whop/elements 0.0.0 → 1.0.0-beta.1

package/payments.d.cts

@@ -0,0 +1,1211 @@
+/**
+ * Options for `whop.payments.create()`: the controller's props plus its `on<Event>` callbacks. In React, these are the `<Payments>` component's props.
+ * @example
+ * ```ts
+ * import { loadWhop } from "@whop/elements";
+ * 
+ * const whop = (await loadWhop())({ locale: "en" });
+ * const payments = whop.payments.create({}); // options: props + on<Event> callbacks
+ * ```
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export type PaymentsOptions = (
+	| {
+		/**
+		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection surface.
+		 */
+		accountId: string;
+		/**
+		 * Plan ID, prefixed `plan_`. It resolves client-side to currency, amount, and method configuration. Pass a plan or inline currency and amount, never both.
+		 */
+		plan: string;
+		/**
+		 * Minor-unit `feeInclusive` and `feeFree` totals used to gate methods when checkout re-prices `amount` for a fee-free method such as BNPL. Each method is checked against its matching total, preventing the selected fee-free method from disappearing. When omitted, `amount` gates every method.
+		 */
+		offerAmounts?: undefined;
+		/**
+		 * Return URL for off-site bank or 3DS steps. Defaults to the mounting page.
+		 */
+		returnUrl?: string;
+		/**
+		 * Displays consent to save the payment method and marks the token for `off_session` or `on_session` use.
+		 */
+		setupFutureUsage?: "off_session" | "on_session";
+		/**
+		 * Wallet availability override for deterministic previews. Live checkouts probe the host.
+		 */
+		previewWalletAvailability?: WalletAvailability;
+		/**
+		 * Checkout session updated when a buyer signs in. Pass its `chs_`-prefixed `id` and `client_secret`. Without them, sign-in succeeds but the session does not record the buyer.
+		 */
+		checkoutSession?: { id: string; clientSecret: string; };
+		/**
+		 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
+		 */
+		onLoadingChange?: ((loading: boolean) => void);
+		/**
+		 * Set `false` to turn off Whop's built-in usage analytics for this handle and its elements. The analytics identity is never threaded to its frames. A reserved option, not element data.
+		 */
+		analytics?: false;
+	}
+	| {
+		/**
+		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection surface.
+		 */
+		accountId: string;
+		/**
+		 * Lowercase three-letter ISO 4217 payment currency code. It filters the payment-method matrix.
+		 */
+		currency: string;
+		/**
+		 * Payment amount in minor units. Methods whose bounds exclude it aren't offered.
+		 */
+		amount: number;
+		/**
+		 * Minor-unit `feeInclusive` and `feeFree` totals used to gate methods when checkout re-prices `amount` for a fee-free method such as BNPL. Each method is checked against its matching total, preventing the selected fee-free method from disappearing. When omitted, `amount` gates every method.
+		 */
+		offerAmounts?: { feeInclusive: number; feeFree: number; };
+		/**
+		 * Account payment-method filters in the API's `enabled`, `disabled`, and `include_platform_defaults` format. `disabled` removes types, `enabled` restores offered types, and `include_platform_defaults: false` leaves only enabled types. Plans provide their own configuration.
+		 */
+		paymentMethodConfiguration?: { enabled?: string[] | undefined; disabled?: string[] | undefined; include_platform_defaults?: boolean | undefined; };
+		/**
+		 * Return URL for off-site bank or 3DS steps. Defaults to the mounting page.
+		 */
+		returnUrl?: string;
+		/**
+		 * Displays consent to save the payment method and marks the token for `off_session` or `on_session` use.
+		 */
+		setupFutureUsage?: "off_session" | "on_session";
+		/**
+		 * Wallet availability override for deterministic previews. Live checkouts probe the host.
+		 */
+		previewWalletAvailability?: WalletAvailability;
+		/**
+		 * Checkout session updated when a buyer signs in. Pass its `chs_`-prefixed `id` and `client_secret`. Without them, sign-in succeeds but the session does not record the buyer.
+		 */
+		checkoutSession?: { id: string; clientSecret: string; };
+		/**
+		 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
+		 */
+		onLoadingChange?: ((loading: boolean) => void);
+		/**
+		 * Set `false` to turn off Whop's built-in usage analytics for this handle and its elements. The analytics identity is never threaded to its frames. A reserved option, not element data.
+		 */
+		analytics?: false;
+	}
+	| {
+		/**
+		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection surface.
+		 */
+		accountId?: undefined;
+		/**
+		 * Plan ID, prefixed `plan_`. It resolves client-side to currency, amount, and method configuration. Pass a plan or inline currency and amount, never both.
+		 */
+		plan?: undefined;
+		/**
+		 * Lowercase three-letter ISO 4217 payment currency code. It filters the payment-method matrix.
+		 */
+		currency?: undefined;
+		/**
+		 * Payment amount in minor units. Methods whose bounds exclude it aren't offered.
+		 */
+		amount?: undefined;
+		/**
+		 * Minor-unit `feeInclusive` and `feeFree` totals used to gate methods when checkout re-prices `amount` for a fee-free method such as BNPL. Each method is checked against its matching total, preventing the selected fee-free method from disappearing. When omitted, `amount` gates every method.
+		 */
+		offerAmounts?: undefined;
+		/**
+		 * Account payment-method filters in the API's `enabled`, `disabled`, and `include_platform_defaults` format. `disabled` removes types, `enabled` restores offered types, and `include_platform_defaults: false` leaves only enabled types. Plans provide their own configuration.
+		 */
+		paymentMethodConfiguration?: undefined;
+		/**
+		 * Return URL for off-site bank or 3DS steps. Defaults to the mounting page.
+		 */
+		returnUrl?: string;
+		/**
+		 * Displays consent to save the payment method and marks the token for `off_session` or `on_session` use.
+		 */
+		setupFutureUsage?: "off_session" | "on_session";
+		/**
+		 * Wallet availability override for deterministic previews. Live checkouts probe the host.
+		 */
+		previewWalletAvailability?: WalletAvailability;
+		/**
+		 * Checkout session updated when a buyer signs in. Pass its `chs_`-prefixed `id` and `client_secret`. Without them, sign-in succeeds but the session does not record the buyer.
+		 */
+		checkoutSession?: { id: string; clientSecret: string; };
+		/**
+		 * Runs when the grouped loading state changes. The value is `true` while any mounted element is still loading.
+		 */
+		onLoadingChange?: ((loading: boolean) => void);
+		/**
+		 * Set `false` to turn off Whop's built-in usage analytics for this handle and its elements. The analytics identity is never threaded to its frames. A reserved option, not element data.
+		 */
+		analytics?: false;
+	}
+) & {
+	/**
+	 * Visual customization for this group's elements. Overrides the global `WhopElements({ appearance })`. Change it live with `update({ appearance })`.
+	 */
+	appearance?: import("./_framework.js").Appearance;
+	/**
+	 * Locale for this group's element UI text. Set it to one of the app's built locales to override the global configuration. Any other value falls back to the default locale.
+	 */
+	locale?: import("./_framework.js").WhopElementsLocale;
+};
+
+/**
+ * Consumer props for the "payment" element. Set at create (or as `<PaymentElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/payments/payment
+ */
+export interface PaymentElementProps {
+	/**
+	 * Controls display order in either layout. Listed types appear first in order. Unlisted types retain their relative order. Does not affect availability.
+	 * @default []
+	 */
+	order?: string[];
+	/**
+	 * Controls billing-details collection. `billingDetails: 'minimal'` (default) follows each method's matrix. Methods collect name and the complete country format by default. An override may collect only the declared minimum or nothing. For cards, the minimum is name on card, country, and postal code. `'full'` requires name and the complete country format for every fresh method. `'never'` hides the block. Pass the address to `createConfirmationToken` instead. The country selector includes only countries supported by the method and payment currency. It locks when only one is available.
+	 * @default {"billingDetails":"minimal"}
+	 */
+	fields?: { billingDetails?: "full" | "minimal" | "never" | undefined; };
+	/**
+	 * Picker layout. `accordion` (default) stacks methods and expands details inline. `horizontal` shows equal-width, non-scrolling tiles with selected details below. After four methods, a More tile opens a native selector. The method picked there occupies the final tile until the next selection. Selection and confirmation behave identically.
+	 * @default "accordion"
+	 */
+	layout?: "accordion" | "horizontal";
+	/**
+	 * `accordion` only. Adds spacing and separate card styling between methods. Ignored when `layout` is `horizontal`.
+	 * @default false
+	 */
+	separated?: boolean;
+	/**
+	 * Whether to select the first offered method after resolution. The default `true` respects `order` and emits `selected` and `change` like a buyer interaction. It runs once before buyer interaction and does nothing when no method is offered. Set `false` to mount unselected. Independently, if an update removes the selected method, selection falls back to the first offered method. An already unselected element stays unselected.
+	 * @default true
+	 */
+	autoSelect?: boolean;
+}
+
+/**
+ * The live handle for a mounted "payment" element. Returned by `create("payment")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/payments/payment
+ */
+export interface PaymentElementHandle {
+	/**
+	 * Select a method through the same path as a buyer interaction. For example, `select('cashapp')` expands the tile and emits `selected` and `change`. Cards remain `complete: false` until their fields are complete. Unknown, unavailable, or amount-gated methods reject with code `METHOD_NOT_OFFERED`. `select(null)` clears selection and emits `change` with `complete: false`. Use with `autoSelect={false}` for full external control.
+	 */
+	select: (input: string | null) => Promise<void>;
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<PaymentElementProps>) => void;
+}
+
+/**
+ * Options for `create("payment")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const payment = payments.create("payment", {}); // this interface: props + on<Event> callbacks
+ * payment.mount("#payments-payment");
+ * ```
+ * @see https://docs.whop.com/elements/latest/payments/payment
+ */
+export interface PaymentElementCreateOptions {
+	/**
+	 * Controls display order in either layout. Listed types appear first in order. Unlisted types retain their relative order. Does not affect availability.
+	 * @default []
+	 */
+	order?: string[];
+	/**
+	 * Controls billing-details collection. `billingDetails: 'minimal'` (default) follows each method's matrix. Methods collect name and the complete country format by default. An override may collect only the declared minimum or nothing. For cards, the minimum is name on card, country, and postal code. `'full'` requires name and the complete country format for every fresh method. `'never'` hides the block. Pass the address to `createConfirmationToken` instead. The country selector includes only countries supported by the method and payment currency. It locks when only one is available.
+	 * @default {"billingDetails":"minimal"}
+	 */
+	fields?: { billingDetails?: "full" | "minimal" | "never" | undefined; };
+	/**
+	 * Picker layout. `accordion` (default) stacks methods and expands details inline. `horizontal` shows equal-width, non-scrolling tiles with selected details below. After four methods, a More tile opens a native selector. The method picked there occupies the final tile until the next selection. Selection and confirmation behave identically.
+	 * @default "accordion"
+	 */
+	layout?: "accordion" | "horizontal";
+	/**
+	 * `accordion` only. Adds spacing and separate card styling between methods. Ignored when `layout` is `horizontal`.
+	 * @default false
+	 */
+	separated?: boolean;
+	/**
+	 * Whether to select the first offered method after resolution. The default `true` respects `order` and emits `selected` and `change` like a buyer interaction. It runs once before buyer interaction and does nothing when no method is offered. Set `false` to mount unselected. Independently, if an update removes the selected method, selection falls back to the first offered method. An already unselected element stays unselected.
+	 * @default true
+	 */
+	autoSelect?: boolean;
+	/**
+	 * Fires when selection changes. `complete: true` means the buyer selected a method and completed its card fields or required inputs. Use it to enable confirmation. `method` provides category, per-currency countries, and amount bounds for dependent UI such as country fields. `supportsBuyerFee` indicates whether to include Whop's buyer service fee in the displayed total.
+	 */
+	onChange?: ((payload: { complete: boolean; type?: string | undefined; supportsBuyerFee?: boolean | undefined; method?: { type: string; category: string; template: string; display_name: string; countries: ({ country: string; min_amount: number | null; max_amount: number | null; })[]; min_amount: number | null; max_amount: number | null; } | undefined; }) => void);
+	/**
+	 * Fires about 300 ms after the internal billing address changes. Use it for tax, shipping, or other address-dependent updates. `country` is an ISO 3166-1 alpha-2 code. The payload omits other address keys when empty or unused for that country. `complete: true` means the billing block is valid and complete. This event fires only while the payment element owns address collection. With `fields.billingDetails: 'never'`, use your address source. With a mounted `AddressElement`, use its `change` event.
+	 */
+	onAddressChange?: ((payload: { complete: boolean; address: { line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "address" element. Set at create (or as `<AddressElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/payments/address
+ */
+export interface AddressElementProps {
+	/**
+	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
+	 * @default "full"
+	 */
+	layout?: "full" | "compact";
+	/**
+	 * Address line 2: always visible (default), revealed by a text button (`toggle`), or never collected.
+	 * @default "always"
+	 */
+	line2?: "never" | "toggle" | "always";
+	/**
+	 * The name row: one full-name field (default), split first/last fields, or none.
+	 * @default "combined"
+	 */
+	name?: "split" | "combined" | "none";
+	/**
+	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
+	 * @default "billing"
+	 */
+	mode?: "billing" | "shipping";
+	/**
+	 * `full` (default) follows the selected country's complete address format. `minimal` collects only country and postal code. `name` independently adds required name fields. Set `name` to `none` to omit them. This element does not add fields required by a payment method. Card confirmation requires a name, country, and postal code, so keep `name` enabled or pass `billingDetails.name`.
+	 * @default "full"
+	 */
+	scope?: "full" | "minimal";
+	/**
+	 * Organization fields: none (default), name only, or name with a business/individual selector.
+	 * @default "none"
+	 */
+	organization?: "name" | "none" | "name_with_type";
+	/**
+	 * Seed values applied once before first paint (`address.country` is an ISO 3166-1 alpha-2 country code). Takes precedence over IP-country detection.
+	 */
+	defaultValues?: { name?: string | undefined; address?: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country?: string | undefined; } | undefined; };
+	/**
+	 * Default the country from the buyer's IP (resolved before first paint). Falls back to the controller's `countryHint`, then US.
+	 * @default true
+	 */
+	detectCountry?: boolean;
+	/**
+	 * Allowed ISO 3166-1 alpha-2 country codes. With one code, the selector remains visible but offers only that country.
+	 */
+	allowedCountries?: string[];
+	/**
+	 * Enables Google Places suggestions for the street address. If no match appears or Places is blocked, the list reports no matches and lets buyers enter the address manually. Set `false` for a plain input.
+	 * @default true
+	 */
+	autocomplete?: boolean;
+	/**
+	 * Additional fields rendered with the address form. Values are validated and emitted in the separate `custom` map.
+	 */
+	customFields?: ({ key: string; label: string; type: "text" | "phone" | "select" | "date"; position: "after_name" | "after_organization" | "before_country" | "after_address"; required?: boolean | undefined; options?: string[] | undefined; format?: string | undefined; autocomplete?: string | undefined; })[];
+	/**
+	 * Fallback country after `defaultValues` and IP detection. Use an ISO 3166-1 alpha-2 code. An empty value falls back to `US`.
+	 * @default ""
+	 */
+	countryHint?: string;
+}
+
+/**
+ * The live handle for a mounted "address" element. Returned by `create("address")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/payments/address
+ */
+export interface AddressElementHandle {
+	/**
+	 * Validates the form, reveals all inline errors, and never throws. Returns `complete`, `address`, and `errors`. `errors` is empty exactly when `complete` is true. Keys use contract names such as `postal_code` and `line1`, `custom:<key>` for custom fields, and transient `form` while loading.
+	 */
+	validate: () => Promise<{ complete: boolean; address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; errors: Record<string, string>; }>;
+	/**
+	 * Returns `address` and `custom` without validation or revealing errors.
+	 */
+	getValues: () => Promise<{ address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; custom: Record<string, string>; }>;
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<AddressElementProps>) => void;
+}
+
+/**
+ * Options for `create("address")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const address = payments.create("address", {}); // this interface: props + on<Event> callbacks
+ * address.mount("#payments-address");
+ * ```
+ * @see https://docs.whop.com/elements/latest/payments/address
+ */
+export interface AddressElementCreateOptions {
+	/**
+	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
+	 * @default "full"
+	 */
+	layout?: "full" | "compact";
+	/**
+	 * Address line 2: always visible (default), revealed by a text button (`toggle`), or never collected.
+	 * @default "always"
+	 */
+	line2?: "never" | "toggle" | "always";
+	/**
+	 * The name row: one full-name field (default), split first/last fields, or none.
+	 * @default "combined"
+	 */
+	name?: "split" | "combined" | "none";
+	/**
+	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
+	 * @default "billing"
+	 */
+	mode?: "billing" | "shipping";
+	/**
+	 * `full` (default) follows the selected country's complete address format. `minimal` collects only country and postal code. `name` independently adds required name fields. Set `name` to `none` to omit them. This element does not add fields required by a payment method. Card confirmation requires a name, country, and postal code, so keep `name` enabled or pass `billingDetails.name`.
+	 * @default "full"
+	 */
+	scope?: "full" | "minimal";
+	/**
+	 * Organization fields: none (default), name only, or name with a business/individual selector.
+	 * @default "none"
+	 */
+	organization?: "name" | "none" | "name_with_type";
+	/**
+	 * Seed values applied once before first paint (`address.country` is an ISO 3166-1 alpha-2 country code). Takes precedence over IP-country detection.
+	 */
+	defaultValues?: { name?: string | undefined; address?: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country?: string | undefined; } | undefined; };
+	/**
+	 * Default the country from the buyer's IP (resolved before first paint). Falls back to the controller's `countryHint`, then US.
+	 * @default true
+	 */
+	detectCountry?: boolean;
+	/**
+	 * Allowed ISO 3166-1 alpha-2 country codes. With one code, the selector remains visible but offers only that country.
+	 */
+	allowedCountries?: string[];
+	/**
+	 * Enables Google Places suggestions for the street address. If no match appears or Places is blocked, the list reports no matches and lets buyers enter the address manually. Set `false` for a plain input.
+	 * @default true
+	 */
+	autocomplete?: boolean;
+	/**
+	 * Additional fields rendered with the address form. Values are validated and emitted in the separate `custom` map.
+	 */
+	customFields?: ({ key: string; label: string; type: "text" | "phone" | "select" | "date"; position: "after_name" | "after_organization" | "before_country" | "after_address"; required?: boolean | undefined; options?: string[] | undefined; format?: string | undefined; autocomplete?: string | undefined; })[];
+	/**
+	 * Fallback country after `defaultValues` and IP detection. Use an ISO 3166-1 alpha-2 code. An empty value falls back to `US`.
+	 * @default ""
+	 */
+	countryHint?: string;
+	/**
+	 * Fires when the address changes. `complete` is true when all country-specific fields and required custom fields are valid. `address` follows confirmation-token `billing_details` names, including `postal_code`. `country` is an ISO 3166-1 alpha-2 code. Custom values are in `custom`.
+	 */
+	onChange?: ((payload: { complete: boolean; address: { name?: string | undefined; first_name?: string | undefined; last_name?: string | undefined; organization?: string | undefined; organization_type?: "business" | "individual" | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; custom: Record<string, string>; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "card" element. Set at create (or as `<CardElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/payments/card
+ */
+export interface CardElementProps {
+	/**
+	 * `stacked` (default) places the card number above expiration and security code. `compact` places all three in one row.
+	 * @default "stacked"
+	 */
+	layout?: "compact" | "stacked";
+}
+
+/**
+ * The live handle for a mounted "card" element. Returned by `create("card")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/payments/card
+ */
+export interface CardElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<CardElementProps>) => void;
+}
+
+/**
+ * Options for `create("card")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const card = payments.create("card", {}); // this interface: props + on<Event> callbacks
+ * card.mount("#payments-card");
+ * ```
+ * @see https://docs.whop.com/elements/latest/payments/card
+ */
+export interface CardElementCreateOptions {
+	/**
+	 * `stacked` (default) places the card number above expiration and security code. `compact` places all three in one row.
+	 * @default "stacked"
+	 */
+	layout?: "compact" | "stacked";
+	/**
+	 * Fires when card fields change. `complete` becomes true after the buyer fills all three. Use it to enable confirmation. `brand` is the detected card network.
+	 */
+	onChange?: ((payload: { complete: boolean; brand: string; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "email" element. Set at create (or as `<EmailElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/payments/email
+ */
+export interface EmailElementProps {
+	/**
+	 * Shows the localized label. Set `false` when supplying your own. The input retains a localized `aria-label`.
+	 * @default true
+	 */
+	label?: boolean;
+	/**
+	 * Seed value applied once at mount.
+	 * @default ""
+	 */
+	defaultValue?: string;
+	/**
+	 * Placeholder text for the email input. Empty (default) renders `you@example.com`.
+	 * @default ""
+	 */
+	placeholder?: string;
+}
+
+/**
+ * The live handle for a mounted "email" element. Returned by `create("email")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/payments/email
+ */
+export interface EmailElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<EmailElementProps>) => void;
+}
+
+/**
+ * Options for `create("email")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const email = payments.create("email", {}); // this interface: props + on<Event> callbacks
+ * email.mount("#payments-email");
+ * ```
+ * @see https://docs.whop.com/elements/latest/payments/email
+ */
+export interface EmailElementCreateOptions {
+	/**
+	 * Shows the localized label. Set `false` when supplying your own. The input retains a localized `aria-label`.
+	 * @default true
+	 */
+	label?: boolean;
+	/**
+	 * Seed value applied once at mount.
+	 * @default ""
+	 */
+	defaultValue?: string;
+	/**
+	 * Placeholder text for the email input. Empty (default) renders `you@example.com`.
+	 * @default ""
+	 */
+	placeholder?: string;
+	/**
+	 * Fires when the email changes. `complete` is true when plausible. Sign-in fires it with the signed-in email, which also feeds `createConfirmationToken()`.
+	 */
+	onChange?: ((payload: { email: string; complete: boolean; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "taxId" element. Set at create (or as `<TaxIdElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/payments/taxId
+ */
+export interface TaxIdElementProps {
+	/**
+	 * Disables both fields while the host saves the last committed registration.
+	 * @default false
+	 */
+	disabled?: boolean;
+	/**
+	 * ISO 3166-1 alpha-2 buyer country used to preselect the type. `AR` selects `ar_cuit`. EU and unmapped or empty values select `eu_vat`. Other uniquely mapped countries select their type. A manual selection persists across country changes.
+	 * @default ""
+	 */
+	country?: string;
+	/**
+	 * Initial `type` and `value` from a resumed session. An unsupported `type` falls back to the country default.
+	 */
+	defaultValue?: { type: string; value: string; };
+	/**
+	 * API validation error shown below the value input. Empty (default) shows nothing.
+	 * @default ""
+	 */
+	error?: string;
+}
+
+/**
+ * The live handle for a mounted "taxId" element. Returned by `create("taxId")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/payments/taxId
+ */
+export interface TaxIdElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<TaxIdElementProps>) => void;
+}
+
+/**
+ * Options for `create("taxId")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const taxId = payments.create("taxId", {}); // this interface: props + on<Event> callbacks
+ * taxId.mount("#payments-taxId");
+ * ```
+ * @see https://docs.whop.com/elements/latest/payments/taxId
+ */
+export interface TaxIdElementCreateOptions {
+	/**
+	 * Disables both fields while the host saves the last committed registration.
+	 * @default false
+	 */
+	disabled?: boolean;
+	/**
+	 * ISO 3166-1 alpha-2 buyer country used to preselect the type. `AR` selects `ar_cuit`. EU and unmapped or empty values select `eu_vat`. Other uniquely mapped countries select their type. A manual selection persists across country changes.
+	 * @default ""
+	 */
+	country?: string;
+	/**
+	 * Initial `type` and `value` from a resumed session. An unsupported `type` falls back to the country default.
+	 */
+	defaultValue?: { type: string; value: string; };
+	/**
+	 * API validation error shown below the value input. Empty (default) shows nothing.
+	 * @default ""
+	 */
+	error?: string;
+	/**
+	 * Fires on blur or Enter when the value is nonempty, or when the type changes with a value present. Identical consecutive values fire once. Clearing the value doesn't fire. The host must clear stored registrations.
+	 */
+	onChange?: ((payload: { taxId: { type: "ad_nrt" | "ao_tin" | "ar_cuit" | "al_tin" | "am_tin" | "aw_tin" | "au_abn" | "au_arn" | "eu_vat" | "az_tin" | "bs_tin" | "bh_vat" | "bd_bin" | "bb_tin" | "by_tin" | "bj_ifu" | "bo_tin" | "ba_tin" | "br_cnpj" | "br_cpf" | "bg_uic" | "bf_ifu" | "kh_tin" | "cm_niu" | "ca_bn" | "ca_gst_hst" | "ca_pst_bc" | "ca_pst_mb" | "ca_pst_sk" | "ca_qst" | "cv_nif" | "cl_tin" | "cn_tin" | "co_nit" | "cd_nif" | "cr_tin" | "hr_oib" | "do_rcn" | "ec_ruc" | "eg_tin" | "sv_nit" | "et_tin" | "eu_oss_vat" | "ge_vat" | "gh_tin" | "de_stn" | "gb_vat" | "gn_nif" | "hk_br" | "hu_tin" | "is_vat" | "in_gst" | "id_npwp" | "il_vat" | "jp_cn" | "jp_rn" | "jp_trn" | "kz_bin" | "ke_pin" | "kg_tin" | "la_tin" | "li_uid" | "li_vat" | "my_frp" | "my_itn" | "my_sst" | "mr_nif" | "mx_rfc" | "md_vat" | "me_pib" | "ma_vat" | "np_pan" | "nz_gst" | "ng_tin" | "mk_vat" | "no_vat" | "no_voec" | "om_vat" | "pe_ruc" | "ph_tin" | "pl_nip" | "ro_tin" | "ru_inn" | "ru_kpp" | "sa_vat" | "sn_ninea" | "rs_pib" | "sg_gst" | "sg_uen" | "si_tin" | "za_vat" | "kr_brn" | "es_cif" | "ch_uid" | "ch_vat" | "tw_vat" | "tj_tin" | "tz_vat" | "th_vat" | "tr_tin" | "ug_tin" | "ua_vat" | "ae_trn" | "us_ein" | "uy_ruc" | "uz_tin" | "uz_vat" | "ve_rif" | "vn_tin" | "zm_tin" | "zw_tin" | "sr_fin" | "xi_vat"; value: string; }; }) => void);
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "branding" element. Set at create (or as `<BrandingElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/payments/branding
+ */
+export interface BrandingElementProps {}
+
+/**
+ * The live handle for a mounted "branding" element. Returned by `create("branding")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/payments/branding
+ */
+export interface BrandingElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<BrandingElementProps>) => void;
+}
+
+/**
+ * Options for `create("branding")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const branding = payments.create("branding", {}); // this interface: props + on<Event> callbacks
+ * branding.mount("#payments-branding");
+ * ```
+ * @see https://docs.whop.com/elements/latest/payments/branding
+ */
+export interface BrandingElementCreateOptions {
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "cardFields" sub-controller: the `create("cardFields")` options and the minted sub handle's `update()` payload (React: `<CardFields>` props). Parent-injected props never appear here.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardFieldsSubOptions {
+	/**
+	 * `stacked` (default) shapes composed fields as a number row above expiration and security code. `compact` shapes one row. Separately mounted fields ignore this layout and render with full borders and rounded corners.
+	 * @default "stacked"
+	 */
+	layout?: "compact" | "stacked";
+	/**
+	 * Advanced Basis Theory publishable key. Omit it to fetch the key automatically.
+	 */
+	publicKey?: string;
+	/**
+	 * The seller's accepted card networks in display order — the matrix card entry's `networks` objects, whose API-served icons drive the number field's brand art. Omit it to fetch alongside the key.
+	 */
+	networks?: CardNetworkArt[];
+	/**
+	 * Fires when completeness changes. `complete` becomes true after the buyer fills all three fields. Use it to enable confirmation. `brand` is the detected card network.
+	 */
+	onChange?: ((payload: { complete: boolean; brand: string; }) => void);
+}
+
+/**
+ * Consumer props for the "cardFields" sub-controller's "cardNumber" element.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardNumberElementProps {}
+
+/**
+ * The live handle for a mounted "cardNumber" element. Returned by the "cardFields" sub handle's `create("cardNumber")`.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardNumberElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<CardNumberElementProps>) => void;
+}
+
+/**
+ * Options for the "cardFields" sub handle's `create("cardNumber")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardNumberElementCreateOptions {
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "cardFields" sub-controller's "cardExpiry" element.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardExpiryElementProps {}
+
+/**
+ * The live handle for a mounted "cardExpiry" element. Returned by the "cardFields" sub handle's `create("cardExpiry")`.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardExpiryElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<CardExpiryElementProps>) => void;
+}
+
+/**
+ * Options for the "cardFields" sub handle's `create("cardExpiry")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardExpiryElementCreateOptions {
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * Consumer props for the "cardFields" sub-controller's "cardCvc" element.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardCvcElementProps {}
+
+/**
+ * The live handle for a mounted "cardCvc" element. Returned by the "cardFields" sub handle's `create("cardCvc")`.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardCvcElementHandle {
+	/**
+	 * Mounts the element in `target` and starts loading. React components mount themselves.
+	 */
+	mount: (target: string | HTMLElement) => void;
+	/**
+	 * Removes the element and releases its frame and subscriptions. You can call it more than once. React removes the element automatically.
+	 */
+	destroy: () => void;
+	/**
+	 * Merges new props into the mounted element. In React, change the component props instead.
+	 */
+	update: (options: Partial<CardCvcElementProps>) => void;
+}
+
+/**
+ * Options for the "cardFields" sub handle's `create("cardCvc")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardCvcElementCreateOptions {
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * The "cardFields" sub-handle, minted by `handle.create("cardFields", …)`. Mounts the sub-controller's elements and carries its actions.
+ * Exclusive slot `entry`. Mount exactly one of: payment | card | cardFields.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface CardFieldsSubHandle {
+	/**
+	 * PCI-isolated hosted card number field. Card numbers never reach the host page.
+	 */
+	create(name: "cardNumber", options?: CardNumberElementCreateOptions): CardNumberElementHandle;
+	/**
+	 * PCI-isolated hosted card expiration field.
+	 */
+	create(name: "cardExpiry", options?: CardExpiryElementCreateOptions): CardExpiryElementHandle;
+	/**
+	 * PCI-isolated hosted card security code field.
+	 */
+	create(name: "cardCvc", options?: CardCvcElementCreateOptions): CardCvcElementHandle;
+	/**
+	 * Advanced method that tokenizes the three fields without creating a confirmation token. It emits `tokenized` to the payments controller. Validation errors appear on the failing field, and the method throws. Use `payments.createConfirmationToken()` to confirm a payment.
+	 */
+	tokenize: (input: { accountId?: string | undefined; }) => Promise<{ token: string; }>;
+	/**
+	 * `payments.createConfirmationToken()` calls this action for `cardFields`. Don't call it directly. It tokenizes the fields and returns the data used to create the confirmation token.
+	 */
+	collect: (input: { billingDetails?: { email?: string | undefined; name?: string | undefined; address?: { country?: string | undefined; line1?: string | undefined; city?: string | undefined; postal_code?: string | undefined; } | undefined; } | undefined; }) => Promise<{ paymentMethod: { type: string; category: string; card: { token: string; }; }; billingDetails: { email: string; name?: string | undefined; address?: { country?: string | undefined; line1?: string | undefined; city?: string | undefined; postal_code?: string | undefined; } | undefined; }; }>;
+	/**
+	 * Merges new props and callbacks into the sub-controller.
+	 */
+	update(options: Partial<CardFieldsSubOptions>): void;
+	/**
+	 * Destroys the sub-controller and its elements, then frees its exclusive slot. A later `create("cardFields")` starts fresh.
+	 */
+	destroy(): void;
+}
+
+/**
+ * Options for `whop.payments.paymentRequest.create()` — the "paymentRequest" resource's create options.
+ * @see https://docs.whop.com/elements/latest/payments/paymentRequest
+ */
+export interface PaymentRequestResourceOptions {
+	/**
+	 * Account ID, prefixed `biz_`, that scopes every client-side call.
+	 */
+	accountId: string;
+	/**
+	 * Three-letter ISO 4217 payment currency code.
+	 */
+	currency: string;
+	/**
+	 * Payment amount in minor units.
+	 */
+	amount: number;
+	/**
+	 * Set only after displaying save consent. Marks the token for `off_session` or `on_session` use.
+	 */
+	setupFutureUsage?: "off_session" | "on_session";
+	/**
+	 * Ask the sheet for the payer's email — the confirmation token requires one.
+	 * @default true
+	 */
+	requestPayerEmail?: boolean;
+	/**
+	 * Ask the sheet for a shipping address (and offer `shippingOptions` when given).
+	 * @default false
+	 */
+	requestShipping?: boolean;
+	/**
+	 * Account ISO 3166-1 alpha-2 country code for the Apple Pay sheet. Omit it to use the account's published registration country. The sheet defaults to `US` when neither is available.
+	 */
+	countryCode?: string;
+	/**
+	 * Line items the sheet lists under the total.
+	 */
+	lineItems?: PaymentRequestLineItem[];
+	/**
+	 * Shipping options the sheet offers when `requestShipping` is set. Display-only — update `amount` from your change handler.
+	 */
+	shippingOptions?: PaymentRequestShippingOption[];
+}
+
+/**
+ * A minted "paymentRequest" resource — returned by `whop.payments.paymentRequest.create()`. Low-level Apple Pay or Google Pay sheet for custom buttons, express checkout, and shipping callbacks. Wallet tiles automate this flow through `payments.createConfirmationToken`. Await `canMakePayment()` to check availability and prime the sheet, then call `show(type)` synchronously in the user-interaction handler. The resolved `ctok` is a `ctok_`-prefixed confirmation token. Confirm it server-side like an element-minted token.
+ * @see https://docs.whop.com/elements/latest/payments/paymentRequest
+ */
+export interface PaymentRequestResource {
+	/**
+	 * Returns availability for each wallet when the account offers it, the device supports it, and this page's origin is approved for the account (first-party whop.com pages are pre-approved; a merchant page needs its domain registered as a payment method domain). Apple Pay on non-WebKit browsers is the desktop iPhone-handoff flow, so mobile devices there report it unavailable — native Apple Pay on iOS browsers is unaffected. `order` ranks the wallets by which sheet is native to the browser — Apple Pay first on Safari, Google Pay first elsewhere — so express buttons can stack best-first. This primes `show()`. Always await it first.
+	 */
+	canMakePayment: () => Promise<WalletAvailability>;
+	/**
+	 * Open the selected wallet sheet after awaiting `canMakePayment()`. Apple requires session creation within the gesture stack. Pass `email` when your page already collected one — the sheet takes it and never asks for a second. With `requestPayerEmail: false`, passing one is required, and the sheet refuses to open without it because confirmation tokens require an email.
+	 * Call synchronously during user activation. Await prerequisites first because browsers revoke activation across asynchronous steps.
+	 */
+	show: (type: "apple_pay" | "google_pay", provided?: { email?: string | undefined; } | undefined) => Promise<PaymentRequestResult>;
+	/**
+	 * The sheet's shipping address changed (redacted pre-authorization: city/state/postal/country only).
+	 * Call `updateWith(…)` exactly once per event or the flow waits until the vendor times out.
+	 * Returns the unsubscribe function.
+	 */
+	onShippingAddressChange(handler: (ev: ShippingAddressChangeEvent) => void): () => void;
+	/**
+	 * The buyer picked a shipping option. Amount-only contract: `updateWith` carries amount/lineItems/shippingOptions/errors.
+	 * Call `updateWith(…)` exactly once per event or the flow waits until the vendor times out.
+	 * Returns the unsubscribe function.
+	 */
+	onShippingOptionChange(handler: (ev: ShippingOptionChangeEvent) => void): () => void;
+	/**
+	 * Fires at sheet open and on card switches with the selected card's redacted billing address (city/state/postal/country only) — reprice the total for the address the charge taxes off. Answer `updateWith({ amount })` in minor units, or `updateWith({})` to keep the current total. Every event is answered exactly once: a slow, thrown, or superseded handler answers keep-current.
+	 * Call `updateWith(…)` exactly once per event or the flow waits until the vendor times out.
+	 * Returns the unsubscribe function.
+	 */
+	onBillingAddressChange(handler: (ev: BillingAddressChangeEvent) => void): () => void;
+	/**
+	 * The sheet created a confirmation token. This is the same result that `show()` returns.
+	 * Returns the unsubscribe function.
+	 */
+	onConfirmationToken(handler: (ev: PaymentRequestResult) => void): () => void;
+	/**
+	 * The buyer dismissed the sheet.
+	 * Returns the unsubscribe function.
+	 */
+	onCancel(handler: () => void): () => void;
+}
+
+/**
+ * The Payments handle, returned by `whop.payments.create()` (React: `usePayments()`). Mounts the elements and carries the controller's actions.
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface PaymentsHandle {
+	/**
+	 * Shows available payment methods and collects the selected method's required fields and disclosures. Use `change` to enable your pay button. In its activation handler, call `payments.createConfirmationToken()`. Confirm the token server-side, then pass any pending step to `payments.handleNextAction(…)`. Use `addressChange` for address-dependent updates.
+	 * Exclusive slot `entry`. Mount exactly one of: payment | card | cardFields.
+	 */
+	create(name: "payment", options?: PaymentElementCreateOptions): PaymentElementHandle;
+	/**
+	 * Collects a billing or shipping address. Fields, order, and validation follow the selected country. Includes street autocomplete and methods to read or validate the address.
+	 */
+	create(name: "address", options?: AddressElementCreateOptions): AddressElementHandle;
+	/**
+	 * Prearranged fields for card number, expiration, and security code. Create with `payments.create("card")`, enable your payment button from `onChange`, and confirm with `payments.createConfirmationToken()`. Card numbers remain in PCI-isolated hosted fields. `layout` supports `stacked` (default) and `compact`.
+	 * Exclusive slot `entry`. Mount exactly one of: payment | card | cardFields.
+	 */
+	create(name: "card", options?: CardElementCreateOptions): CardElementHandle;
+	/**
+	 * Collects the buyer's email and passes it to `payments.createConfirmationToken()` while mounted. Explicit `billingDetails.email` wins. A matching Whop account shows optional sign-in with code verification. Successful sign-in unlocks saved payment methods in the payment element. Buyers can continue as guests.
+	 */
+	create(name: "email", options?: EmailElementCreateOptions): EmailElementHandle;
+	/**
+	 * Collects a business tax registration accepted by the API. Labels use buyer-facing names. The placeholder matches the selected format. `country` preselects a type. `onChange` emits committed pairs. The host supplies API validation errors.
+	 */
+	create(name: "taxId", options?: TaxIdElementCreateOptions): TaxIdElementHandle;
+	/**
+	 * Whop's merchant-of-record notice: the Whop wordmark with links to the buyer terms and privacy policy. Required — the other payments elements stay in their loading state until it is mounted, and payments cannot be confirmed without it.
+	 */
+	create(name: "branding", options?: BrandingElementCreateOptions): BrandingElementHandle;
+	/**
+	 * Creates a confirmation token for the selected method from your pay button. Pass the checkout's billing details. They must include `email`. Cards also need `name` and an address containing `line1` and `country`. Wallet selections open their sheet during the pay-button interaction. Confirm the returned `confirmationToken` server-side, then call `WhopElements.payments.handleNextAction(…)`.
+	 * Runs on your page (host-side), not in the controller iframe.
+	 */
+	createConfirmationToken: (input: { billingDetails?: { email?: string | undefined; name?: string | undefined; address?: { country?: string | undefined; line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; } | undefined; } | undefined; }) => Promise<{ confirmationToken: string; type: string; }>;
+	/**
+	 * Three separately mountable, PCI-isolated card fields for custom layouts: number, expiration, and security code. Create with `payments.create("cardFields")`, place each field, enable your payment button from `onChange`, and confirm with `payments.createConfirmationToken()`. Card numbers remain in hosted fields.
+	 * Exclusive slot `entry`. Mount exactly one of: payment | card | cardFields.
+	 */
+	create(name: "cardFields", options?: CardFieldsSubOptions): CardFieldsSubHandle;
+	/**
+	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
+	 */
+	update(options: Partial<PaymentsOptions>): void;
+	/**
+	 * Destroys every element and sub-controller this handle created, removes the controller frame, and releases its subscriptions. You can call it more than once, but a destroyed handle refuses any other call — create a new handle to start over. React removes the group automatically when the provider unmounts.
+	 */
+	destroy(): void;
+}
+
+/**
+ * Payments's static actions, callable with nothing mounted: `whop.payments.<method>()` (React: `useWhop().payments.<method>()`).
+ * @see https://docs.whop.com/elements/latest/payments/overview
+ */
+export interface PaymentsStatics {
+	/**
+	 * Completes a confirmed payment's pending step without mounting an element. `clientSecret` identifies the payment. You don't need a payment ID. Inline steps open in a dialog and resolve with `redirected: false`. Dismissing the dialog returns the payment's current status, which can remain pending. Full-page steps redirect with `redirected: true` to `return_url`, or a hosted receipt when the payment has no return URL. They reject with code `FULL_PAGE_STEP_IN_FRAME` inside subordinate frames. Set `returnUrl` to update the destination before presentation. An update failure rejects before any step runs. Inline steps never navigate to that URL. A payment with no pending step resolves immediately.
+	 */
+	handleNextAction: (input: { clientSecret: string; returnUrl?: string | undefined; pollIntervalMs?: number | undefined; }) => Promise<{ status: string; redirected: boolean; lastPaymentError: { code?: string | null | undefined; decline_code?: string | null | undefined; message?: string | null | undefined; } | null; }>;
+	/**
+	 * Low-level Apple Pay or Google Pay sheet for custom buttons, express checkout, and shipping callbacks. Wallet tiles automate this flow through `payments.createConfirmationToken`. Await `canMakePayment()` to check availability and prime the sheet, then call `show(type)` synchronously in the user-interaction handler. The resolved `ctok` is a `ctok_`-prefixed confirmation token. Confirm it server-side like an element-minted token.
+	 * Mint with `whop.payments.paymentRequest.create(options)` — nothing needs to be mounted.
+	 */
+	paymentRequest: { create(options: PaymentRequestResourceOptions): PaymentRequestResource };
+}
+
+/**
+ * Host-probed wallet availability after checking offered methods, device capability, and Google Pay origin approval.
+ * Declared from the app's `WalletAvailability`, referenced by a host-capability surface.
+ */
+export interface WalletAvailability {
+	applePay: boolean;
+	googlePay: boolean;
+	/**
+	 * The wallets ranked by which sheet is native to this browser — Apple Pay first on WebKit, Google Pay first everywhere else — so express buttons can stack best-first. Absent on consumer-stated availability (previews) and on wires that predate it. An inline union, not payment-request's WalletSheetType: that module already imports this one.
+	 */
+	order?: ("apple_pay" | "google_pay")[] | undefined;
+}
+
+/**
+ * The slice of a matrix card network the fields need: identity plus the API-served square art.
+ * Declared from the app's `CardNetworkArt`, referenced by a host-capability surface.
+ */
+export interface CardNetworkArt {
+	brand: "visa" | "mastercard" | "amex" | "discover" | "jcb" | "diners" | "unionpay" | "elo" | "maestro";
+	icons: { square: { light: { svg: string; }; dark: { svg: string; }; }; };
+}
+
+/**
+ * Declared from the app's `PaymentRequestLineItem`, referenced by a host-capability surface.
+ */
+export interface PaymentRequestLineItem {
+	label: string;
+	/**
+	 * Minor units, same as `amount`.
+	 */
+	amount: number;
+}
+
+/**
+ * Declared from the app's `PaymentRequestShippingOption`, referenced by a host-capability surface.
+ */
+export interface PaymentRequestShippingOption {
+	id: string;
+	label: string;
+	detail?: string | undefined;
+	/**
+	 * Minor-unit display value. The resource doesn't calculate shipping. Update `amount` from your handler.
+	 */
+	amount: number;
+}
+
+/**
+ * Declared from the app's `PaymentRequestAddress`, referenced by a host-capability surface.
+ */
+export interface PaymentRequestAddress {
+	line1?: string | undefined;
+	line2?: string | undefined;
+	city?: string | undefined;
+	state?: string | undefined;
+	postal_code?: string | undefined;
+	country?: string | undefined;
+	recipient?: string | undefined;
+	phone?: string | undefined;
+}
+
+/**
+ * Declared from the app's `PaymentRequestResult`, referenced by a host-capability surface.
+ */
+export interface PaymentRequestResult {
+	/**
+	 * Confirmation token ID, prefixed `ctok_`. Confirm it server-side with your secret key.
+	 */
+	ctok: string;
+	type: "apple_pay" | "google_pay";
+	payer: { email?: string | undefined; name?: string | undefined; phone?: string | undefined; };
+	shipping: { address?: PaymentRequestAddress | undefined; option?: PaymentRequestShippingOption | undefined; } | null;
+}
+
+/**
+ * Declared from the app's `PaymentRequestError`, referenced by a host-capability surface.
+ */
+export interface PaymentRequestError {
+	code?: "shipping_address_invalid" | "shipping_address_unserviceable" | "shipping_option_invalid" | "other" | undefined;
+	message: string;
+}
+
+/**
+ * Declared from the app's `PaymentRequestUpdate`, referenced by a host-capability surface.
+ */
+export interface PaymentRequestUpdate {
+	amount?: number | undefined;
+	lineItems?: PaymentRequestLineItem[] | undefined;
+	shippingOptions?: PaymentRequestShippingOption[] | undefined;
+	errors?: PaymentRequestError[] | undefined;
+}
+
+/**
+ * Declared from the app's `ShippingAddressChangeEvent`, referenced by a host-capability surface.
+ */
+export interface ShippingAddressChangeEvent {
+	/**
+	 * Vendor-normalized pre-authorization address. It includes only city, state, postal code, and country.
+	 */
+	address: PaymentRequestAddress;
+	/**
+	 * Call this exactly once, or the sheet stalls until the vendor times it out.
+	 */
+	updateWith: (update: PaymentRequestUpdate) => void;
+}
+
+/**
+ * Declared from the app's `ShippingOptionChangeEvent`, referenced by a host-capability surface.
+ */
+export interface ShippingOptionChangeEvent {
+	/**
+	 * Always includes the selected `id`. It includes the full option when it matches one of yours.
+	 */
+	option: { id: string; } & Partial<PaymentRequestShippingOption>;
+	updateWith: (update: PaymentRequestUpdate) => void;
+}
+
+/**
+ * Declared from the app's `BillingAddressChangeEvent`, referenced by a host-capability surface.
+ */
+export interface BillingAddressChangeEvent {
+	/**
+	 * Vendor-normalized pre-authorization billing address. It includes only city, state, postal code, and country.
+	 */
+	address: PaymentRequestAddress;
+	/**
+	 * Call this exactly once. An event left unanswered keeps the current total when the reply deadline passes.
+	 */
+	updateWith: (update: PaymentRequestUpdate) => void;
+}