Accept a payment

Checkout is the fastest integration path. One mount renders shopper contact, addresses, and a payment-method selector. Call checkout.submit() (returns void); the authorize-ready payload arrives on on('onSubmit') for your server to forward to the authorize API. If you need to lay fields out across multiple screens, mount the individual elements yourself. See 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 authorize-ready 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:

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:

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

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

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

3. Mount Checkout

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

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

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:

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 payload:

card: encrypted envelope — encryptedCardNumber, encryptedExpiryMonth, encryptedExpiryYear, encryptedSecurityCode (empty string when hidden), plus riskData and browserInfo. POST the entire envelope to your server.
bank: { mode: 'manual', manual: { encryptedBankAccountNumber, encryptedBankRoutingNumber, bankAccountType } } or { mode: 'plaid', plaid: { publicToken, account, institution } }.
applePay / googlePay: { walletToken, walletType: 'applePay' | 'googlePay', … }.

Never send the payload directly to the payment gateway. Your server calls the Overflow authorize endpoint with the payload; see the authorize a payment API reference.

6. Handle errors

checkout.on('onError', ({ code, message, fieldErrors }) => {
  switch (code) {
    case 'validation_failed':
      paintFieldErrors(fieldErrors);
      break;
    case 'tokenization_failed':
    case 'encryption_failed': // bank-only: raised when the bank field encryption key is stale. See handle-validation-errors.
    case 'network':
    case 'not_mounted':
    case 'plaid_link_failed':
    case 'wallet_failed':
    case 'unknown':
      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 and Error codes for the full code list.

7. Ship it

Match the brand: pass appearance to new Overflow(...). See Theming.
Enable wallets: see Wallets.
Localize the country list: see Localization.

Get started

Elements

Options

Events

Theming

Guides

Prerequisites

1. Install the SDK

2. Add a host element

3. Mount Checkout

4. Track readiness and validity

5. Handle submit

6. Handle errors

7. Ship it

See also

​Prerequisites

​1. Install the SDK

​2. Add a host element

​3. Mount Checkout

​4. Track readiness and validity

​5. Handle submit

​6. Handle errors

​7. Ship it

​See also

Prerequisites

1. Install the SDK

2. Add a host element

3. Mount Checkout

4. Track readiness and validity

5. Handle submit

6. Handle errors

7. Ship it

See also