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

package/payments.d.cts

@@ -12,17 +12,13 @@
 export type PaymentsOptions = (
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Required for PaymentsElement; omit only when calling static methods without an account surface.
+		 * Account ID, prefixed `biz_`. 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.
 		 */
@@ -36,7 +32,7 @@ export type PaymentsOptions = (
 		 */
 		returnUrl?: string;
 		/**
-		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts, and displays the save consent.
+		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -58,17 +54,13 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Required for PaymentsElement; omit only when calling static methods without an account surface.
+		 * Account ID, prefixed `biz_`. 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;
 		/**
 		 * Lowercase three-letter ISO 4217 currency code. It filters the payment-method matrix.
 		 */
@@ -90,7 +82,7 @@ export type PaymentsOptions = (
 		 */
 		returnUrl?: string;
 		/**
-		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts, and displays the save consent.
+		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -112,17 +104,13 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Required for PaymentsElement; omit only when calling static methods without an account surface.
+		 * Account ID, prefixed `biz_`. 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: "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.
 		 */
@@ -148,7 +136,7 @@ export type PaymentsOptions = (
 		 */
 		returnUrl?: string;
 		/**
-		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts, and displays the save consent.
+		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts.
 		 */
 		setupFutureUsage?: "off_session";
 		/**
@@ -170,13 +158,9 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Required for PaymentsElement; omit only when calling static methods without an account surface.
+		 * Account ID, prefixed `biz_`. 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.
 		 */
@@ -206,7 +190,7 @@ export type PaymentsOptions = (
 		 */
 		returnUrl?: string;
 		/**
-		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts, and displays the save consent.
+		 * A setup saves the payment method for `off_session` use, the only usage a setup accepts.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -237,120 +221,6 @@ 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
@@ -362,10 +232,10 @@ export interface PaymentElementProps {
 	 */
 	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. With an installment plan selected, it narrows to the countries the plan serves — the billing country is the transaction country the charge processes under. It locks when only one is available.
+	 * 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. `phone: 'never'` hides only the billing phone input when your form already collects it; pass `billingDetails.phone` to `createConfirmationToken` for methods that require it. Pass the address to `createConfirmationToken` instead. The country selector includes only countries supported by the method and payment currency. With an installment plan selected, it narrows to the countries the plan serves — the billing country is the transaction country the charge processes under. It locks when only one is available.
 	 * @default {"billingDetails":"minimal"}
 	 */
-	fields?: { billingDetails?: "full" | "minimal" | "never" | undefined; };
+	fields?: { billingDetails?: "full" | "minimal" | "never" | undefined; phone?: "never" | "auto" | 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"
@@ -422,10 +292,10 @@ export interface PaymentElementCreateOptions {
 	 */
 	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. With an installment plan selected, it narrows to the countries the plan serves — the billing country is the transaction country the charge processes under. It locks when only one is available.
+	 * 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. `phone: 'never'` hides only the billing phone input when your form already collects it; pass `billingDetails.phone` to `createConfirmationToken` for methods that require it. Pass the address to `createConfirmationToken` instead. The country selector includes only countries supported by the method and payment currency. With an installment plan selected, it narrows to the countries the plan serves — the billing country is the transaction country the charge processes under. It locks when only one is available.
 	 * @default {"billingDetails":"minimal"}
 	 */
-	fields?: { billingDetails?: "full" | "minimal" | "never" | undefined; };
+	fields?: { billingDetails?: "full" | "minimal" | "never" | undefined; phone?: "never" | "auto" | 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"
@@ -442,9 +312,9 @@ export interface PaymentElementCreateOptions {
 	 */
 	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.
+	 * 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. `requiresBillingPhone` indicates whether the selected method requires a phone in billing details, including when `fields.phone` disables its input. `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);
+	onChange?: ((payload: { complete: boolean; type?: string | undefined; supportsBuyerFee?: boolean | undefined; requiresBillingPhone?: 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.
 	 */
@@ -473,6 +343,11 @@ export interface AddressElementProps {
 	 * @default "billing"
 	 */
 	mode?: "billing" | "shipping";
+	/**
+	 * `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"
@@ -483,11 +358,6 @@ export interface AddressElementProps {
 	 * @default "combined"
 	 */
 	name?: "split" | "combined" | "none";
-	/**
-	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
-	 * @default "full"
-	 */
-	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"
@@ -519,7 +389,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" | "select" | "phone" | "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: "phone" | "text" | "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 ""
@@ -569,6 +439,11 @@ export interface AddressElementCreateOptions {
 	 * @default "billing"
 	 */
 	mode?: "billing" | "shipping";
+	/**
+	 * `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"
@@ -579,11 +454,6 @@ export interface AddressElementCreateOptions {
 	 * @default "combined"
 	 */
 	name?: "split" | "combined" | "none";
-	/**
-	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
-	 * @default "full"
-	 */
-	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"
@@ -615,7 +485,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" | "select" | "phone" | "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: "phone" | "text" | "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 ""
@@ -1176,7 +1046,7 @@ export interface PaymentRequestResourceOptions {
  */
 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 and verified as a [payment method domain](/api-reference/beta/payment-method-domains/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.
+	 * 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 and verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain), and offering Google Pay there is subject to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos)). 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>;
 	/**
@@ -1219,10 +1089,6 @@ 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.
@@ -1250,10 +1116,10 @@ export interface PaymentsHandle {
 	 */
 	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(…)`.
+	 * Creates a confirmation token for the selected method from your pay button. Pass the checkout's billing details. They must include `email`. Supply `phone` for methods that require it when billing collection is disabled. 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; }>;
+	createConfirmationToken: (input: { billingDetails?: { email?: string | undefined; name?: string | undefined; phone?: 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.