Skip to main content
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.

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:
Or drop the CDN script tag into your page and use the global Overflow constructor:
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.

3. Mount Checkout

Configure the payment methods you accept, opt into contact fields, and mount:
  • 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).

5. Handle submit

Checkout drives its own submit button. When the shopper authorizes, onSubmit fires with a discriminated value envelope:
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.

6. Handle errors

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.

See also

Last modified on July 17, 2026