Upcoming — generated from the latest merged element source; documents unreleased development. Use the channel picker at the top of the sidebar for the docs of a published release.
Payments group. Render <PaymentElement /> inside it (React), or call payments.create('payment', { … }) on the handle (vanilla) — consumer props and on<Event> callbacks both go in the create options / JSX props.
Exclusive — when using
PaymentElement, you can’t mount CardElement or CardFields in the same Payments handle: these are alternatives — mount one at a time; destroy it to mount another.Preview
A live, interactive demo of this element with sample data:Usage
Props
{ billingDetails?: "full" | "minimal" | "never" | undefined; }
Which internal collection blocks render.
billingDetails: 'minimal' (default) collects each method’s DECLARED payment minimum — exactly the billing fields the method’s matrix entry declares (card: name on card, country, postal code — never a street address; most redirect and wallet methods declare nothing and render no block at all). 'full' opts every fresh method into name plus the complete country format — for hosts who want a full billing address (tax-style collection is a checkout concern, not a payment requirement). 'never' hides the block — pass the address in createConfirmationToken({ billingDetails }) instead. The block’s country select offers only the countries the method supports for the charge currency (a single-country method locks it). Defaults to {"billingDetails":"minimal"}."accordion" | "horizontal"
Presentation of the method picker: ‘accordion’ (default) stacks the methods in a vertical list, each expanding its detail inline; ‘horizontal’ lays the methods out as a row of equal-width tiles (never scrolling — beyond four methods the row ends in a More tile whose native selector lists the rest, and a method picked there holds the last tile spot until the next pick) with the selected method’s detail below. Selection and confirm behavior are identical in both. Defaults to
"accordion".boolean
Accordion layout only: render each method as its own visually separate card with spacing between items, instead of the fused list. Ignored while
layout is ‘horizontal’. Defaults to false.string[]
Display ordering of the methods, in every layout: listed types render first in the given order, unlisted types keep their relative order after them. Presentation only — never affects which methods are available. Defaults to
[].boolean
Select the first offered method automatically once the methods resolve (default true) — respects
order and emits selected + change exactly like a click. One-shot: it never re-fires after the buyer interacts, and it does nothing when no method is offered. Set false to mount with nothing selected. Separately from this flag, when a live charge update drops the SELECTED method off the list the selection falls back to the first offered method (an element with nothing selected stays blank). Defaults to true.Events
Pass a callback in the create options (or React prop) to receive these.onChange
The selection changed — complete: true means a method is chosen (and, for card, its fields are filled; for methods declaring required inputs, those are filled and valid) so the confirm can run; drive your pay button off it. method carries the selected entry’s matrix metadata (category, per-currency country list, amount bounds) so your page can react — e.g. narrow its own country field.
Signature: ((payload: { complete: boolean; type?: string | 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)
onAddressChange
The billing address the element collects itself changed — quote tax off it, rate your own shipping off it, or drive any address-dependent part of your page off it. Carries the whole postal address: country (ISO2) always, plus line1, line2, city, state and postal_code whenever the country’s format collects them (a key is absent when the form has no value for it — several countries have no state or no postal code at all). Debounced ~300ms and emitted only on a real change, so it maps one-to-one onto a quote. complete: true means the whole billing block is filled and valid. Fires only while the element collects the address itself — with fields.billingDetails: 'never', or beside a live address element (which collapses the internal block), drive your quote off that surface’s own change instead.
Signature: ((payload: { complete: boolean; address: { line1?: string | undefined; line2?: string | undefined; city?: string | undefined; state?: string | undefined; postal_code?: string | undefined; country: string; }; }) => void)
onLoaderStart
Fired the moment the element’s own loading skeleton has painted inside its frame — the earliest point a consumer-managed loading state can hand off without ever exposing a blank. Always precedes onReady; most consumers only need onReady.
Signature: (() => void)
onReady
Fired once the element has booted and painted its first complete frame.
Signature: (() => void)
onError
Fired when the element fails to load or crashes; the element shows its own error fallback. message is human-readable; framework refusals also carry code (e.g. HOST_SOURCE_FAILED, with sourceKey naming the failed hostState key) so hosts can switch on codes, never message text.
Signature: ((e: { message: string; code?: string | undefined; sourceKey?: string | undefined; }) => void)
Methods
Call these on the element handle — the return ofcreate (vanilla) or the component ref (React).
select
Select a payment method imperatively. select('cashapp') runs the same path a buyer’s click does — the tile expands, selected and change fire (a card selection stays complete: false until its fields are filled). A type that isn’t offered — unknown, seller-disabled, or amount-gated off the list — refuses with code: 'METHOD_NOT_OFFERED'. select(null) clears the selection, emitting change { complete: false }. Pair with autoSelect={false} (which mounts the element blank) for full external control of the selection.
Signature: (input: string | null) => Promise<void>
mount
Place the element on the page: appends its container to target (a CSS selector or an element) and starts loading. Nothing renders until this is called. React consumers never call it — the component mounts itself.
Signature: (target: string | HTMLElement) => void
destroy
Remove the element from the page and release its frame and subscriptions. Safe to call more than once. React consumers never call it — unmounting the component does it.
Signature: () => void
update
Change this element’s consumer props after mount — it re-renders with the merged props. React consumers never call it — updating the JSX props does the same.
Signature: (options: Partial<PaymentElementProps>) => void
Styling
Each part below is a stable class name — safe to depend on. Restyle a part by mapping its class to a style declaration object underappearance.classes (properties camelCase or kebab-case, values as strings with units — the same shape as React’s style prop). The element renders in its own frame, so page stylesheets can’t reach it: these declarations are sanitized against a safe-property allowlist and injected inside the frame for you.
appearance prop on <Payments>; appearance also applies globally at WhopElements({ appearance }).