@whop/elements 1.7.0 → 1.9.0

package/payments.d.ts

@@ -215,6 +215,11 @@ export interface PaymentElementProps {
 	 * @default []
 	 */
 	order?: string[];
+	/**
+	 * Controls which wallets the element offers. Each key defaults to `'auto'`, which offers the wallet wherever the account, the buyer's device, and the charge support it. `'never'` removes that wallet from the method list. Use it when your page draws its own Apple Pay, Google Pay, or PayPal buttons with `paymentRequest`, so buyers see each wallet once. `payPal: 'never'` removes the PayPal method. Saved payment methods are unaffected.
+	 * @default {}
+	 */
+	wallets?: { applePay?: "never" | "auto" | undefined; googlePay?: "never" | "auto" | undefined; payPal?: "never" | "auto" | undefined; };
 	/**
 	 * 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"}
@@ -279,6 +284,11 @@ export interface PaymentElementCreateOptions {
 	 * @default []
 	 */
 	order?: string[];
+	/**
+	 * Controls which wallets the element offers. Each key defaults to `'auto'`, which offers the wallet wherever the account, the buyer's device, and the charge support it. `'never'` removes that wallet from the method list. Use it when your page draws its own Apple Pay, Google Pay, or PayPal buttons with `paymentRequest`, so buyers see each wallet once. `payPal: 'never'` removes the PayPal method. Saved payment methods are unaffected.
+	 * @default {}
+	 */
+	wallets?: { applePay?: "never" | "auto" | undefined; googlePay?: "never" | "auto" | undefined; payPal?: "never" | "auto" | undefined; };
 	/**
 	 * 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"}
@@ -304,9 +314,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. `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.
+	 * 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. `paymentMethod` is the selected payment method, saved or new, or `null` while nothing is selected: `displayName` and `icons` name the pick the way the element shows it (with `balance.imageUrl`, a balance owner's image), `card` carries a card's network, last four digits and funding, `requiresBillingPhone` says whether the method needs a phone in billing details, and `countries` lists where the method can pay from in the charge's currency. `type`, `requiresBillingPhone` and `method` at the top level are deprecated: read them from `paymentMethod`. `supportsBuyerFee` at the top level is deprecated too, with no replacement: Whop prices its buyer service fee itself.
 	 */
-	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);
+	onChange?: ((payload: PaymentElementChangeEvent) => 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.
 	 */
@@ -339,7 +349,7 @@ export interface AddressElementProps {
 	 * The name row: one full-name field (default), split first/last fields, or none.
 	 * @default "combined"
 	 */
-	name?: "split" | "combined" | "none";
+	name?: "split" | "none" | "combined";
 	/**
 	 * Address line 2: always visible (default), revealed by a text button (`toggle`), or never collected.
 	 * @default "always"
@@ -368,7 +378,7 @@ export interface AddressElementProps {
 	 * Organization fields: none (default), name only, or name with a business/individual selector.
 	 * @default "none"
 	 */
-	organization?: "name" | "none" | "name_with_type";
+	organization?: "none" | "name" | "name_with_type";
 	/**
 	 * Default the country from the buyer's IP (resolved before first paint). Falls back to the controller's `countryHint`, then US.
 	 * @default true
@@ -379,7 +389,7 @@ export interface AddressElementProps {
 	 */
 	allowedCountries?: string[];
 	/**
-	 * Enables Google Places suggestions for the street address. If no match appears or Places is blocked, the list reports no matches and lets buyers enter the address manually. Set `false` for a plain input.
+	 * Enables Google Places suggestions for the street address. If no match appears or Places is blocked, the list reports no matches and lets buyers enter the address manually. On a phone, the suggestions open full screen from a search button in the street field instead of under it, where the keyboard would cover them. Set `false` for a plain input.
 	 * @default true
 	 */
 	autocomplete?: boolean;
@@ -445,7 +455,7 @@ export interface AddressElementCreateOptions {
 	 * The name row: one full-name field (default), split first/last fields, or none.
 	 * @default "combined"
 	 */
-	name?: "split" | "combined" | "none";
+	name?: "split" | "none" | "combined";
 	/**
 	 * Address line 2: always visible (default), revealed by a text button (`toggle`), or never collected.
 	 * @default "always"
@@ -474,7 +484,7 @@ export interface AddressElementCreateOptions {
 	 * Organization fields: none (default), name only, or name with a business/individual selector.
 	 * @default "none"
 	 */
-	organization?: "name" | "none" | "name_with_type";
+	organization?: "none" | "name" | "name_with_type";
 	/**
 	 * Default the country from the buyer's IP (resolved before first paint). Falls back to the controller's `countryHint`, then US.
 	 * @default true
@@ -485,7 +495,7 @@ export interface AddressElementCreateOptions {
 	 */
 	allowedCountries?: string[];
 	/**
-	 * Enables Google Places suggestions for the street address. If no match appears or Places is blocked, the list reports no matches and lets buyers enter the address manually. Set `false` for a plain input.
+	 * Enables Google Places suggestions for the street address. If no match appears or Places is blocked, the list reports no matches and lets buyers enter the address manually. On a phone, the suggestions open full screen from a search button in the street field instead of under it, where the keyboard would cover them. Set `false` for a plain input.
 	 * @default true
 	 */
 	autocomplete?: boolean;
@@ -595,6 +605,11 @@ export interface EmailElementProps {
 	 * @default true
 	 */
 	label?: boolean;
+	/**
+	 * Placeholder text for the email input. Empty (default) renders `you@example.com`. With floating labels the label text is the placeholder instead.
+	 * @default ""
+	 */
+	placeholder?: string;
 	/**
 	 * `above` (default) shows the label above the input. `floating` uses the label text as the placeholder, then shows a small label above the typed text once the input has a value. Ignored when `label` is `false`.
 	 * @default "above"
@@ -605,11 +620,6 @@ export interface EmailElementProps {
 	 * @default ""
 	 */
 	defaultValue?: string;
-	/**
-	 * Placeholder text for the email input. Empty (default) renders `you@example.com`. With floating labels the label text is the placeholder instead.
-	 * @default ""
-	 */
-	placeholder?: string;
 }
 
 /**
@@ -646,6 +656,11 @@ export interface EmailElementCreateOptions {
 	 * @default true
 	 */
 	label?: boolean;
+	/**
+	 * Placeholder text for the email input. Empty (default) renders `you@example.com`. With floating labels the label text is the placeholder instead.
+	 * @default ""
+	 */
+	placeholder?: string;
 	/**
 	 * `above` (default) shows the label above the input. `floating` uses the label text as the placeholder, then shows a small label above the typed text once the input has a value. Ignored when `label` is `false`.
 	 * @default "above"
@@ -656,11 +671,6 @@ export interface EmailElementCreateOptions {
 	 * @default ""
 	 */
 	defaultValue?: string;
-	/**
-	 * Placeholder text for the email input. Empty (default) renders `you@example.com`. With floating labels the label text is the placeholder instead.
-	 * @default ""
-	 */
-	placeholder?: string;
 	/**
 	 * Fires when the email changes. `complete` is true when plausible. Sign-in fires it with the signed-in email, which also feeds `createConfirmationToken()`.
 	 */
@@ -825,6 +835,10 @@ export interface BrandingElementCreateOptions {
  * @see https://docs.whop.com/elements/latest/payments/overview
  */
 export interface CardFieldsSubOptions {
+	/**
+	 * The seller's accepted card networks in display order — the matrix card entry's `networks` objects, whose API-served icons drive the number field's brand art. Omit it to fetch alongside the key.
+	 */
+	networks?: CardNetworkArt[];
 	/**
 	 * `stacked` (default) shapes composed fields as a number row above expiration and security code. `compact` shapes one row. Separately mounted fields ignore this layout and render with full borders and rounded corners.
 	 * @default "stacked"
@@ -835,13 +849,9 @@ export interface CardFieldsSubOptions {
 	 */
 	publicKey?: string;
 	/**
-	 * The seller's accepted card networks in display order — the matrix card entry's `networks` objects, whose API-served icons drive the number field's brand art. Omit it to fetch alongside the key.
-	 */
-	networks?: CardNetworkArt[];
-	/**
-	 * Fires when completeness changes. `complete` becomes true after the buyer fills all three fields. Use it to enable confirmation. `brand` is the detected card network. `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.
+	 * 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 as the field reports it; `network` is the same detection in the API's network vocabulary (matches the matrix card entry's `networks`, `null` while unknown). `last4` is the number's last four digits, `null` until the number is far enough along. `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; issuingCountry: string | null; }) => void);
+	onChange?: ((payload: { complete: boolean; brand: string; network: "visa" | "mastercard" | "amex" | "discover" | "jcb" | "diners" | "unionpay" | "elo" | "maestro" | null; last4: string | null; funding: string | null; issuingCountry: string | null; }) => void);
 }
 
 /**
@@ -1034,6 +1044,10 @@ export interface PaymentRequestResourceOptions {
 	 * Set only after displaying save consent. Marks the token for `off_session` or `on_session` use.
 	 */
 	setupFutureUsage?: "off_session" | "on_session";
+	/**
+	 * Payment method filters in the API's `enabled`, `disabled`, and `include_platform_defaults` format. They narrow the wallets `canMakePayment()` reports: `disabled` removes types, `enabled` restores offered types, and `include_platform_defaults: false` leaves only enabled types. They never add a method the account doesn't offer. PayPal follows the `paypal` type.
+	 */
+	paymentMethodConfiguration?: PaymentMethodConfigurationShape;
 	/**
 	 * Ask the sheet for the payer's email — the confirmation token requires one.
 	 * @default true
@@ -1055,11 +1069,11 @@ export interface PaymentRequestResourceOptions {
 	 */
 	requestPromoCode?: boolean;
 	/**
-	 * A promo code already applied to the charge, prefilled into the sheet so the buyer can see or remove it.
+	 * A promo code already applied to the charge, prefilled into the sheet so the buyer can see, replace or remove it.
 	 */
 	appliedPromoCode?: string;
 	/**
-	 * What `appliedPromoCode` does, shown next to the code where the sheet captions applied codes (Google Pay).
+	 * What `appliedPromoCode` does, shown next to the code in Google Pay. Apple Pay's coupon field has no caption.
 	 */
 	appliedPromoDescription?: string;
 	/**
@@ -1072,7 +1086,7 @@ export interface PaymentRequestResourceOptions {
 	 */
 	lineItems?: PaymentRequestLineItem[];
 	/**
-	 * Shipping options the sheet offers when `requestShipping` is set. Display-only — update `amount` from your change handler.
+	 * Shipping options the sheet offers when `requestShipping` is set. Display-only — update `amount` from your change handler. The sheet opens with the first option selected and fires no `onShippingOptionChange` for it, so `amount` must already include its price.
 	 * Change it later with `update()`.
 	 */
 	shippingOptions?: PaymentRequestShippingOption[];
@@ -1084,7 +1098,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), and offering Google Pay there is subject to the [Google Pay API Terms of Service](https://payments.developers.google.com/terms/sellertos)). On a page that is itself inside an iframe, Apple Pay checks the top-level page's domain instead when the browser exposes it. 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, PayPal last — so express buttons can stack best-first. `payPal` reports PayPal where the account offers it in this currency, the amount is within PayPal's limits, the request neither sets `setupFutureUsage` nor asks for the payer's phone, PayPal's scripts load on this page, and this page's origin is approved for the account like the other wallets'. A page with a Content Security Policy must allow PayPal's hosts, which `contentSecurityPolicy()` includes. A page that already loads PayPal's own v5 JavaScript SDK reports `payPal: false`. Pass `types` to check only the wallets you list; `show(type)` needs that wallet checked. `wallets` carries each available wallet's official button art (`light` and `dark` color and image). 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)). On a page that is itself inside an iframe, Apple Pay checks the top-level page's domain instead when the browser exposes it. 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, PayPal last — so express buttons can stack best-first. `payPal` reports PayPal where the account offers it in this currency, the amount is within PayPal's limits, the request does not ask for the payer's phone (an `off_session` request may be $0, which saves PayPal without a charge), PayPal's scripts load on this page, and this page's origin is approved for the account like the other wallets'. A page with a Content Security Policy must allow PayPal's hosts, which `contentSecurityPolicy()` includes. A page that already loads PayPal's own v5 JavaScript SDK reports `payPal: false`. Pass `types` to check only the wallets you list; `show(type)` needs that wallet checked. `wallets` carries each available wallet's official button art (`light` and `dark` color and image). This primes `show()`. Always await it first.
 	 */
 	canMakePayment: (filter?: { types?: ("apple_pay" | "google_pay" | "paypal_express")[] | undefined; } | undefined) => Promise<WalletAvailability>;
 	/**
@@ -1097,31 +1111,43 @@ export interface PaymentRequestResource {
 	 */
 	update: (patch: { amount?: number | undefined; lineItems?: PaymentRequestLineItem[] | undefined; shippingOptions?: PaymentRequestShippingOption[] | undefined; }) => void;
 	/**
-	 * The sheet's shipping address changed (redacted pre-authorization: city/state/postal/country only). An error in the answer that names a `field` (`city`, `state`, `postal_code`, `country`) marks that field in Apple Pay; Google Pay shows the message alone. PayPal fires it with the address the buyer picks, and an error naming a `field` refuses that part of the address inside PayPal.
+	 * The buyer chose a shipping address (redacted pre-authorization: city, state, postal code and country only; Apple Pay cuts a US ZIP code to five digits and drops the last three characters of a Canadian or UK postal code). Answer with the totals for the address and the selected shipping option: the first one until the buyer picks another. `shippingOptions` replaces the options (an empty list changes nothing). A picked option stays selected while the answer keeps its `id`; when the answer drops it, the first option becomes the selection without an `onShippingOptionChange`, so price that one. Every error in the answer stays on the address until a later answer for an address clears it: one that names a `field` (`city`, `state`, `postal_code`, `country`) marks that field in Apple Pay, and Google Pay shows the message alone. Pay is refused while an error stands on the address. Refuse an address you can't ship to with a `shipping_address_unserviceable` error and no `field`. On Apple Pay, Google Pay and PayPal, a handler that hasn't answered within 25 seconds fails the address, the way a throwing one does, and its later answer is ignored. PayPal fires it with the address the buyer picks, and an error naming a `field` refuses that part of the address inside PayPal.
 	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
 	 * Returns the unsubscribe function.
 	 */
 	onShippingAddressChange(handler: (ev: ShippingAddressChangeEvent) => void): () => void;
 	/**
-	 * The buyer picked a shipping option. Amount-only contract: `updateWith` carries amount/lineItems/shippingOptions/errors. Apple Pay has no error slot for a shipping option: an answer with `errors` keeps the last accepted total, and the first error's message shows when the buyer taps Pay, until they pick an option your handler accepts. Google Pay shows the message when the option is picked.
+	 * The buyer picked a shipping option, or Apple Pay re-announced the selected one: once the address changes are all answered and none is waiting, Apple Pay fires it for the option still selected. It never fires after an answer that drops the selected option, which makes the first option the selection without an event, so every total you answer prices the selected option: the first one until the buyer picks another, the pick while your answers keep its `id`, and the first again once an answer drops it. Amount-only contract: `updateWith` carries amount/lineItems/shippingOptions/errors. An answer with `errors` refuses the option until the buyer picks one your handler accepts. Apple Pay has no error slot for a shipping option, so it keeps the last accepted total whatever else the answer carries, and the first error's message shows when the buyer taps Pay. Google Pay shows the message when the option is picked. On Apple Pay, Google Pay and PayPal, a handler that hasn't answered within 25 seconds refuses the option, the way a throwing one does, and its later answer is ignored.
 	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
 	 * Returns the unsubscribe function.
 	 */
 	onShippingOptionChange(handler: (ev: ShippingOptionChangeEvent) => void): () => void;
 	/**
-	 * Fires at sheet open and on card switches with the selected card's redacted billing address (city/state/postal/country only) — reprice the total for the address the charge taxes off. Answer `updateWith({ amount })` in minor units, `updateWith({})` to keep the current total, or `updateWith({ errors })` to refuse the card. Every event is answered exactly once: a handler that throws, rejects, or doesn't answer within 10 seconds refuses the card, so the buyer picks another one. PayPal fires it with each shipping address the buyer picks in PayPal, which is the address its token bills and taxes on, and a refusal there refuses that address inside PayPal.
+	 * The buyer selected a card, with its redacted billing address (city, state, postal code and country only): reprice the total for the address the charge taxes off. Apple Pay fires it when the buyer selects a card, and Google Pay when the sheet opens and each time the buyer switches cards. Answer `updateWith({ amount })` in minor units, `updateWith({})` to keep the current total, or `updateWith({ errors })` to refuse the card. Every event is answered exactly once: a handler that throws, rejects, or doesn't answer within 10 seconds refuses the card, so the buyer picks another one. On Apple Pay and Google Pay the same selection then fires `paymentMethodChange`, and the sheet updates once both are answered. PayPal fires it with each shipping address the buyer picks in PayPal, which is the address its token bills and taxes on, and a refusal there refuses that address inside PayPal.
 	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
 	 * Returns the unsubscribe function.
 	 */
 	onBillingAddressChange(handler: (ev: BillingAddressChangeEvent) => void): () => void;
 	/**
-	 * The buyer typed, changed, or removed a code in the sheet's promo field (`requestPromoCode`). Answer `updateWith({ amount })` to apply the code at a new total, `updateWith({})` to apply it at the current total, or `updateWith({ error })` to refuse it in place. A removal arrives with `code` null and is answered the same way. A handler that throws, rejects, or doesn't answer within 10 seconds refuses the code.
+	 * The buyer selected a payment method: reprice the total for it, such as a surcharge on credit cards. Apple Pay fires it when the buyer selects a card, and Google Pay when the sheet opens and each time the buyer switches cards, each right after that card's `billingAddressChange`. `paymentMethod.type` is `card`. `paymentMethod.card` carries what the wallet tells about a card before the buyer authorizes: Apple Pay reports its `funding` (Apple usually withholds the network until then), and Google Pay its `network`. `paymentMethod.billingAddress` is the card's redacted billing address. Answer `updateWith({ amount, lineItems })` to reprice, `updateWith({})` to keep the current total, or `updateWith({ errors })` to refuse the method; `shippingOptions` is ignored. Apple Pay marks a refusal on the card's billing contact (on the named `field` when one is given) and holds its Pay button until the buyer picks another method. Google Pay shows the message on the card and refuses a Pay tap on it until the buyer picks a card you accept. A refused card leaves the totals as they were, whatever this answer or its `billingAddressChange` answer priced. Every event is answered exactly once: a handler that throws, rejects, or doesn't answer within 10 seconds refuses the method. Each sheet waits for your answer before the buyer can pay. PayPal never fires it.
+	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
+	 * Returns the unsubscribe function.
+	 */
+	onPaymentMethodChange(handler: (ev: PaymentMethodChangeEvent) => void): () => void;
+	/**
+	 * The buyer typed, changed, or removed a code in the sheet's promo field (`requestPromoCode`). Answer `updateWith({ amount })` to apply the code at a new total, `updateWith({})` to apply it at the current total, or `updateWith({ error })` to refuse it in place. A removal arrives with `code` null and is answered the same way. Replacing an applied code arrives as one event with the new code, never a removal first, and a refused new code leaves the applied one in place. When `shippingOptions` drops the selected option, the first one becomes the selection without an `onShippingOptionChange`, so price that one. `appliedDescription` captions the code in Google Pay; Apple Pay's coupon field has no caption, so put anything the buyer must see in a line item label. A handler that throws, rejects, or doesn't answer within 10 seconds refuses the code.
 	 * Call `updateWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
 	 * Returns the unsubscribe function.
 	 */
 	onPromoCodeChange(handler: (ev: PromoCodeChangeEvent) => void): () => void;
 	/**
-	 * The sheet created a confirmation token. This is the same result that `show()` returns.
+	 * The buyer authorized the payment, and no confirmation token exists yet. Subscribe to approve or refuse it first: the sheet waits for your answer, and without a handler the token is created at once. The event carries the payer, the payment method (with its redacted billing address, and in `displayName` the wallet's own label for it, such as `Visa 1234`), the shipping address and option, and the total and line items the buyer authorized. Answer `respondWith({ approved: true })` to create the token, which `show()` and `onConfirmationToken` then deliver as usual. Answer `respondWith({ approved: false, message })` to refuse: no token is created, Apple Pay and Google Pay show `message` in the sheet, and the buyer can change something and pay again, or close the sheet. PayPal can't show your message, so a refusal there ends the attempt: `show()` rejects with `payment_request_refused`, and the buyer can press PayPal again. Every event is answered exactly once, and only `approved: true` creates a token: a handler that throws, rejects, or doesn't answer within 25 seconds refuses the payment, early enough for Apple Pay and Google Pay to show the refusal before their own 30-second limit.
+	 * Call `respondWith(…)` exactly once per event. A handler that throws or rejects before calling it fails that update right away.
+	 * Returns the unsubscribe function.
+	 */
+	onPaymentAuthorization(handler: (ev: PaymentAuthorizationEvent) => void): () => void;
+	/**
+	 * The sheet created a confirmation token, heard once the sheet has closed. This is the same result that `show()` returns.
 	 * Returns the unsubscribe function.
 	 */
 	onConfirmationToken(handler: (ev: PaymentRequestResult) => void): () => void;
@@ -1143,7 +1169,7 @@ export interface PaymentsHandle {
 	 */
 	create(name: "payment", options?: PaymentElementCreateOptions): PaymentElementHandle;
 	/**
-	 * Collects a billing or shipping address. Fields, order, and validation follow the selected country. Includes street autocomplete and methods to read or validate the address.
+	 * Collects a billing or shipping address. Fields, order, and validation follow the selected country. Includes street autocomplete (full screen on phones) and methods to read or validate the address.
 	 * One per "mode": call once per "mode" value; a second "address" with the same "mode" throws. "mode" is fixed at create.
 	 */
 	create(name: "address", options?: AddressElementCreateOptions): AddressElementHandle;
@@ -1161,11 +1187,11 @@ export interface PaymentsHandle {
 	 */
 	create(name: "taxId", options?: TaxIdElementCreateOptions): TaxIdElementHandle;
 	/**
-	 * Whop's merchant-of-record notice: the Whop wordmark with links to the buyer terms and privacy policy. Mount it alongside every payment collection surface.
+	 * Whop's merchant-of-record notice: the buyer's agreement to Whop's Buyer Terms of Service and Privacy Policy, with the Whop wordmark. Required — the payment, card and card fields elements stay in their loading state until it is mounted, and payments cannot be confirmed without it.
 	 */
 	create(name: "branding", options?: BrandingElementCreateOptions): BrandingElementHandle;
 	/**
-	 * Creates a confirmation token for the selected method from your pay button. Pass the checkout's billing details. They must include `email`. 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(…)`.
+	 * 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. When the account offers in-page bank linking (`bank_debit.bank_connection` on its bank account payment method type), a bank account selection opens Plaid Link during it too, and the call resolves once the buyer has linked an account. That needs a whop.com page or a domain verified as a [payment method domain](/api-reference/beta/payment-method-domains/payment-method-domain), and a Content Security Policy that allows the Plaid hosts `contentSecurityPolicy()` returns. Otherwise the buyer links the account after submitting instead. If the buyer closes the sheet or Link, the call rejects with `payment_request_cancelled`: treat it as a cancel, not a payment error, and let the buyer pay again. 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; 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; }>;
@@ -1242,6 +1268,95 @@ export interface WalletAvailability {
 	wallets?: { apple_pay?: WalletDetails | undefined; google_pay?: WalletDetails | undefined; paypal_express?: WalletDetails | undefined; } | undefined;
 }
 
+/**
+ * Any API `icons` object (or slice of one) qualifies: the component only reads the requested shape's light/dark SVGs.
+ * Declared from the app's `PaymentMethodIconVariants`, referenced by a host-capability surface.
+ */
+export interface PaymentMethodIconVariants {
+	light: { svg: string; };
+	dark: { svg: string; };
+}
+
+/**
+ * Declared from the app's `PaymentMethodIcons`, referenced by a host-capability surface.
+ */
+export interface PaymentMethodIcons {
+	square?: PaymentMethodIconVariants | null | undefined;
+	card?: PaymentMethodIconVariants | null | undefined;
+}
+
+/**
+ * Declared from the app's `PaymentElementPaymentMethod`, referenced by a host-capability surface.
+ */
+export interface PaymentElementPaymentMethod {
+	/**
+	 * The saved payment method the buyer picked, or `null` for a method the buyer is entering now or a balance.
+	 */
+	id: string | null;
+	/**
+	 * The payment method type: `card`, `klarna`, `apple_pay`, `balance`, and so on.
+	 */
+	type: string;
+	/**
+	 * The family the type belongs to, such as `card`, `wallet`, `bnpl` or `balance`.
+	 */
+	category: string;
+	/**
+	 * What to call the pick: a saved method's own label ("Visa •••• 4242", "Cash App $tag"), a balance's name ("Acme", "Personal Balance"), a card's network and last four digits as the buyer types it, or else the method's own name ("Klarna").
+	 */
+	displayName: string;
+	/**
+	 * The pick's icon art: a saved method's own icons, a typed card's network art, or else the method's icons. Always an icon set, with SVG and PNG renditions.
+	 */
+	icons?: PaymentMethodIcons | undefined;
+	/**
+	 * What is known about a balance pick beyond its type: `imageUrl` is the balance owner's image, a single raster image URL rather than an icon set, to show in place of `icons`. Absent for other methods, and for a balance whose owner has no image.
+	 */
+	balance?: { imageUrl?: string | undefined; } | undefined;
+	/**
+	 * What is known about a card pick: a saved card's details, or a typed card's as the buyer types. Absent for other methods.
+	 */
+	card?: { network?: string | undefined; last4?: string | undefined; funding?: string | undefined; } | undefined;
+	/**
+	 * Whether the method needs a phone in the billing details, including when `fields.phone` disables the element's own phone input.
+	 */
+	requiresBillingPhone: boolean;
+	/**
+	 * The lowercase two-letter country codes the method can pay from in the charge's currency.
+	 */
+	countries: string[];
+}
+
+/**
+ * Declared from the app's `PaymentElementChangeEvent`, referenced by a host-capability surface.
+ */
+export interface PaymentElementChangeEvent {
+	/**
+	 * Whether the buyer selected a method and completed its card fields or required inputs. Use it to enable confirmation.
+	 */
+	complete: boolean;
+	/**
+	 * The selected payment method, or `null` while nothing is selected.
+	 */
+	paymentMethod: PaymentElementPaymentMethod | null;
+	/**
+	 * @deprecated Use `paymentMethod.type`.
+	 */
+	type?: string | undefined;
+	/**
+	 * @deprecated Whop prices its buyer service fee itself, so a page has no use for it. Removed in the next major.
+	 */
+	supportsBuyerFee?: boolean | undefined;
+	/**
+	 * @deprecated Use `paymentMethod.requiresBillingPhone`.
+	 */
+	requiresBillingPhone?: boolean | undefined;
+	/**
+	 * @deprecated Use `paymentMethod`. Absent when the buyer picks a saved method.
+	 */
+	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;
+}
+
 /**
  * The slice of a matrix card network the fields need: identity plus the API-served square art.
  * Declared from the app's `CardNetworkArt`, referenced by a host-capability surface.
@@ -1251,6 +1366,16 @@ export interface CardNetworkArt {
 	icons: { square: { light: { svg: string; }; dark: { svg: string; }; }; };
 }
 
+/**
+ * Payment method filters in the API's `payment_method_configuration` format: `disabled` removes types, `enabled` restores offered types, and `include_platform_defaults: false` leaves only enabled types.
+ * Declared from the app's `PaymentMethodConfigurationShape`, referenced by a host-capability surface.
+ */
+export interface PaymentMethodConfigurationShape {
+	enabled?: string[] | undefined;
+	disabled?: string[] | undefined;
+	include_platform_defaults?: boolean | undefined;
+}
+
 /**
  * Declared from the app's `PaymentRequestLineItem`, referenced by a host-capability surface.
  */
@@ -1279,12 +1404,20 @@ export interface PaymentRequestShippingOption {
  * Declared from the app's `PaymentRequestAddress`, referenced by a host-capability surface.
  */
 export interface PaymentRequestAddress {
+	/**
+	 * The name on the address.
+	 */
+	name?: string | undefined;
 	line1?: string | undefined;
 	line2?: string | undefined;
 	city?: string | undefined;
 	state?: string | undefined;
 	postal_code?: string | undefined;
 	country?: string | undefined;
+	/**
+	 * The same value as `name`.
+	 * @deprecated Use `name`.
+	 */
 	recipient?: string | undefined;
 	phone?: string | undefined;
 }
@@ -1298,7 +1431,17 @@ export interface PaymentRequestResult {
 	 */
 	ctok: string;
 	type: "apple_pay" | "google_pay" | "paypal_express";
+	/**
+	 * `phone` is E.164 where it parsed against the contact's country, as given otherwise; `country` is the billing country every sheet collects.
+	 */
 	payer: { email?: string | undefined; name?: string | undefined; phone?: string | undefined; country?: string | undefined; };
+	/**
+	 * The full billing address the confirmation token carries, unlike the redacted one the change events carry; `null` when the wallet gave none. Apple Pay and Google Pay give the card's billing address. On PayPal it is the address the buyer picked in PayPal, the one its total was taxed on.
+	 */
+	billing: { address: PaymentRequestAddress; } | null;
+	/**
+	 * `null` unless `requestShipping` was set. `option` is the selected shipping option: the first offered one until the buyer picks another, and the first again when an answer replaced the options without the picked `id`. Apple Pay and Google Pay set it whenever options were offered, and PayPal never does.
+	 */
 	shipping: { address?: PaymentRequestAddress | undefined; option?: PaymentRequestShippingOption | undefined; } | null;
 }
 
@@ -1306,12 +1449,15 @@ export interface PaymentRequestResult {
  * Declared from the app's `PaymentRequestError`, referenced by a host-capability surface.
  */
 export interface PaymentRequestError {
-	code?: "shipping_address_invalid" | "shipping_address_unserviceable" | "shipping_option_invalid" | "other" | undefined;
+	/**
+	 * What a shipping answer refuses. An error in a `billingAddressChange` or `paymentMethodChange` answer refuses the card or method that event asked about, whatever its code.
+	 */
+	code?: "other" | "shipping_address_invalid" | "shipping_address_unserviceable" | "shipping_option_invalid" | undefined;
 	message: string;
 	/**
 	 * The address field the error is about: one of the fields the redacted address carries. Apple Pay marks that field with the message, whatever the `code`; Google Pay shows the message alone. Omit it for an error about the whole address.
 	 */
-	field?: "state" | "city" | "postal_code" | "country" | undefined;
+	field?: "state" | "country" | "city" | "postal_code" | undefined;
 }
 
 /**
@@ -1320,6 +1466,9 @@ export interface PaymentRequestError {
 export interface PaymentRequestUpdate {
 	amount?: number | undefined;
 	lineItems?: PaymentRequestLineItem[] | undefined;
+	/**
+	 * Replaces the sheet's shipping options. The selected option stays selected while its `id` is still in the list; otherwise the first option becomes the selection, with no `shippingOptionChange`, so price it in the same answer. An empty list changes nothing: refuse an address you can't ship to with a `shipping_address_unserviceable` error instead.
+	 */
 	shippingOptions?: PaymentRequestShippingOption[] | undefined;
 	errors?: PaymentRequestError[] | undefined;
 }
@@ -1329,11 +1478,11 @@ export interface PaymentRequestUpdate {
  */
 export interface ShippingAddressChangeEvent {
 	/**
-	 * Vendor-normalized pre-authorization address. It includes only city, state, postal code, and country.
+	 * Vendor-normalized pre-authorization address. It includes only city, state, postal code, and country. Apple Pay cuts the postal code down: a US ZIP code to its first five digits, and a Canadian or UK postal code without its last three characters.
 	 */
 	address: PaymentRequestAddress;
 	/**
-	 * Call this exactly once, or the sheet stalls until the vendor times it out.
+	 * Call this exactly once, within 25 seconds. On Apple Pay, Google Pay and PayPal a handler that hasn't answered by then fails the address the way a throwing one does, and its later answer is ignored.
 	 */
 	updateWith: (update: PaymentRequestUpdate) => void;
 }
@@ -1346,6 +1495,9 @@ export interface ShippingOptionChangeEvent {
 	 * Always includes the selected `id`. It includes the full option when it matches one of yours.
 	 */
 	option: { id: string; } & Partial<PaymentRequestShippingOption>;
+	/**
+	 * Call this exactly once, within 25 seconds. On Apple Pay, Google Pay and PayPal a handler that hasn't answered by then refuses the option the way a merchant refusal does, and its later answer is ignored.
+	 */
 	updateWith: (update: PaymentRequestUpdate) => void;
 }
 
@@ -1363,6 +1515,42 @@ export interface BillingAddressChangeEvent {
 	updateWith: (update: PaymentRequestUpdate) => void;
 }
 
+/**
+ * Declared from the app's `PaymentRequestPaymentMethod`, referenced by a host-capability surface.
+ */
+export interface PaymentRequestPaymentMethod {
+	/**
+	 * `card` on Apple Pay and Google Pay, which report only cards; `paypal` on PayPal.
+	 */
+	type: string;
+	/**
+	 * What the wallet tells about the card. Before the buyer authorizes, on `paymentMethodChange`, Apple Pay reports its funding, usually without the network, and Google Pay its network. At authorization Apple Pay and Google Pay report both.
+	 */
+	card?: { network?: string | undefined; funding?: "credit" | "debit" | "prepaid" | "store" | undefined; } | undefined;
+	/**
+	 * The card's redacted billing address (city, state, postal code and country only), which Apple Pay and Google Pay hand over with the card.
+	 */
+	billingAddress?: PaymentRequestAddress | undefined;
+	/**
+	 * The wallet's own label for the method, such as `Visa 1234`. Apple Pay and Google Pay set it only once the buyer authorizes, so only `paymentAuthorization` carries it. Show it, and don't parse it: the wallets promise no format.
+	 */
+	displayName?: string | undefined;
+}
+
+/**
+ * Declared from the app's `PaymentMethodChangeEvent`, referenced by a host-capability surface.
+ */
+export interface PaymentMethodChangeEvent {
+	/**
+	 * The method the buyer selected, as the wallet describes it before authorization.
+	 */
+	paymentMethod: PaymentRequestPaymentMethod;
+	/**
+	 * Call this exactly once: `amount` and `lineItems` reprice the sheet for the method, `updateWith({})` keeps the total, and `errors` refuses the method. An event left unanswered for 10 seconds refuses the method.
+	 */
+	updateWith: (update: PaymentRequestUpdate) => void;
+}
+
 /**
  * Declared from the app's `PromoCodeUpdate`, referenced by a host-capability surface.
  */
@@ -1376,7 +1564,11 @@ export interface PromoCodeUpdate {
 	 */
 	lineItems?: PaymentRequestLineItem[] | undefined;
 	/**
-	 * A caption for the applied code, where the sheet captions codes (Google Pay).
+	 * Replaces the sheet's shipping options under the code, such as a free-shipping code that drops a rate to zero. An option stays selected while its `id` is still in the list; otherwise the first option becomes the selection, with no `shippingOptionChange`. Send `amount` as well when the selected option's price changes, since the total doesn't follow on its own. An empty list changes nothing.
+	 */
+	shippingOptions?: PaymentRequestShippingOption[] | undefined;
+	/**
+	 * A caption shown beside the applied code in Google Pay. Apple Pay's coupon field has no caption, so put anything the buyer must see in a line item label.
 	 */
 	appliedDescription?: string | undefined;
 	/**
@@ -1390,11 +1582,59 @@ export interface PromoCodeUpdate {
  */
 export interface PromoCodeChangeEvent {
 	/**
-	 * The code now in the sheet's promo field, or null when the buyer removed it.
+	 * The code now in the sheet's promo field, or null when the buyer removed it. Replacing an applied code is one event with the new code, never a removal first.
 	 */
 	code: string | null;
 	/**
-	 * Answer exactly once: `error` refuses the code and keeps the totals, and any other answer applies it. `amount` and `lineItems` reprice the sheet under the code, and `appliedDescription` captions the applied code where the sheet shows one (Google Pay). `updateWith({})` applies the code at the current total.
+	 * Answer exactly once: `error` refuses the code and keeps the totals, and any other answer applies it. `amount` and `lineItems` reprice the sheet under the code, `shippingOptions` replaces its shipping options (a free-shipping code), and `appliedDescription` captions the applied code where the sheet shows one (Google Pay). `updateWith({})` applies the code at the current total.
 	 */
 	updateWith: (update: PromoCodeUpdate) => void;
 }
+
+/**
+ * Declared from the app's `PaymentAuthorizationResponse`, referenced by a host-capability surface.
+ */
+export interface PaymentAuthorizationResponse {
+	/**
+	 * `true` creates the confirmation token. `false` refuses the payment.
+	 */
+	approved: boolean;
+	/**
+	 * Shown to the buyer when you refuse, in the sheet that took the authorization.
+	 */
+	message?: string | undefined;
+}
+
+/**
+ * Declared from the app's `PaymentAuthorizationEvent`, referenced by a host-capability surface.
+ */
+export interface PaymentAuthorizationEvent {
+	/**
+	 * The wallet the buyer authorized in.
+	 */
+	type: "apple_pay" | "google_pay" | "paypal_express";
+	/**
+	 * The payer, as the result will carry it.
+	 */
+	payer: { email?: string | undefined; name?: string | undefined; phone?: string | undefined; country?: string | undefined; };
+	/**
+	 * The method the buyer authorized. Its billing address is redacted to city, state, postal code and country, as `paymentMethodChange` carries it.
+	 */
+	paymentMethod: PaymentRequestPaymentMethod;
+	/**
+	 * `null` unless `requestShipping` was set. Otherwise the address and option the result will carry.
+	 */
+	shipping: { address?: PaymentRequestAddress | undefined; option?: PaymentRequestShippingOption | undefined; } | null;
+	/**
+	 * The total the buyer authorized, in minor units.
+	 */
+	amount: number;
+	/**
+	 * The line items the sheet showed under that total.
+	 */
+	lineItems: PaymentRequestLineItem[];
+	/**
+	 * Call this exactly once. `{ approved: true }` creates the confirmation token. Anything else refuses the payment, and no token is created.
+	 */
+	respondWith: (response: PaymentAuthorizationResponse) => void;
+}