This page documents
@whop/elements@1.9.0 and @whop/elements-react@1.9.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. Returns
Open the selected wallet after awaiting Returns
Change
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.
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
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
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
The buyer typed, changed, or removed a code in the sheet’s promo field (
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
The sheet created a confirmation token, heard once the sheet has closed. This is the same result that
The buyer dismissed the sheet or closed PayPal. Returns the unsubscribe function.
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.PaymentMethodConfigurationShape
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. Since v1.9.0.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, replace or remove it. Since
v1.5.0.string
What
appliedPromoCode does, shown next to the code in Google Pay. Apple Pay’s coupon field has no caption. 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. 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().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 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.Parametersobject
Promise<WalletAvailability>boolean
required
boolean
required
boolean
("apple_pay" | "google_pay" | "paypal_express")[]
The wallets ranked by which sheet is native to this browser — Apple Pay first on WebKit, Google Pay first everywhere else, PayPal last — so express buttons can stack best-first. Absent on consumer-stated availability (previews) and on wires that predate it. An inline union, not payment-request’s WalletSheetType: that module already imports this one.
object
Each available wallet’s details, keyed by wallet type. Absent on consumer-stated availability (previews).
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.Parameters"apple_pay" | "google_pay" | "paypal_express"
required
object
Promise<PaymentRequestResult>string
required
Confirmation token ID, prefixed
ctok_. Confirm it server-side with your secret key."apple_pay" | "google_pay" | "paypal_express"
required
object
required
phone is E.164 where it parsed against the contact’s country, as given otherwise; country is the billing country every sheet collects.object | null
required
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.object | null
required
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.update
Change amount, lineItems and shippingOptions on this instance. Every other option is fixed at create(): create a new instance to change it.Parametersobject
required
Events
Subscribe to events below. Each method returns an unsubscribe function.onShippingAddressChange
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.ShippingAddressChangeEvent
onShippingOptionChange
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.ShippingOptionChangeEvent
onBillingAddressChange
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.BillingAddressChangeEvent
onPaymentMethodChange
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.PaymentMethodChangeEvent
onPromoCodeChange
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.PromoCodeChangeEvent
onPaymentAuthorization
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.PaymentAuthorizationEvent
onConfirmationToken
The sheet created a confirmation token, heard once the sheet has closed. This is the same result that show() returns. Returns the unsubscribe function.PaymentRequestResult
onCancel
The buyer dismissed the sheet or closed PayPal. Returns the unsubscribe function.Content 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".