Checkout

The checkout element renders a complete payment form in one mount. It composes the same elements you can use standalone (contact, addresses, payment methods, custom fields) and wires them together so you submit once, validate once, and receive a single tokenized payload. Reach for Checkout when you want a turnkey form. Reach for standalone elements when you need to lay out fields across multiple steps or screens.

When to use Checkout

You want a single drop-in that collects everything: shopper contact, addresses, and a payment method.
You want the SDK to manage section order, conditional visibility, and a single submit lifecycle.
You want one event stream for the whole form.

Minimal example

<div id="checkout"></div>

<script>
  const overflow = new Overflow('live_pub_...');

  const checkout = overflow.checkout({
    paymentMethods: ['card', 'bank'],
    contact: { email: {}, fullName: {} },
  });

  checkout.mount('#checkout');
</script>

That single call renders shopper email and name, then a card/bank picker. Each subsection is themed, validated, and tokenized as part of the parent element.

What it composes

Checkout renders the following sections, in this default order:

Contact (opt-in; pass contact to show it).
Shipping address (opt-in; pass shippingAddress).
Billing address (opt-in; pass billingAddress).
Payment methods (required; pass paymentMethods).
Custom elements (opt-in; pass customElements).

Each subsection accepts the same options as its standalone element. See the per-section pages:

The same Card, Bank, and Wallet elements documented under Payment methods are configured here as nested Checkout options.

Contact is opt-in

Omitting contact (or passing {}) renders Checkout with no contact fields. To collect shopper contact details, explicitly include the keys you need:

overflow.checkout({
  paymentMethods: ['card'],
  contact: {
    email: {},
    fullName: {},
    phone: {},
    companyName: {},
  },
});

Selecting payment methods

Pass a list of method names to paymentMethods. Render order matches array order; the first available method is selected on mount unless you set defaultPaymentMethod.

const checkout = overflow.checkout({
  paymentMethods: ['applePay', 'googlePay', 'card', 'bank'],
  defaultPaymentMethod: 'card',
});

Per-method options accepted by standalone elements apply here under matching keys:

overflow.checkout({
  paymentMethods: ['card', 'bank'],
  card: { fields: { postalCode: { hidden: true } } },
  bank: { mode: { default: 'manual' } },
});

The submitted value

onSubmit returns a payload tagged with the selected method:

checkout.on('onSubmit', ({ value }) => {
  // value.method: 'card' | 'bank' | 'applePay' | 'googlePay'
  // value.contact, value.billingAddress, value.shippingAddress (when configured)
  // value.customElements (when configured)
  // Method-specific payload lives on the matching key: value.card, value.bank, etc.
  fetch('/api/authorize', {
    method: 'POST',
    body: JSON.stringify(value),
  });
});

Inspect value.method to know which payment branch fired, then forward the whole payload to your server. Your server calls the Overflow API to authorize the charge. See the authorize a payment API reference.

Events

Checkout emits the standard element events:

onReady: the form is mounted and interactive.
onChange: fires with { complete, value, errors } on any field change.
onSubmit: fires after a successful submit() with the tokenized payload.
onError: fires when a submit fails.
onClick, onExit: fire from the wallet path (Apple Pay / Google Pay) with value.method set.

Errors from any section carry a source tag: 'contact', 'billingAddress', 'shippingAddress', 'paymentMethod', or 'customElement'. See Events overview.

Next steps

How it works

Lifecycle, section ordering, and the submit flow.

Best practices

Submit-button gating, validation, and accessibility.

Accept a payment

End-to-end integration walkthrough.

Payment methods

Configure card, bank, and wallet options.

Get started

Elements

Options

Events

Theming

Guides

When to use Checkout

Minimal example

What it composes

Contact is opt-in

Selecting payment methods

The submitted value

Events

Next steps

How it works

Best practices

Accept a payment

Payment methods

​When to use Checkout

​Minimal example

​What it composes

​Contact is opt-in

​Selecting payment methods

​The submitted value

​Events

​Next steps

How it works

Best practices

Accept a payment

Payment methods

When to use Checkout

Minimal example

What it composes

Contact is opt-in

Selecting payment methods

The submitted value

Events

Next steps