This page documents
@whop/elements@1.8.0 and @whop/elements-react@1.8.0.v1.0.0.
Create this
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, and offering Google Pay there is subject to the Google Pay API Terms of Service). 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.
Open the selected wallet after awaiting
Change
The sheet’s shipping address changed (redacted pre-authorization: city/state/postal/country only). An error in the answer that names a
The buyer picked a shipping option. Amount-only contract:
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
The buyer typed, changed, or removed a code in the sheet’s promo field (
The sheet created a confirmation token. This is the same result that
The buyer dismissed the sheet or closed PayPal. Returns the unsubscribe function.Signature:
Payments resource without mounting an element: whop.payments.paymentRequest.create({ … }) in vanilla or useWhop().payments.paymentRequest.create({ … }) in React.Options
Pass these towhop.payments.paymentRequest.create({ … }).string
required
Account ID, prefixed
biz_, that scopes every client-side call.string
required
Three-letter ISO 4217 payment currency code.
number
required
Payment amount in minor units. Change it later with
update()."off_session" | "on_session"
Set only after displaying save consent. Marks the token for
off_session or on_session use.boolean
Ask the sheet for the payer’s email — the confirmation token requires one. Defaults to
true.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. Defaults to false.boolean
Ask the sheet for a shipping address (and offer
shippingOptions when given). PayPal always asks for an address, since it is the address tax is computed on, and returns it as shipping only when this is set. Defaults to false.boolean
Offer the sheet’s own promo code field and answer
onPromoCodeChange. Apple Pay shows the field on devices that support Apple Pay version 12 (iOS 15 and macOS 12); Google Pay shows it where the account’s Google Pay setup allows offers. Other devices open the sheet without it. Defaults to false. Since v1.5.0.string
A promo code already applied to the charge, prefilled into the sheet so the buyer can see or remove it. Since
v1.5.0.string
What
appliedPromoCode does, shown next to the code where the sheet captions applied codes (Google Pay). Since v1.5.0.string
Account ISO 3166-1 alpha-2 country code for the Apple Pay sheet. Omit it to use the account’s published registration country. The sheet defaults to
US when neither is available.PaymentRequestLineItem[]
Line items the sheet lists under the total. Change it later with
update().PaymentRequestShippingOption[]
Shipping options the sheet offers when
requestShipping is set. Display-only — update amount from your change handler. Change it later with update().Methods
Call these on the resource.canMakePayment
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, and offering Google Pay there is subject to the Google Pay API Terms of Service). 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.Signature: (filter?: { types?: ("apple_pay" | "google_pay" | "paypal_express")[] | undefined; } | undefined) => Promise<WalletAvailability>show
Open the selected wallet after awaiting canMakePayment(), synchronously in the press: Apple requires session creation within the gesture stack, and PayPal opens its window there — a pop-up on desktop, PayPal’s in-page window when the pop-up is blocked and on mobile. Pass email when your page already collected one — the wallet takes it and never asks for a second. With requestPayerEmail: false, passing one is required, and the wallet refuses to open without it because confirmation tokens require an email. While the sheet is open, update() throws: answer the change events to change it. Call synchronously during user activation. Await prerequisites first because browsers revoke activation across asynchronous steps.Signature: (type: "apple_pay" | "google_pay" | "paypal_express", provided?: { email?: string | undefined; } | undefined) => Promise<PaymentRequestResult>update
Change amount, lineItems and shippingOptions on this instance. Every other option is fixed at create(): create a new instance to change it.Signature: (patch: { amount?: number | undefined; lineItems?: PaymentRequestLineItem[] | undefined; shippingOptions?: PaymentRequestShippingOption[] | undefined; }) => voidEvents
Subscribe to events below. Each method returns an unsubscribe function.onShippingAddressChange
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. Call updateWith(…) exactly once per event. A handler that throws or rejects before calling it fails that update right away. Returns the unsubscribe function.Signature: (handler: (ev: ShippingAddressChangeEvent) => void) => () => voidonShippingOptionChange
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. Call updateWith(…) exactly once per event. A handler that throws or rejects before calling it fails that update right away. Returns the unsubscribe function.Signature: (handler: (ev: ShippingOptionChangeEvent) => void) => () => voidonBillingAddressChange
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. Call updateWith(…) exactly once per event. A handler that throws or rejects before calling it fails that update right away. Returns the unsubscribe function.Signature: (handler: (ev: BillingAddressChangeEvent) => void) => () => voidonPromoCodeChange
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. Call updateWith(…) exactly once per event. A handler that throws or rejects before calling it fails that update right away. Returns the unsubscribe function.Signature: (handler: (ev: PromoCodeChangeEvent) => void) => () => voidonConfirmationToken
The sheet created a confirmation token. This is the same result that show() returns. Returns the unsubscribe function.Signature: (handler: (ev: PaymentRequestResult) => void) => () => voidonCancel
The buyer dismissed the sheet or closed PayPal. Returns the unsubscribe function.Signature: (handler: () => void) => () => voidContent security policy
This resource runs on your page, not in a frame. A page with a Content Security Policy needs these sources.contentSecurityPolicy() from @whop/elements returns every source in this table. The sandbox source applies with environment: "sandbox".