@whop/elements 1.0.0-beta.3 → 1.0.0-beta.4

package/payments.d.ts

@@ -12,9 +12,17 @@
 export type PaymentsOptions = (
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection surface.
+		 * Account ID, prefixed `biz_`. Required for PaymentsElement; omit only when calling static methods without an account surface.
 		 */
 		accountId: string;
+		/**
+		 * Mount mode, `payment` by default. `setup` saves a payment method and charges nothing, now or later: only methods that can be saved are offered and amount bounds do not apply. Confirm with `createConfirmationToken()`, then create the setup intent server-side.
+		 */
+		mode?: "payment";
+		/**
+		 * Scoped bearer token for PaymentsElement. Requires `payment:basic:read`; buyer emails additionally require `member:email:read`. Omit only with a same-origin Whop session.
+		 */
+		accessToken?: 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.
 		 */
@@ -28,7 +36,7 @@ export type PaymentsOptions = (
 		 */
 		returnUrl?: string;
 		/**
-		 * Displays consent to save the payment method and marks the token for `off_session` or `on_session` use.
+		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts, and displays the save consent.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -50,11 +58,19 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection surface.
+		 * Account ID, prefixed `biz_`. Required for PaymentsElement; omit only when calling static methods without an account surface.
 		 */
 		accountId: string;
 		/**
-		 * Lowercase three-letter ISO 4217 payment currency code. It filters the payment-method matrix.
+		 * Mount mode, `payment` by default. `setup` saves a payment method and charges nothing, now or later: only methods that can be saved are offered and amount bounds do not apply. Confirm with `createConfirmationToken()`, then create the setup intent server-side.
+		 */
+		mode?: "payment";
+		/**
+		 * Scoped bearer token for PaymentsElement. Requires `payment:basic:read`; buyer emails additionally require `member:email:read`. Omit only with a same-origin Whop session.
+		 */
+		accessToken?: string;
+		/**
+		 * Lowercase three-letter ISO 4217 currency code. It filters the payment-method matrix.
 		 */
 		currency: string;
 		/**
@@ -74,7 +90,7 @@ export type PaymentsOptions = (
 		 */
 		returnUrl?: string;
 		/**
-		 * Displays consent to save the payment method and marks the token for `off_session` or `on_session` use.
+		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts, and displays the save consent.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -96,15 +112,81 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection surface.
+		 * Account ID, prefixed `biz_`. Required for PaymentsElement; omit only when calling static methods without an account surface.
+		 */
+		accountId: string;
+		/**
+		 * Mount mode, `payment` by default. `setup` saves a payment method and charges nothing, now or later: only methods that can be saved are offered and amount bounds do not apply. Confirm with `createConfirmationToken()`, then create the setup intent server-side.
 		 */
-		accountId?: undefined;
+		mode: "setup";
+		/**
+		 * Scoped bearer token for PaymentsElement. Requires `payment:basic:read`; buyer emails additionally require `member:email:read`. Omit only with a same-origin Whop session.
+		 */
+		accessToken?: string;
+		/**
+		 * Lowercase three-letter ISO 4217 currency code. It filters the payment-method matrix.
+		 */
+		currency: 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?: undefined;
 		/**
-		 * Lowercase three-letter ISO 4217 payment currency code. It filters the payment-method matrix.
+		 * 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?: { 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;
+		/**
+		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts, and displays the save consent.
+		 */
+		setupFutureUsage?: "off_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_`. Required for PaymentsElement; omit only when calling static methods without an account surface.
+		 */
+		accountId?: string;
+		/**
+		 * Scoped bearer token for PaymentsElement. Requires `payment:basic:read`; buyer emails additionally require `member:email:read`. Omit only with a same-origin Whop session.
+		 */
+		accessToken?: string;
+		/**
+		 * Mount mode, `payment` by default. `setup` saves a payment method and charges nothing, now or later: only methods that can be saved are offered and amount bounds do not apply. Confirm with `createConfirmationToken()`, then create the setup intent server-side.
+		 */
+		mode?: 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 currency code. It filters the payment-method matrix.
 		 */
 		currency?: undefined;
 		/**
@@ -124,7 +206,7 @@ export type PaymentsOptions = (
 		 */
 		returnUrl?: string;
 		/**
-		 * Displays consent to save the payment method and marks the token for `off_session` or `on_session` use.
+		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts, and displays the save consent.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -155,6 +237,120 @@ export type PaymentsOptions = (
 	locale?: import("./_framework.js").WhopElementsLocale;
 };
 
+/**
+ * Consumer props for the "payments" element. Set at create (or as `<PaymentsElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/payments/payments
+ */
+export interface PaymentsElementProps {
+	/**
+	 * Show the header action menu, Export button, and table settings button.
+	 * @default true
+	 */
+	showActions?: boolean;
+	/**
+	 * Show the three-dot action menu on each payment row.
+	 * @default true
+	 */
+	showRowActions?: boolean;
+	/**
+	 * Show the six payment status boxes above the filters.
+	 * @default true
+	 */
+	showStatusTabs?: boolean;
+	/**
+	 * Show the tracking column and filter for physical-product accounts. Tracking data requires `shipment:basic:read`.
+	 * @default true
+	 */
+	showTracking?: boolean;
+}
+
+/**
+ * The live handle for a mounted "payments" element. Returned by `create("payments")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/payments/payments
+ */
+export interface PaymentsElementHandle {
+	/**
+	 * Reload payments after a refund or another change.
+	 */
+	refresh: () => 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<PaymentsElementProps>) => void;
+}
+
+/**
+ * Options for `create("payments")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const payments = payments.create("payments", {}); // this interface: props + on<Event> callbacks
+ * payments.mount("#payments-payments");
+ * ```
+ * @see https://docs.whop.com/elements/latest/payments/payments
+ */
+export interface PaymentsElementCreateOptions {
+	/**
+	 * Show the header action menu, Export button, and table settings button.
+	 * @default true
+	 */
+	showActions?: boolean;
+	/**
+	 * Show the three-dot action menu on each payment row.
+	 * @default true
+	 */
+	showRowActions?: boolean;
+	/**
+	 * Show the six payment status boxes above the filters.
+	 * @default true
+	 */
+	showStatusTabs?: boolean;
+	/**
+	 * Show the tracking column and filter for physical-product accounts. Tracking data requires `shipment:basic:read`.
+	 * @default true
+	 */
+	showTracking?: boolean;
+	/**
+	 * Open payment details in your application.
+	 */
+	onPaymentSelected?: ((payload: { paymentId: string; }) => void);
+	/**
+	 * Open the invoice in your application.
+	 */
+	onInvoiceRequested?: ((payload: { paymentId: string; }) => void);
+	/**
+	 * Open the buyer in your application.
+	 */
+	onUserSelected?: ((payload: { userId: string; }) => void);
+	/**
+	 * The viewer requested a refund. Your application must confirm and authorize it server-side. Refund controls are enabled only when this callback is provided.
+	 */
+	onRefundRequested?: ((payload: { paymentIds: string[]; }) => void);
+	/**
+	 * Open the account’s payment settings in your application.
+	 */
+	onSettingsRequested?: ((payload: Record<string, never>) => 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 "payment" element. Set at create (or as `<PaymentElement />` JSX props), and updatable live via `update()`.
  * @see https://docs.whop.com/elements/latest/payments/payment
@@ -273,10 +469,10 @@ export interface PaymentElementCreateOptions {
  */
 export interface AddressElementProps {
 	/**
-	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
-	 * @default "full"
+	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
+	 * @default "billing"
 	 */
-	layout?: "full" | "compact";
+	mode?: "billing" | "shipping";
 	/**
 	 * Address line 2: always visible (default), revealed by a text button (`toggle`), or never collected.
 	 * @default "always"
@@ -288,10 +484,10 @@ export interface AddressElementProps {
 	 */
 	name?: "split" | "combined" | "none";
 	/**
-	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
-	 * @default "billing"
+	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
+	 * @default "full"
 	 */
-	mode?: "billing" | "shipping";
+	layout?: "full" | "compact";
 	/**
 	 * `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"
@@ -323,7 +519,7 @@ export interface AddressElementProps {
 	/**
 	 * 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; })[];
+	customFields?: ({ key: string; label: string; type: "text" | "select" | "phone" | "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 ""
@@ -369,10 +565,10 @@ export interface AddressElementHandle {
  */
 export interface AddressElementCreateOptions {
 	/**
-	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
-	 * @default "full"
+	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
+	 * @default "billing"
 	 */
-	layout?: "full" | "compact";
+	mode?: "billing" | "shipping";
 	/**
 	 * Address line 2: always visible (default), revealed by a text button (`toggle`), or never collected.
 	 * @default "always"
@@ -384,10 +580,10 @@ export interface AddressElementCreateOptions {
 	 */
 	name?: "split" | "combined" | "none";
 	/**
-	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
-	 * @default "billing"
+	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
+	 * @default "full"
 	 */
-	mode?: "billing" | "shipping";
+	layout?: "full" | "compact";
 	/**
 	 * `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"
@@ -419,7 +615,7 @@ export interface AddressElementCreateOptions {
 	/**
 	 * 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; })[];
+	customFields?: ({ key: string; label: string; type: "text" | "select" | "phone" | "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 ""
@@ -950,6 +1146,11 @@ export interface PaymentRequestResourceOptions {
 	 * @default true
 	 */
 	requestPayerEmail?: boolean;
+	/**
+	 * Ask the sheet for the payer's phone number, delivered as `payer.phone` on the result — in E.164 where it parses against the country of the contact that supplied it, as the wallet gave it otherwise; `payer.country` is the billing country. Google Pay collects it through the billing address the sheet already asks for.
+	 * @default false
+	 */
+	requestPayerPhone?: boolean;
 	/**
 	 * Ask the sheet for a shipping address (and offer `shippingOptions` when given).
 	 * @default false
@@ -1018,6 +1219,10 @@ export interface PaymentRequestResource {
  * @see https://docs.whop.com/elements/latest/payments/overview
  */
 export interface PaymentsHandle {
+	/**
+	 * The dashboard payments table with status cards, search, filters, sorting, row selection, CSV export, column settings, and pagination. Reads all payment pages to compute complete counts and filter locally; intended for accounts with modest payment histories. Customer details and refunds are handed to your application through events.
+	 */
+	create(name: "payments", options?: PaymentsElementCreateOptions): PaymentsElementHandle;
 	/**
 	 * 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.
@@ -1070,7 +1275,7 @@ export interface PaymentsHandle {
  */
 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. Inside an iframe they navigate the top-level tab. If the embedding page refuses that navigation, they reject with code `TAB_NAVIGATION_BLOCKED`, and the payment stays pending. 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.
+	 * 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. Inside an iframe they navigate the top-level tab. If the embedding page refuses that navigation, they reject with code `TAB_NAVIGATION_BLOCKED`, and the payment stays pending. 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 whose charge is still being decided is polled until a step appears or it settles; a decided payment with no 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; }>;
 	/**
@@ -1149,7 +1354,7 @@ export interface PaymentRequestResult {
 	 */
 	ctok: string;
 	type: "apple_pay" | "google_pay";
-	payer: { email?: string | undefined; name?: string | undefined; phone?: string | undefined; };
+	payer: { email?: string | undefined; name?: string | undefined; phone?: string | undefined; country?: string | undefined; };
 	shipping: { address?: PaymentRequestAddress | undefined; option?: PaymentRequestShippingOption | undefined; } | null;
 }
 

package/verifications.d.cts

@@ -237,7 +237,7 @@ export interface RfiElementCreateOptions {
 	/**
 	 * One group of requirements was answered. Fires per group, not once per field.
 	 */
-	onSubmitted?: ((payload: { source: "identity" | "payout" | "audit" | "card_issuing" | "bank" | "ads" | "application"; itemIds: string[]; }) => void);
+	onSubmitted?: ((payload: { source: "identity" | "payout" | "audit" | "card_issuing" | "bank" | "ads" | "application" | "airwallex"; itemIds: string[]; }) => void);
 	/**
 	 * Nothing is outstanding any more. Fires when the element first observes an empty list, including on mount.
 	 */

package/verifications.d.ts

@@ -237,7 +237,7 @@ export interface RfiElementCreateOptions {
 	/**
 	 * One group of requirements was answered. Fires per group, not once per field.
 	 */
-	onSubmitted?: ((payload: { source: "identity" | "payout" | "audit" | "card_issuing" | "bank" | "ads" | "application"; itemIds: string[]; }) => void);
+	onSubmitted?: ((payload: { source: "identity" | "payout" | "audit" | "card_issuing" | "bank" | "ads" | "application" | "airwallex"; itemIds: string[]; }) => void);
 	/**
 	 * Nothing is outstanding any more. Fires when the element first observes an empty list, including on mount.
 	 */