Payments - Whop Docs

This page documents @whop/elements@1.9.0 and @whop/elements-react@1.9.0.

Since v1.0.0.

Playground

Assemble the elements with example data. Drive the controls, add and arrange elements, and watch events fire live:

import { WhopElements, Payments } from "@whop/elements-react";
import { loadWhop } from "@whop/elements";

function Example() {
  return (
    <WhopElements elements={loadWhop()}>
      <Payments /* options */>
        {/* mount elements here */}
      </Payments>
    </WhopElements>
  );
}

<script src="https://cdn.whop.com/elements/amber/elements.js" data-whop-elements></script>
<script type="module">
  const payments = window.WhopElements().payments.create({ /* options */ });
</script>

Options

Pass these to whop.payments.create({ … }), or as props on <Payments> in React.

Pass exactly one of these combinations:

accountId and plan
accountId, currency, and amount
accountId, mode: "setup", and currency
none of plan, currency, amount, or mode

string

Account ID, prefixed biz_. Omit only when calling static methods without an account surface.

"payment" | "setup"

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.

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.

object

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.

Show properties

number

required

number

required

string

Return URL for off-site bank or 3DS steps. Defaults to the mounting page. The buyer lands there whatever the outcome, with payment (or setup), status (succeeded, failed, canceled, or a still-pending status such as processing), and client_secret appended, so branch on status before showing a success page.

"off_session" | "on_session"

A setup saves the payment method for off_session use, the only usage a setup accepts.

WalletAvailability

Wallet availability override for deterministic previews. Live checkouts probe the host.

Show properties

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 properties

WalletDetails

Show properties

WalletButtonArt

The wallet’s official button art. Absent when none is published.

Show properties

object

required

For light pages.

Show properties

string

required

string

required

object

required

For dark pages.

Show properties

string

required

string

required

WalletDetails

Show properties

WalletButtonArt

The wallet’s official button art. Absent when none is published.

Show properties

object

required

For light pages.

Show properties

string

required

string

required

object

required

For dark pages.

Show properties

string

required

string

required

WalletDetails

Show properties

WalletButtonArt

The wallet’s official button art. Absent when none is published.

Show properties

object

required

For light pages.

Show properties

string

required

string

required

object

required

For dark pages.

Show properties

string

required

string

required

string

Lowercase three-letter ISO 4217 currency code. It filters the payment-method matrix.

number

Payment amount in minor units. Methods whose bounds exclude it aren’t offered.

object

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.

Show properties

string[]

boolean

Appearance

Visual customization for this group’s elements. Overrides the global WhopElements({ appearance }). Change it live with update({ appearance }).

WhopElementsLocale

Locale for this group’s element UI text. Set it to one of the app’s built locales to override the global configuration. Any other value falls back to the default locale.

Events

Pass callbacks in the create options or React props.

`onLoadingChange`

Runs when the grouped loading state changes. The value is true while any mounted element is still loading.

boolean

Methods

Call these on the Payments handle from whop.payments.create({ … }) or usePayments().

`createConfirmationToken`

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, 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. Parameters

object

required

Hide properties

object

Show properties

string

object

Show properties

string

Returns Promise<object>

string

required

string

required

`update`

Merges new handle options into every mounted element. In React, change the namespace props instead. Parameters

Partial<PaymentsOptions>

required

`destroy`

Destroys every element and sub-controller this handle created, removes the controller frame, and releases its subscriptions. You can call it more than once, but a destroyed handle refuses any other call — create a new handle to start over. React removes the group automatically when the provider unmounts.

Static methods

Call these without mounting: whop.payments.<method>(…) in vanilla or useWhop().payments.<method>(…) in React.

`handleNextAction`

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. Parameters

object

required

Hide properties

string

required

string

number

Returns Promise<object>

string

required

boolean

required

object | null

required

Show properties

string | null

Resources

Create these SDK objects without mounting an element. Each has its own page:

PaymentRequest

Low-level Apple Pay, Google Pay, or PayPal sheet for custom buttons, express checkout, and shipping callbacks. Wallet tiles automate this flow through payments.createConfirmationToken. Await canMakePayment() to check availability and prime the wallet, then call show(type) synchronously in the user-interaction handler. The resolved ctok is a ctok_-prefixed confirmation token. Confirm it server-side like an element-minted token. A PayPal token charges at most the total PayPal showed the buyer.

Content security policy

Some of this group’s work 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".

Requirement	Directive	Production source	Sandbox source
Plaid Link’s script	`script-src`	`https://cdn.plaid.com`	Same
↳ Plaid Link’s frame, which Plaid’s script opens	`frame-src`	`https://cdn.plaid.com`	Same
↳ Plaid’s API, which Plaid’s script calls	`connect-src`	`https://production.plaid.com`	`https://sandbox.plaid.com`

Elements

The elements this group mounts. Each has its own page:

AddressElement

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.

EmailElement

Collects the buyer’s email and passes it to payments.createConfirmationToken() while mounted. Explicit billingDetails.email wins. A matching Whop account shows optional sign-in with code verification. Successful sign-in unlocks saved payment methods in the payment element. Buyers can continue as guests.

TaxIdElement

Collects a business tax registration accepted by the API. Labels use buyer-facing names. The placeholder matches the selected format. country preselects a type. onChange emits committed pairs. The host supplies API validation errors.

BrandingElement

Required — the other elements except AddressElement, EmailElement, and TaxIdElement wait for it. 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.

Alternatives. Mount one at a time. Destroy it before mounting another:

PaymentElement

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.

CardElement

Prearranged fields for card number, expiration, and security code. Create with payments.create("card"), enable your payment button from onChange, and confirm with payments.createConfirmationToken(). Card numbers remain in PCI-isolated hosted fields. layout supports stacked (default) and compact.

CardFields

Three separately mountable, PCI-isolated card fields for custom layouts: number, expiration, and security code. Create with payments.create("cardFields"), place each field, enable your payment button from onChange, and confirm with payments.createConfirmationToken(). Card numbers remain in hosted fields. (sub-controller, 3 elements)

​Playground

​Options

​Events

​onLoadingChange

​Methods

​createConfirmationToken

​update

​destroy

​Static methods

​handleNextAction

​Resources

PaymentRequest

​Content security policy

​Elements

AddressElement

EmailElement

TaxIdElement

BrandingElement

PaymentElement

CardElement

CardFields

Playground

Options

Events

`onLoadingChange`

Methods

`createConfirmationToken`

`update`

`destroy`

Static methods

`handleNextAction`

Resources

Content security policy

Elements