> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Overflow Payment Elements SDK via npm or CDN script tag.

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

```bash theme={null}
npm install @getoverflow/payment-elements
```

```javascript theme={null}
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:

```javascript theme={null}
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:

```typescript theme={null}
/// <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

```html theme={null}
<script src="https://cdn.overflow.co/sdk/v1/payment-elements.js"></script>
```

Then, in your page:

```html theme={null}
<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)

```html theme={null}
<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)

```html theme={null}
<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.

```html theme={null}
<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`:

```bash theme={null}
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>`:

```html theme={null}
<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](/payment-elements/elements/address/autocomplete).

## Next steps

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/payment-elements/quickstart">
    Render your first payment form.
  </Card>

  <Card title="Concepts" icon="book" href="/payment-elements/concepts">
    Elements, options, events, and theming.
  </Card>
</CardGroup>