Payments - Whop Docs

This page documents @whop/elements@1.0.0-beta.0 and @whop/elements-react@1.0.0-beta.0.

Pre-release, not yet part of a stable release.

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://js.whop.cloud/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.

string

Account ID, prefixed biz_. Omit only when calling static methods without a collection surface.

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.

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.

string

Return URL for off-site bank or 3DS steps. Defaults to the mounting page.

"off_session" | "on_session"

Displays consent to save the payment method and marks the token for off_session or on_session use.

WalletAvailability

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

{ id: string; clientSecret: string; }

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.

string

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

number

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

{ enabled?: string[] | undefined; disabled?: string[] | undefined; include_platform_defaults?: boolean | 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.

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.

The options are a union. Provide exactly one of these shapes, plus the shared event callbacks below:

{ accountId: string; plan: string; offerAmounts?: undefined; returnUrl?: string; setupFutureUsage?: "off_session" | "on_session"; previewWalletAvailability?: WalletAvailability; checkoutSession?: { id: string; clientSecret: string; } }
{ accountId: string; currency: string; amount: number; offerAmounts?: { feeInclusive: number; feeFree: number; }; paymentMethodConfiguration?: { enabled?: string[] | undefined; disabled?: string[] | undefined; include_platform_defaults?: boolean | undefined; }; returnUrl?: string; setupFutureUsage?: "off_session" | "on_session"; previewWalletAvailability?: WalletAvailability; checkoutSession?: { id: string; clientSecret: string; } }
{ accountId?: undefined; plan?: undefined; currency?: undefined; amount?: undefined; offerAmounts?: undefined; paymentMethodConfiguration?: undefined; returnUrl?: string; setupFutureUsage?: "off_session" | "on_session"; previewWalletAvailability?: WalletAvailability; checkoutSession?: { id: string; clientSecret: string; } }

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. Signature: ((loading: boolean) => void)

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. 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(…). Runs on your page (host-side), not in the controller iframe. Signature:

(input: { billingDetails?: { email?: string | undefined; name?: 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; }>

`update`

Merges new handle options into every mounted element. In React, change the namespace props instead. Signature: (options: Partial<PaymentsOptions>) => void

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. 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. Signature:

(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; }>

Resources

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

PaymentRequest

Low-level Apple Pay or Google Pay 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 sheet, 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.

Types

Named types used throughout this page.

`WalletAvailability`

Host-probed wallet availability after checking offered methods, device capability, and Google Pay origin approval.

`applePay`

Signature: boolean

`googlePay`

Signature: boolean

`CardNetworkArt`

The slice of a matrix card network the fields need: identity plus the API-served square art.

`brand`

`icons`

Signature: { square: { light: { svg: string; }; dark: { svg: string; }; }; }

`PaymentRequestLineItem`

Fields on PaymentRequestLineItem.

`label`

Signature: string

`amount`

Minor units, same as amount. Signature: number

`PaymentRequestShippingOption`

Fields on PaymentRequestShippingOption.

`id`

Signature: string