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

package/payments.d.cts

@@ -12,9 +12,13 @@
 export type PaymentsOptions = (
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection 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";
 		/**
 		 * 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 +32,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.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -50,11 +54,15 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection surface.
+		 * Account ID, prefixed `biz_`. 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";
+		/**
+		 * Lowercase three-letter ISO 4217 currency code. It filters the payment-method matrix.
 		 */
 		currency: string;
 		/**
@@ -74,7 +82,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.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -96,15 +104,73 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection 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.
 		 */
-		accountId?: undefined;
+		mode: "setup";
+		/**
+		 * 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.
+		 */
+		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_`. 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?: 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 +190,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.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -166,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"
@@ -226,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"
@@ -246,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.
 	 */
@@ -272,6 +338,11 @@ export interface PaymentElementCreateOptions {
  * @see https://docs.whop.com/elements/latest/payments/address
  */
 export interface AddressElementProps {
+	/**
+	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
+	 * @default "billing"
+	 */
+	mode?: "billing" | "shipping";
 	/**
 	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
 	 * @default "full"
@@ -287,11 +358,6 @@ export interface AddressElementProps {
 	 * @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"
@@ -323,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" | "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: "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 ""
@@ -368,6 +434,11 @@ export interface AddressElementHandle {
  * @see https://docs.whop.com/elements/latest/payments/address
  */
 export interface AddressElementCreateOptions {
+	/**
+	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
+	 * @default "billing"
+	 */
+	mode?: "billing" | "shipping";
 	/**
 	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
 	 * @default "full"
@@ -383,11 +454,6 @@ export interface AddressElementCreateOptions {
 	 * @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"
@@ -419,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" | "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: "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 ""
@@ -950,6 +1016,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
@@ -975,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>;
 	/**
@@ -1045,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.
@@ -1070,7 +1141,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 +1220,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/payments.d.ts

@@ -12,9 +12,13 @@
 export type PaymentsOptions = (
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection 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";
 		/**
 		 * 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 +32,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.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -50,11 +54,15 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection surface.
+		 * Account ID, prefixed `biz_`. 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";
+		/**
+		 * Lowercase three-letter ISO 4217 currency code. It filters the payment-method matrix.
 		 */
 		currency: string;
 		/**
@@ -74,7 +82,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.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -96,15 +104,73 @@ export type PaymentsOptions = (
 	}
 	| {
 		/**
-		 * Account ID, prefixed `biz_`. Omit only when calling static methods without a collection 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.
 		 */
-		accountId?: undefined;
+		mode: "setup";
+		/**
+		 * 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.
+		 */
+		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_`. 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?: 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 +190,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.
 		 */
 		setupFutureUsage?: "off_session" | "on_session";
 		/**
@@ -166,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"
@@ -226,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"
@@ -246,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.
 	 */
@@ -272,6 +338,11 @@ export interface PaymentElementCreateOptions {
  * @see https://docs.whop.com/elements/latest/payments/address
  */
 export interface AddressElementProps {
+	/**
+	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
+	 * @default "billing"
+	 */
+	mode?: "billing" | "shipping";
 	/**
 	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
 	 * @default "full"
@@ -287,11 +358,6 @@ export interface AddressElementProps {
 	 * @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"
@@ -323,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" | "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: "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 ""
@@ -368,6 +434,11 @@ export interface AddressElementHandle {
  * @see https://docs.whop.com/elements/latest/payments/address
  */
 export interface AddressElementCreateOptions {
+	/**
+	 * Browser autocomplete purpose: `billing` (default) or `shipping`.
+	 * @default "billing"
+	 */
+	mode?: "billing" | "shipping";
 	/**
 	 * `full` (default) stacks labeled fields. `compact` groups placeholder-labeled fields within one border.
 	 * @default "full"
@@ -383,11 +454,6 @@ export interface AddressElementCreateOptions {
 	 * @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"
@@ -419,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" | "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: "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 ""
@@ -950,6 +1016,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
@@ -975,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>;
 	/**
@@ -1045,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.
@@ -1070,7 +1141,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 +1220,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.
 	 */
@@ -301,7 +301,7 @@ export interface ActionRequiredItem {
 	requirement: string;
 	type: string;
 	label: string;
-	source?: "identity" | "payout" | "audit" | "card_issuing" | "bank" | "ads" | "application" | undefined;
+	source?: "identity" | "payout" | "audit" | "card_issuing" | "bank" | "ads" | "application" | "airwallex" | undefined;
 	optional?: boolean | undefined;
 	options?: string[] | undefined;
 	errors?: { code: string; reason: string; }[] | undefined;