Concepts

Every element in Payment Elements is built on the same four concepts. Once you understand them, every element in the SDK feels familiar.

The Overflow instance

You create one Overflow instance per page and keep it. The instance owns your publishable key, page-wide options (locale, theme, validation debounce), and every element you create. Do not construct a new Overflow(...) to change options at runtime — call overflow.update({ ... }) on the existing instance instead. new Overflow(publishableKey, options) is a singleton per page. A second new Overflow(...) call logs a warning and returns the existing instance. To recreate the instance (for example, in a hot-reload dev flow), call instance.destroy() first.

const overflow = new Overflow('live_pub_...', {
  locale: 'en-US',
  appearance: { variables: { colorPrimary: '#0a3783' } },
});

Publishable keys use one of two prefixes:

live_pub_… for production.
test_pub_… for staging or test.

Call overflow.destroy() when you are done to tear down the instance and every element it created.

Elements

An element is a self-contained payment UI component you mount into a host node on your page. You create one by calling a factory on your Overflow instance.

const card = overflow.card();
const bank = overflow.bank();
const applePay = overflow.applePay();
const checkout = overflow.checkout();

Every element exposes the same lifecycle:

const element = overflow.card(options);   // create
element.on('onChange', handler);            // subscribe to events
element.mount('#host');                     // render into your DOM
element.submit();                           // submit(): void — validate, then fire onSubmit or onError
element.unmount();                          // remove from DOM
element.destroy();                          // tear down and drop every handler

Elements fall into a few categories:

Checkout: a composite element that renders a full payment form. Use it as your primary integration.
Payment methods: card, bank, applePay, googlePay. Mount standalone or nest inside Checkout.
Address elements: billingAddress, shippingAddress, with optional autocomplete.
Contact elements: email, fullName, phone, companyName.
Custom elements: text, number, select, checkbox for arbitrary metadata.
Submit button: a themed submit CTA (submitButton).

Options

Every element factory accepts an options object with a uniform shape:

Top-level keys control behavior. Examples: splitMode on fullName, defaultCountry on phone, mode on bank, paymentMethods on checkout.
fields carries per-input customization: label, placeholder, disabled, hidden, and so on.
BaseElementOptions carry the shared identity and cascade knobs: disabled, readOnly, id, ariaLabel, locale. The cascade flows from the element to its fields; per-field overrides win. required and validate are element-specific and are not accepted everywhere — card, checkout, applePay, googlePay, and submitButton reject both; bank accepts validate but not required. Check each element’s reference for the exact surface.
Compound elements (Checkout) nest the standalone options shape under each per-method key. What you configure standalone works the same way inside Checkout.

overflow.card({
  disabled: false,
  fields: {
    cardNumber: { label: 'Card number' },
    holderName: { label: 'Name on card', hidden: false },
    postalCode: { hidden: true },
  },
});

See Options overview for the shared knobs.

Events

Most elements share a common event surface (onReady, onChange, onSubmit, onError, onFocus, onBlur, onEscapeKeyPressed); wallets and submitButton add or omit events where the shape of the element differs. See Events.

Event	Fires
`onReady`	Once, when the element is mounted and interactive.
`onChange`	On every value or completeness change, with `{ value, complete, errors }`.
`onSubmit`	After a successful `.submit()` call or wallet authorization, with the authorize-ready payload (encrypted card fields, bank union, or `walletToken`).
`onError`	When validation or a runtime action fails; emits `OverflowErrorEvent` — `{ elementType, code, message, fieldErrors?, cause? }`.
`onFocus` / `onBlur`	When focus enters or leaves the element.

Wallets add onClick (for pre-sheet gating) and onExit (when the shopper dismisses the sheet). Non-wallet, non-button elements add onEscapeKeyPressed.

overflow.card()
  .on('onReady', () => console.log('ready'))
  .on('onChange', ({ complete, errors }) => {
    payButton.disabled = !complete;
  })
  .on('onSubmit', ({ value }) => forwardToServer(value))
  .on('onError', ({ code, message }) => console.error(code, message));

Subscribing to an unsupported event is rejected at compile time. See Events overview.

Theming

Pass design tokens on the Overflow instance. Every mounted element inherits them.

new Overflow('live_pub_...', {
  appearance: {
    size: 'normal',               // 'compact' | 'normal' | 'large'
    shadowSize: 'md',              // optional elevation preset
    variables: {
      colorPrimary: '#0a3783',
      colorBorder: '#ededed',
      borderRadius: '6px',
    },
  },
});

Every optional token has a documented default. Element-scoped overrides layer on top for standalone elements; sub-elements inside Checkout share the parent’s theme. See Theming.

`complete` vs `value`

Two concepts govern when a form is ready to submit:

value is the current typed or (for payment methods) authorize-ready data for an element. For payment methods it is often null until the shopper completes the fields; on onSubmit you receive the method-specific payload — card fields as an encrypted envelope (encryptedCardNumber, encryptedExpiryMonth, encryptedExpiryYear, encryptedSecurityCode, riskData, browserInfo), bank as a discriminated union ({ mode: 'manual' | 'plaid', … }), or wallets as { walletToken, walletType }. For input elements it is the current shopper input.
complete is a boolean that flips true when the element passes validation. For a card element, that means every required field is filled and format-valid; for an email element, that means the value matches the email schema.

Use complete from onChange to gate your Pay button. Read value from onSubmit to forward to your server.

card.on('onChange', ({ complete }) => {
  payButton.disabled = !complete;
});

card.on('onSubmit', ({ value }) => {
  fetch('/api/authorize', { method: 'POST', body: JSON.stringify(value) });
});

Standalone vs Checkout

You have two integration shapes:

Checkout renders shopper contact, addresses, and payment methods in one mount. One onSubmit returns the whole payload. Use this when you want a turnkey form.
Standalone mounts one element at a time. You gate your submit button on onChange.complete for each element, forward each .onSubmit payload yourself, and control the layout.

Start with Checkout unless you have a specific layout requirement it cannot meet. See Compose standalone elements for the standalone path.

Next steps

Quickstart

Mount your first element.

Checkout

Start with the composite element.

Elements

Browse every element.

Events

Full event reference.

Get started

Elements

Options

Events

Theming

Guides

The Overflow instance

Elements

Options

Events

Theming

`complete` vs `value`

Standalone vs Checkout

Next steps

Quickstart

Checkout

Elements

Events

​The Overflow instance

​Elements

​Options

​Events

​Theming

​complete vs value

​Standalone vs Checkout

​Next steps

Quickstart

Checkout

Elements

Events

The Overflow instance

Elements

Options

Events

Theming

`complete` vs `value`

Standalone vs Checkout

Next steps