Installation

The Payment Elements SDK ships as a single JavaScript bundle. Install it via npm (recommended for bundlers and frameworks) or add a <script> tag directly to your page. Both paths converge on the same CDN artifact. The npm package is a thin typed loader that injects the CDN URL at runtime.

Publishable keys

The SDK is initialized with a publishable key. The key prefix selects the API environment:

Key prefix	API environment
`live_pub_…`	Production
`test_pub_…`	Staging or test

Your secret key stays on your server and is used to authorize the tokenized payload the SDK returns.

Option 1: npm

npm install @getoverflow/payment-elements

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

const overflow = await loadOverflow('live_pub_...');
if (!overflow) return; // Guard for server-side rendering.

overflow.checkout({ /* ... */ }).mount('#checkout');

Importing the default entry starts downloading the CDN bundle as a side effect. If you need to defer that download until checkout is opened, import from /pure instead:

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

async function openCheckout() {
  const overflow = await loadOverflow('live_pub_...');
  overflow?.checkout({ /* ... */ }).mount('#checkout');
}

In server-side rendered apps (Next.js, Remix, SvelteKit, etc.), call loadOverflow from client-only code such as an effect or event handler.

TypeScript types without runtime import

If you use a bare <script> tag and want editor types, add the package as a devDependency and reference the ambient types:

/// <reference types="@getoverflow/payment-elements/types" />

Latest-only policy

The npm loader always injects the floating v1 CDN URL. Pinning and Subresource Integrity are not supported through the loader. If you need pinning or SRI, use the script-tag install described below.

Option 2: script tag

<script src="https://cdn.overflow.co/sdk/v1/payment-elements.js"></script>

Then, in your page:

<script>
  const overflow = new Overflow('live_pub_...');
  overflow.checkout({ /* ... */ }).mount('#checkout');
</script>

Choose a versioning strategy

Every deployment of the SDK is available under two URL shapes:

Floating URL (recommended default)

<script src="https://cdn.overflow.co/sdk/v1/payment-elements.js"></script>

Always serves the latest v1 release.
Cached at the edge for 5 minutes, so patch releases roll out within minutes.
You get bug fixes and non-breaking improvements without redeploying your site.
Cannot be used with Subresource Integrity, the file changes on each deploy.

Pinned URL (for SRI or strict change control)

<script
  src="https://cdn.overflow.co/sdk/v1/0.1.0-alpha.14/payment-elements.js"
  integrity="sha384-..."
  crossorigin="anonymous"
></script>

Immutable: the artifact at a pinned version never changes.
Cached for one year at the edge.
Compatible with Subresource Integrity (see below).
You control the upgrade cadence by updating the version in your HTML.

Subresource Integrity (SRI)

SRI is available on pinned script-tag installs. Fetch the sidecar hash for the version you want:

https://cdn.overflow.co/sdk/v1/<version>/payment-elements.js.sha384

The sidecar is a single ASCII line of the form sha384-<base64>. Copy it verbatim into the integrity attribute and set crossorigin="anonymous" so the browser can enforce integrity on the cross-origin script.

<script
  src="https://cdn.overflow.co/sdk/v1/0.1.0-alpha.14/payment-elements.js"
  integrity="sha384-...paste-sidecar-verbatim..."
  crossorigin="anonymous"
></script>

You can verify a local copy with openssl:

curl -s https://cdn.overflow.co/sdk/v1/0.1.0-alpha.14/payment-elements.js \
  | openssl dgst -sha384 -binary \
  | openssl base64 -A

Environment hosts

For each environment, the same URL shapes exist under a different host:

Environment	Host
Production	`https://cdn.overflow.co`
Staging	`https://cdn-stage.overflow.co`
Demo	`https://cdn-demo.overflow.co`

The host does not determine which Overflow API is called. The publishable key does: live_pub_… always routes to production, test_pub_… always routes to staging.

Preload for above-the-fold checkout

If checkout is critical to first paint, preload the bundle from <head>:

<link
  rel="preload"
  as="script"
  href="https://cdn.overflow.co/sdk/v1/payment-elements.js"
  crossorigin="anonymous"
/>
<script
  src="https://cdn.overflow.co/sdk/v1/payment-elements.js"
  crossorigin="anonymous"
  defer
></script>

For pinned installs, mirror the integrity attribute on both tags. Do not preload on landing pages where the shopper may never reach checkout. Unused preloads waste bandwidth and log a console warning.

Content Security Policy

If your site sets a Content Security Policy, allow the CDN host in script-src and connect-src:

script-src 'self' https://cdn.overflow.co;
connect-src 'self' https://cdn.overflow.co https://server.overflow.co;

For staging, add https://cdn-stage.overflow.co and https://server.stage.overflow.co. If you use address autocomplete, add https://maps.googleapis.com to script-src and connect-src. See Address autocomplete.

Get started

Elements

Options

Events

Theming

Guides

Publishable keys

Option 1: npm

TypeScript types without runtime import

Latest-only policy

Option 2: script tag

Choose a versioning strategy

Floating URL (recommended default)

Pinned URL (for SRI or strict change control)

Subresource Integrity (SRI)

Environment hosts

Preload for above-the-fold checkout

Content Security Policy

Next steps

Quickstart

Concepts

​Publishable keys

​Option 1: npm

​TypeScript types without runtime import

​Latest-only policy

​Option 2: script tag

​Choose a versioning strategy

​Floating URL (recommended default)

​Pinned URL (for SRI or strict change control)

​Subresource Integrity (SRI)

​Environment hosts

​Preload for above-the-fold checkout

​Content Security Policy

​Next steps

Quickstart

Concepts

Publishable keys

Option 1: npm

TypeScript types without runtime import

Latest-only policy

Option 2: script tag

Choose a versioning strategy

Floating URL (recommended default)

Pinned URL (for SRI or strict change control)

Subresource Integrity (SRI)

Environment hosts

Preload for above-the-fold checkout

Content Security Policy

Next steps