> ## 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.

# Accept a payment

> End-to-end guide for taking a payment with the Checkout element.

Checkout is the fastest integration path. One mount renders shopper contact, addresses, and a payment-method selector; one submit returns a tokenized payload for your server to authorize.

If you need to lay fields out across multiple screens, mount the individual elements yourself. See [Compose standalone elements](/payment-elements/guides/compose-standalone-elements).

## Prerequisites

* A publishable key from the Dashboard. Use `live_pub_…` in production and `test_pub_…` in test.
* A server endpoint that can accept the tokenized payload and call the Overflow authorize API.
* A page where you can add a script tag or an npm import and an empty `<div>`.

## 1. Install the SDK

Either import the loader from npm:

```javascript theme={null}
import { loadOverflow } from '@getoverflow/payment-elements';

const overflow = await loadOverflow('live_pub_...');
```

Or drop the CDN script tag into your page and use the global `Overflow` constructor:

```html theme={null}
<script src="https://cdn.overflow.co/sdk/v1/payment-elements.js"></script>
<script>
  const overflow = new Overflow('live_pub_...');
</script>
```

See [Installation](/payment-elements/installation) for details on Subresource Integrity, versioning, and the loader's SSR-safe return contract.

## 2. Add a host element

Checkout mounts into a single DOM node you provide.

```html theme={null}
<div id="checkout"></div>
```

## 3. Mount Checkout

Configure the payment methods you accept, opt into contact fields, and mount:

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

checkout.mount('#checkout');
```

* `paymentMethods` accepts any subset of `'card'`, `'bank'`, `'applePay'`, and `'googlePay'`.
* Wallet methods that fail the device-availability probe are filtered out at runtime.
* Order of the array controls the order the methods appear.

## 4. Track readiness and validity

Use `onReady` to remove a loading skeleton, and `onChange.complete` to gate your own UI (an external submit button, an analytics event, and so on).

```javascript theme={null}
checkout.on('onReady', () => {
  document.querySelector('#skeleton').hidden = true;
});

checkout.on('onChange', ({ complete, availableMethods, unavailableMethods }) => {
  renderMethodBadges(availableMethods, unavailableMethods);
  externalSubmit.disabled = !complete;
});
```

## 5. Handle submit

Checkout drives its own submit button. When the shopper authorizes, `onSubmit` fires with a discriminated value envelope:

```javascript theme={null}
checkout.on('onSubmit', async ({ value }) => {
  const res = await fetch('/your-backend/authorize', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(value),
  });

  if (!res.ok) {
    showError(await res.text());
    return;
  }

  showConfirmation(await res.json());
});
```

The `value` shape is `{ method, contact, billingAddress, shippingAddress, [methodKey] }` where `method` is one of `'card'`, `'bank'`, `'applePay'`, or `'googlePay'` and the per-method key holds the tokenized payment credentials.

Never send the payload directly to the payment gateway. Your server calls the Overflow authorize endpoint with the tokenized payload; see the [authorize a payment API reference](/api-reference/payments/authorize-payment).

## 6. Handle errors

```javascript theme={null}
checkout.on('onError', ({ code, message, fieldErrors }) => {
  switch (code) {
    case 'validation_failed':
      paintFieldErrors(fieldErrors);
      break;
    case 'tokenization_failed':
    case 'network':
    case 'plaid_link_failed':
    case 'wallet_failed':
      toast(message);
      break;
    default:
      toast('Something went wrong. Try again.');
  }
});
```

`message` is already localized and safe to render. Do not surface `cause`; it carries raw diagnostics.

See [`onError`](/payment-elements/events/on-error) and [Error codes](/payment-elements/events/error-codes) for the full code list.

## 7. Ship it

* Match the brand: pass `appearance` to `new Overflow(...)`. See [Theming](/payment-elements/theming/overview).
* Enable wallets: see [Wallets](/payment-elements/guides/wallets).
* Localize the country list: see [Localization](/payment-elements/options/localization).

## See also

* [Quickstart](/payment-elements/quickstart)
* [Checkout introduction](/payment-elements/elements/checkout/introduction)
* [Payment methods overview](/payment-elements/elements/payment-methods/overview)
* [Handle validation errors](/payment-elements/guides/handle-validation-errors)