> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout

> A single composite element that renders a full payment form.

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

```html theme={null}
<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:

1. **Contact** (opt-in; pass `contact` to show it).
2. **Shipping address** (opt-in; pass `shippingAddress`).
3. **Billing address** (opt-in; pass `billingAddress`).
4. **Payment methods** (required; pass `paymentMethods`).
5. **Custom elements** (opt-in; pass `customElements`).

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

* [Contact section](/payment-elements/elements/checkout/sections/contact)
* [Shipping address section](/payment-elements/elements/checkout/sections/shipping-address)
* [Billing address section](/payment-elements/elements/checkout/sections/billing-address)
* [Payment methods section](/payment-elements/elements/checkout/sections/payment-methods)
* [Custom elements section](/payment-elements/elements/checkout/sections/custom-elements)

The same Card, Bank, and Wallet elements documented under [Payment methods](/payment-elements/elements/payment-methods/overview) 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:

```javascript theme={null}
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`.

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

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

```javascript theme={null}
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:

```javascript theme={null}
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](/api-reference/payments/authorize-payment).

## 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](/payment-elements/events/overview).

## Next steps

<CardGroup cols={2}>
  <Card title="How it works" icon="diagram-project" href="/payment-elements/elements/checkout/how-it-works">
    Lifecycle, section ordering, and the submit flow.
  </Card>

  <Card title="Best practices" icon="lightbulb" href="/payment-elements/elements/checkout/best-practices">
    Submit-button gating, validation, and accessibility.
  </Card>

  <Card title="Accept a payment" icon="credit-card" href="/payment-elements/guides/accept-a-payment">
    End-to-end integration walkthrough.
  </Card>

  <Card title="Payment methods" icon="wallet" href="/payment-elements/elements/payment-methods/overview">
    Configure card, bank, and wallet options.
  </Card>
</CardGroup>