Migrating from Stripe

This guide covers the SDK-level migration only: loading, mounting, options, events, and submit flow. Data migration (customers, saved payment methods, stored tokens) is a separate operations topic and is not covered here.

Migrating stored payment credentials and historical customer data requires a separate handoff with the Overflow team. That content is not yet published. Contact support when you are ready to plan that work.

Before you start

Get a test_pub_… publishable key for your staging environment and a live_pub_… key for production. See Concepts.
Confirm your server has an authorize endpoint wired to Overflow. See the authorize a payment API reference.
Read the Checkout element overview. Checkout is the recommended primary path and maps most directly to Stripe’s Payment Element.

Concept mapping

Stripe concept	Payment Elements equivalent
`loadStripe(pk)`	`loadOverflow(pk)` (async loader). See Installation.
`Elements` provider	`new Overflow(pk)` instance. Pass the instance to element factories.
`elements.create('payment')`	`overflow.checkout(options)`
`elements.create('card')`	`overflow.card(options)`
`elements.create('iban')` / bank	`overflow.bank(options)`
`elements.create('paymentRequestButton')`	`overflow.applePay(options)` and `overflow.googlePay(options)` (separate elements)
`elements.create('address')`	`overflow.billingAddress(options)` / `overflow.shippingAddress(options)`
`elements.create('linkAuthentication')`	`overflow.email(options)` and `overflow.phone(options)`
`element.mount('#slot')`	`element.mount('#slot')` (same signature)
`element.unmount()` / `destroy()`	`element.unmount()` (removable) and `element.destroy()` (unmount + drop callbacks). Instance teardown: `overflow.destroy()`.
`elements.submit()` / `stripe.confirmPayment(...)`	`element.submit()` is `void`. Success → `onSubmit` with `{ value }`. Failure → `onError` with `{ code, message, fieldErrors? }`. Forward `value` from `onSubmit` to your server.
`paymentIntent.client_secret` flow	No client secret in the browser. Server calls authorize with the authorize-ready payload from `onSubmit` (encrypted envelope for card, `walletToken` for wallets).
Appearance API (`appearance.variables`)	`appearance.variables`. See Theming
Appearance rules / element-scoped CSS	`appearance.elements.<name>` overrides. See Element-scoped overrides
Locale option	`locale` option. See Localization
`element.on('change', fn)`	`element.on('onChange', fn)`. See onChange
`element.on('ready', fn)`	`element.on('onReady', fn)`. See onReady
`element.on('focus' / 'blur', fn)`	`element.on('onFocus', fn)` / `element.on('onBlur', fn)`. See Focus and blur
Stripe error object (`type`, `code`, `message`)	`onError` payload `{ code, message, fieldErrors?, cause? }` (`OverflowErrorEvent`). See Error codes.

Loading and initialization

Stripe:

import { loadStripe } from '@stripe/stripe-js';
const stripe = await loadStripe('pk_test_...');
const elements = stripe.elements({ appearance, locale: 'en' });

Payment Elements:

import { loadOverflow } from '@getoverflow/payment-elements';

const overflow = await loadOverflow('test_pub_...', {
  appearance: { variables: { colorPrimary: '#111827' } },
  locale: 'en',
});
const checkout = overflow.checkout({
  paymentMethods: ['card', 'bank'],
});

appearance and locale on the loader options (or new Overflow(pk, { … })) set the primary theme for every element. Passing appearance on a specific element is an optional per-element override. Notes:

Publishable keys use the live_pub_… and test_pub_… prefixes. There is no separate live/test toggle in code; the prefix determines the environment.
The npm package is a small loader that fetches the SDK from the CDN. There is no bundled SDK build. See Installation.
The primary theme lives on the Overflow instance — pass appearance to new Overflow(pk, { appearance }) (or mutate it later with overflow.update({ appearance })) and every element inherits it.

Mounting

The mount() signature is compatible:

// Stripe
const card = elements.create('card', { hidePostalCode: true });
card.mount('#card');

// Payment Elements
const card = overflow.card({
  fields: { postalCode: { hidden: true } },
});
card.mount('#card');

Only one instance may be mounted to a given selector at a time. Call unmount() before re-mounting.

Options mapping

Options are set per element in the factory call, not on a shared elements object.

Stripe option	Payment Elements option
`disabled`	`disabled`
`hidePostalCode: true` on card	`fields.postalCode.hidden: true` on card
`showIcon`	Not exposed. Icons render based on element and theme.
Appearance `variables`	`appearance.variables`. See Token reference.
Appearance `rules`	`appearance.elements.<name>` overrides. See Element-scoped overrides.
`fields.billingDetails`	`fields` on the address or contact element. See Address and Contact.
`terms` copy	Not exposed; consent copy is merchant-owned outside the element.
`wallets: { applePay: 'auto' }`	Mount `overflow.applePay()` explicitly. See Wallets.

Optional fields document their defaults on each page under Options.

Event mapping

Handlers are attached with .on('onEventName', handler) after the element is created. Event name strings include the on prefix — same idea as Stripe’s .on, different event name strings.

// Stripe
card.on('ready', () => {});
card.on('change', (event) => { setDisabled(!event.complete || !!event.error); });
card.on('focus', () => {});
card.on('blur', () => {});

// Payment Elements
const card = overflow.card();
card
  .on('onReady', () => {})
  .on('onChange', ({ complete, errors }) => {
    setDisabled(!complete || (errors?.length ?? 0) > 0);
  })
  .on('onFocus', () => {})
  .on('onBlur', () => {});

The full event surface for each element is documented in Events. Highlights:

onChange carries complete, value, and optional errors (FieldError[]). See onChange.
onSubmit fires after a successful submit() (or wallet sheet success) with a non-null value to forward to your server. See onSubmit.
Validation failures from submit() emit onError with code: 'validation_failed' and fieldErrors; they are not returned from submit().
Wallet buttons emit onClick synchronously so you can validate the cart before showing the sheet. See onClick.
Shopper abandonment fires onExit and is not an error. See onExit.

Submit and authorize flow

There is no client secret in the browser. The browser produces an authorize-ready payload (encrypted envelope for card, walletToken for wallets); the server authorizes. element.submit() returns void. Register onSubmit and onError before calling it — success and failure both arrive as events.

// Stripe
const { error } = await stripe.confirmPayment({
  elements,
  confirmParams: { return_url: 'https://example.com/return' },
});

// Payment Elements — register handlers, then call submit()
checkout.on('onSubmit', async ({ value }) => {
  await fetch('/orders/authorize', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ elementPayload: value, orderId }),
  });
});

checkout.on('onError', ({ code, message, fieldErrors }) => {
  if (code === 'validation_failed') {
    // Render fieldErrors inline. See handle-validation-errors.
    return;
  }
  console.error(code, message, fieldErrors);
});

// Merchant-owned Pay button (Checkout may also drive its own submit UI):
document.querySelector('#pay')?.addEventListener('click', () => {
  checkout.submit(); // void — do not await; do not destructure
});

On the server, call the Overflow authorize endpoint with your secret key. See the authorize a payment API reference for the request and response shape.

Validation and error handling

Validation errors surface on onChange.errors while the shopper types, and as an onError event with code: 'validation_failed' and fieldErrors when submit() fails. See Handle validation errors.
Error payloads follow OverflowErrorEvent: { code, message, fieldErrors?, cause? }. For Checkout, each FieldError may include an optional source ('contact' | 'billingAddress' | 'shippingAddress' | 'paymentMethod' | 'customElement') — fieldErrors is always an array, not an object keyed by section. See Field errors and Error codes.
Wallet unavailability (Apple Pay or Google Pay not offered on this device) is not an error. Fall back to the primary Checkout element.

Theming

Set high-level tokens with appearance.variables. See Token reference.
Use appearance.size and appearance.shadowSize presets rather than per-element pixel values. See Sizing presets and Shadows.
Element-scoped overrides live under appearance.elements.<name>. See Element-scoped overrides.
The element renders inside an isolated tree; page CSS does not leak in. See CSS isolation.

What this guide does not cover

Data migration (customers, saved payment methods, stored tokens), drop-in API compatibility, and server-side concerns like webhooks and disputes are out of scope. Contact support to plan data migration.

Get started

Elements

Options

Events

Theming

Guides

Before you start

Concept mapping

Loading and initialization

Mounting

Options mapping

Event mapping

Submit and authorize flow

Validation and error handling

Theming

What this guide does not cover

See also

​Before you start

​Concept mapping

​Loading and initialization

​Mounting

​Options mapping

​Event mapping

​Submit and authorize flow

​Validation and error handling

​Theming

​What this guide does not cover

​See also

Before you start

Concept mapping

Loading and initialization

Mounting

Options mapping

Event mapping

Submit and authorize flow

Validation and error handling

Theming

What this guide does not cover

See also