@whop/elements 1.0.0-beta.2 → 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
@@ -166,7 +362,7 @@ 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. 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. 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; };
@@ -226,7 +422,7 @@ 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. 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. 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; };
@@ -246,7 +442,7 @@ 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; when the buyer picks a card installment plan, `countries` narrows to the countries that plan serves for the payment currency. `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. `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);
 	/**
@@ -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 ""
@@ -490,9 +686,9 @@ export interface CardElementCreateOptions {
 	 */
 	layout?: "compact" | "stacked";
 	/**
-	 * Fires when card fields change. `complete` becomes true after the buyer fills all three. Use it to enable confirmation. `brand` is the detected card network. `funding` is the detected funding type (`credit`, `debit`, or `prepaid`), `null` until the number identifies one.
+	 * Fires when card fields change. `complete` becomes true after the buyer fills all three. Use it to enable confirmation. `brand` is the detected card network. `funding` is the detected funding type (`credit`, `debit`, or `prepaid`), `null` until the number identifies one. `issuingCountry` is the lowercase two-letter code of the country the card was issued in, `null` until the number identifies one.
 	 */
-	onChange?: ((payload: { complete: boolean; brand: string; funding: string | null; }) => void);
+	onChange?: ((payload: { complete: boolean; brand: string; funding: string | null; issuingCountry: string | null; }) => void);
 	/**
 	 * Runs after the loading skeleton first paints and before `onReady`.
 	 */
@@ -602,7 +798,7 @@ export interface TaxIdElementProps {
 	 */
 	disabled?: boolean;
 	/**
-	 * ISO 3166-1 alpha-2 buyer country used to preselect the type. `AR` selects `ar_cuit`. EU and unmapped or empty values select `eu_vat`. Other uniquely mapped countries select their type. A manual selection persists across country changes.
+	 * ISO 3166-1 alpha-2 buyer country used to preselect the type. `AR` selects `ar_cuit`, `LI` selects `li_uid`. EU and unmapped or empty values select `eu_vat`. Other mapped countries select their own first type. A manual selection persists across country changes.
 	 * @default ""
 	 */
 	country?: string;
@@ -652,7 +848,7 @@ export interface TaxIdElementCreateOptions {
 	 */
 	disabled?: boolean;
 	/**
-	 * ISO 3166-1 alpha-2 buyer country used to preselect the type. `AR` selects `ar_cuit`. EU and unmapped or empty values select `eu_vat`. Other uniquely mapped countries select their type. A manual selection persists across country changes.
+	 * ISO 3166-1 alpha-2 buyer country used to preselect the type. `AR` selects `ar_cuit`, `LI` selects `li_uid`. EU and unmapped or empty values select `eu_vat`. Other mapped countries select their own first type. A manual selection persists across country changes.
 	 * @default ""
 	 */
 	country?: string;
@@ -751,9 +947,9 @@ export interface CardFieldsSubOptions {
 	 */
 	networks?: CardNetworkArt[];
 	/**
-	 * Fires when completeness changes. `complete` becomes true after the buyer fills all three fields. Use it to enable confirmation. `brand` is the detected card network. `funding` is the detected funding type (`credit`, `debit`, or `prepaid`), `null` until the number identifies one.
+	 * Fires when completeness changes. `complete` becomes true after the buyer fills all three fields. Use it to enable confirmation. `brand` is the detected card network. `funding` is the detected funding type (`credit`, `debit`, or `prepaid`), `null` until the number identifies one. `issuingCountry` is the lowercase two-letter code of the country the card was issued in, `null` until the number identifies one.
 	 */
-	onChange?: ((payload: { complete: boolean; brand: string; funding: string | null; }) => void);
+	onChange?: ((payload: { complete: boolean; brand: string; funding: string | null; issuingCountry: string | null; }) => void);
 }
 
 /**
@@ -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
@@ -975,7 +1176,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 as a payment method domain). Apple Pay on non-WebKit browsers is the desktop iPhone-handoff flow, so mobile devices there report it unavailable — native Apple Pay on iOS browsers is unaffected. `order` ranks the wallets by which sheet is native to the browser — Apple Pay first on Safari, Google Pay first elsewhere — so express buttons can stack best-first. This primes `show()`. Always await it first.
+	 * 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.
 	 */
 	canMakePayment: () => Promise<WalletAvailability>;
 	/**
@@ -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. They reject with code `FULL_PAGE_STEP_IN_FRAME` inside subordinate frames. Set `returnUrl` to update the destination before presentation. An update failure rejects before any step runs. Inline steps never navigate to that URL. A payment with no pending step resolves immediately.
+	 * 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/tracking.d.cts

@@ -20,7 +20,7 @@ export interface TrackingOptions {
 	 */
 	accessToken?: string;
 	/**
-	 * Where person links lead on your site. `person` is an absolute-URL template with two placeholders, each replaced URL-encoded per row: `{personId}` is the stable `prsn_…` ID, identical for the same person on every surface — key your page on it; `{identifier}` is the most human-meaningful identifier the surface has (a user ID or email where known), so it can differ across surfaces. It must be absolute (`https://…`) — inside an element frame a relative URL would resolve against the frame, so one is treated as unset. Unset, a person click raises `personOpened` on its element instead. `people` and `events` base URLs are accepted for symmetry with the ads handle but nothing under this handle renders them.
+	 * Where person links lead on your site. `person` is an absolute-URL template with two placeholders, each replaced URL-encoded per row: `{personId}` is the stable `prsn_…` ID, identical for the same person on every surface, so key your page on it and mount the `person` element there; `{identifier}` is the most human-meaningful identifier the surface has (a user ID or email where known), so it can differ across surfaces. It must be absolute (`https://…`); a relative URL would resolve against the element frame, so one is treated as unset. Unset, a person click raises `personOpened` on its element instead, which is the cue to present `person` over your page. `people` and `events` base URLs are accepted for symmetry with the ads handle but nothing under this handle renders them.
 	 * @default {}
 	 */
 	links?: CrossLinksConfig;
@@ -265,7 +265,7 @@ export interface PeopleElementCreateOptions {
 	 */
 	onSortChanged?: ((payload: { sort: string; dir: "asc" | "desc"; }) => void);
 	/**
-	 * The viewer clicked a person row and the handle has no `links.person` to follow — open your own person view with it (`personId` is the stable per-person key; `identifier` is the most human-meaningful one the surface has), or pass `links.person` on the handle to turn rows into real anchors instead.
+	 * The viewer clicked a person row and the handle has no `links.person` to follow. Present the `person` element with it, e.g. `createOverlay("person", { identifier: payload.personId })` (`personId` is the stable per-person key; `identifier` is the most human-meaningful one the surface has), or pass `links.person` on the handle to turn rows into real anchors instead.
 	 */
 	onPersonOpened?: ((payload: { identifier: string; personId: string; }) => void);
 	/**
@@ -431,7 +431,7 @@ export interface EventsElementCreateOptions {
 	 */
 	onFiltersChanged?: ((payload: EventsFilterBag) => void);
 	/**
-	 * The viewer clicked a person cell and the handle has no `links.person` to follow — open your own person view with it (`personId` is the stable per-person key; `identifier` is the most human-meaningful one the surface has), or pass `links.person` on the handle to turn the cells into real anchors instead.
+	 * The viewer clicked a person cell and the handle has no `links.person` to follow. Present the `person` element with it, e.g. `createOverlay("person", { identifier: payload.personId })` (`personId` is the stable per-person key; `identifier` is the most human-meaningful one the surface has), or pass `links.person` on the handle to turn the cells into real anchors instead.
 	 */
 	onPersonOpened?: ((payload: { identifier: string; personId: string; }) => void);
 	/**
@@ -448,6 +448,89 @@ export interface EventsElementCreateOptions {
 	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
 }
 
+/**
+ * Consumer props for the "person" element. Set at create (or as `<PersonElement />` JSX props), and updatable live via `update()`.
+ * @see https://docs.whop.com/elements/latest/tracking/person
+ */
+export interface PersonElementProps {
+	/**
+	 * The person to show, as any identifier the account has seen them under: the stable `prsn_…` person ID, a Whop user ID, or an email. Required. `personOpened` carries two of these; prefer its `personId`, the stable key that names the same person on every surface. If nothing resolves, the view says so rather than rendering empty.
+	 * @default ""
+	 */
+	identifier?: string;
+}
+
+/**
+ * The live handle for a mounted "person" element. Returned by `create("person")`; in React, the component's `ref`.
+ * @see https://docs.whop.com/elements/latest/tracking/person
+ */
+export interface PersonElementHandle {
+	/**
+	 * 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<PersonElementProps>) => void;
+}
+
+/**
+ * Options for `create("person")`: the consumer props plus event callbacks and lifecycle hooks.
+ * @example
+ * ```ts
+ * const person = tracking.create("person", {}); // this interface: props + on<Event> callbacks
+ * person.mount("#tracking-person");
+ * ```
+ * @see https://docs.whop.com/elements/latest/tracking/person
+ */
+export interface PersonElementCreateOptions {
+	/**
+	 * The person to show, as any identifier the account has seen them under: the stable `prsn_…` person ID, a Whop user ID, or an email. Required. `personOpened` carries two of these; prefer its `personId`, the stable key that names the same person on every surface. If nothing resolves, the view says so rather than rendering empty.
+	 * @default ""
+	 */
+	identifier?: string;
+	/**
+	 * Runs after the loading skeleton first paints and before `onReady`.
+	 */
+	onLoaderStart?: (() => void);
+	/**
+	 * Runs after the element's first complete paint.
+	 */
+	onReady?: (() => void);
+	/**
+	 * Runs when the element fails to load or crashes. The fallback remains visible. Use `code` for programmatic handling. `sourceKey` identifies a failed host-state source.
+	 */
+	onError?: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void);
+}
+
+/**
+ * The overlay handle for "person". Returned by `createOverlay("person")`; drives the modal presentation imperatively.
+ * @see https://docs.whop.com/elements/latest/tracking/person
+ */
+export interface PersonElementOverlayHandle {
+	/**
+	 * Open the overlay. The first call mounts the element. Later calls reuse it.
+	 */
+	open(): void;
+	/**
+	 * Close the overlay without destroying it. Keep the handle and `open()` again.
+	 */
+	close(): 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<PersonElementProps>): void;
+}
+
 /**
  * The Tracking handle, returned by `whop.tracking.create()` (React: `useTracking()`). Mounts the elements and carries the controller's actions.
  * @see https://docs.whop.com/elements/latest/tracking/overview
@@ -461,6 +544,14 @@ export interface TrackingHandle {
 	 * Every event the account measured — page views, leads, purchases, and custom pixel events — as a raw, filterable stream. The rows behind any metric: filter by event, source, geography, or device over the handle’s window, or search one person’s identifier to read their whole journey. A person cell follows `links.person` when the handle configures it, and otherwise comes back to you as `personOpened`.
 	 */
 	create(name: "events", options?: EventsElementCreateOptions): EventsElementHandle;
+	/**
+	 * Everything the account knows about one person: who they are, where they came from, what they have spent, and every event they have performed, in order. The view a person click leads to: mount it on the page `links.person` points at, or present it over your own page when `people` or `events` raise `personOpened`. `identifier` takes any identifier a person has been seen under, so a `personOpened` payload resolves here unchanged.
+	 */
+	create(name: "person", options?: PersonElementCreateOptions): PersonElementHandle;
+	/**
+	 * Everything the account knows about one person: who they are, where they came from, what they have spent, and every event they have performed, in order. The view a person click leads to: mount it on the page `links.person` points at, or present it over your own page when `people` or `events` raise `personOpened`. `identifier` takes any identifier a person has been seen under, so a `personOpened` payload resolves here unchanged.
+	 */
+	createOverlay(name: "person", options?: PersonElementCreateOptions): PersonElementOverlayHandle;
 	/**
 	 * Merges new handle options into every mounted element. In React, change the namespace props instead.
 	 */