Checkout best practices

Show a loading state until `onReady`

Checkout renders a skeleton while it fetches your merchant configuration. Keep any external UI (a page-level spinner, disabled buttons) in a loading state until onReady fires.

checkout.on('onReady', () => {
  document.querySelector('#page-spinner').hidden = true;
});

Gate external CTAs on `onChange.complete`

If you render your own Pay button outside Checkout, disable it until the form validates:

const payButton = document.getElementById('pay');

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

complete flips true when every visible field passes validation and a payment method is selected and ready.

Authorize on the server

The onSubmit payload is tokenized and safe to POST from the browser to your server. Do not call the Overflow authorize endpoint directly from the browser: your secret key stays server-side.

checkout.on('onSubmit', async ({ value }) => {
  const res = await fetch('/api/authorize', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(value),
  });
  const result = await res.json();
  // Show success or failure UI.
});

Handle `onError`

onError fires for validation failures and runtime errors. Surface a message to the shopper and let them retry.

checkout.on('onError', ({ code, message, fieldErrors }) => {
  showBanner(message);
});

Per-field errors are also emitted inline; you only need to render your own copy when you want a page-level summary.

Retry on `UNKNOWN_KID`

If your authorize endpoint returns 400 { code: 'UNKNOWN_KID' } after a bank submission, call overflow.invalidateBankFieldEncryptionCache() and prompt the shopper to submit again. This clears the cached bank field encryption key so the next submit uses the current one.

if (result.code === 'UNKNOWN_KID') {
  overflow.invalidateBankFieldEncryptionCache();
  showBanner('Please try again.');
}

Checkout’s own retry path invokes this for you when it recognizes the error, so this pattern is mainly for standalone bank integrations.

Match your brand

Pass tokens at construction so every section shares your palette, radii, and typography:

new Overflow('live_pub_...', {
  appearance: {
    size: 'normal',
    variables: {
      colorPrimary: '#0a3783',
      colorBorder: '#ededed',
      borderRadius: '6px',
    },
  },
});

Do not set appearance on nested Checkout slots. Checkout is themed as a single cohesive unit. See Theming.

Order matters for wallets

If you want wallets prominent, list them first:

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

Wallets that are unavailable on the shopper’s device are hidden without shifting the order of the remaining methods.

Accessibility

Provide an accessible label on your surrounding page container.
Do not add tabindex overrides inside the mount host; Checkout manages focus order.
The submit button inside Checkout is a real <button> with a keyboard-navigable focus ring.

Test with `test_pub_…`

Use a test_pub_… publishable key while you build. Swap to live_pub_… for production. The same code paths run on both; only the API environment changes.

Get started

Elements

Options

Events

Theming

Guides

Show a loading state until `onReady`

Gate external CTAs on `onChange.complete`

Authorize on the server

Handle `onError`

Retry on `UNKNOWN_KID`

Match your brand

Order matters for wallets

Accessibility

Test with `test_pub_…`

Next steps

Accept a payment

Handle validation errors

​Show a loading state until onReady

​Gate external CTAs on onChange.complete

​Authorize on the server

​Handle onError

​Retry on UNKNOWN_KID

​Match your brand

​Order matters for wallets

​Accessibility

​Test with test_pub_…

​Next steps

Accept a payment

Handle validation errors

Show a loading state until `onReady`

Gate external CTAs on `onChange.complete`

Authorize on the server

Handle `onError`

Retry on `UNKNOWN_KID`

Match your brand

Order matters for wallets

Accessibility

Test with `test_pub_…`

Next steps