Installation

Frame.js ships from Frame's CDN as a single script. There is no npm package and no bundler integration — you embed the script tag and the global Frame object becomes available on the page.

Add the script tag

Place the script in either the <head> section or just before the closing </body> tag.

FRAME.JS SCRIPT TAG

<script src="https://js.framepayments.com/v1/index.js"></script>

Always load Frame.js directly from https://js.framepayments.com. Don't bundle it into your application or self-host it — you'll miss security patches and feature updates, and PCI compliance assumes the live CDN copy.

Asynchronous loading with async or defer avoids blocking DOM rendering. If you do, gate any Frame.* calls behind the script's load event — the global isn't available until the script finishes executing.

Initialize the SDK

Call Frame.init() with your publishable key. Grab the key from the Frame Developer section of the dashboard.

INITIALIZE FRAME.JS

const frame = await Frame.init("<PUBLISHABLE_KEY>");

The publishable key identifies your application to Frame. It's safe to embed in client-side code — see Architecture for what each credential is allowed to do.

Create and reuse a single Frame instance for the lifetime of the page. Calling Frame.init() multiple times with the same key is wasteful and can produce unexpected behavior in component event ordering.

For flows that only need one element type, lightweight factories like Frame.createTermsOfService() and Frame.createOnboarding() skip loading the full SDK dependency graph (Evervault, FingerprintJS, Sift) and ship faster. Use them when you don't need card tokenization on the same page.

Sandbox and production environments

Frame.js operates in two environments: sandbox and production. Use sandbox during development and switch to production once you're confident in the integration.

The environment is determined by the publishable key prefix you pass to Frame.init() — there is no separate environment switch.

Key prefix	Environment	Notes
`pk_sandbox_*`	Sandbox	Test cards only. See Testing.
`pk_production_*`	Production	Live card processing.

In sandbox you must use Frame's test card numbers — real cards are rejected with a require_test_cards error on the number field. In production the inverse holds: test card numbers are rejected.

Swap the key when you're ready to accept live payments. Nothing else in your integration needs to change.