Install and load - Elements SDK

Load Elements with npm if you can — the loader bakes in a Subresource Integrity (SRI) hash for you, so there’s nothing to copy or keep in sync. Use the CDN script tag only if your build can’t take an npm dependency.

npm
CDN
React

Install the core package:

npm install @cubepay/radiumone-js

Then load the SDK with loadRadiumOne(). It injects the matching CDN <script> for you, with a Subresource Integrity hash that’s baked into the npm package at publish time — you never need to look up or paste a hash yourself.

import { loadRadiumOne } from "@cubepay/radiumone-js";

// Call once, at module scope. Test/mock keys automatically load the sandbox bundle.
const radiumone = await loadRadiumOne("r1pk_test_YOUR_KEY");

loadRadiumOne() returns a shared instance for the page. Calling it again with a different key logs a warning and returns the existing instance — don’t call it more than once per key.
SSR-safe: it resolves to null when there’s no window (for example, during a Next.js server render). Guard for null before using the result.
The load has a 10-second timeout; a failure rejects the promise. See Handle Elements failing to load for how to detect and recover from a load failure.

Load the script directly with a pinned version and its Subresource Integrity hash:

HTML

<!--
  Load RadiumOne Elements from the CDN with Subresource Integrity (SRI).
  Get the integrity hash below from the release notes for this pinned
  version — never take it only from the SRI manifest served at the same
  path, since that manifest can't vouch for its own origin. (Public release
  notes with SRI hashes are not yet published for every version.)
  Pin the immutable /elements/v<VERSION>/ path; never use /elements/v1/ or
  /elements/latest/ in production.
-->
<script
  src="https://js-sandbox.radiumone.io/elements/v1.6.0/radiumone.min.js"
  integrity="sha384-CONFIRM_SDK1_SRI_HASH"
  crossorigin="anonymous"
></script>
<script>
  const { RadiumOne } = window.RadiumOneSDK;
  const radiumone = RadiumOne.init("r1pk_test_YOUR_KEY"); // sync, browser-safe key only
</script>

Pin the immutable /elements/v<X.Y.Z>/ path and its integrity hash — see Subresource Integrity for where to get the hash.
Your Content Security Policy must allow the CDN in script-src and frame-src — see Content Security Policy.

After the script loads, the SDK is available as window.RadiumOneSDK:

const { RadiumOne } = window.RadiumOneSDK;
const radiumone = RadiumOne.init("r1pk_test_YOUR_KEY"); // synchronous

Install both packages:

npm install @cubepay/radiumone-js @cubepay/react-radiumone-js

Call loadRadiumOne() once at module scope and pass the resulting promise to <RadiumOneProvider>:

import { loadRadiumOne } from "@cubepay/radiumone-js";
import { RadiumOneProvider } from "@cubepay/react-radiumone-js";

const radiumone = loadRadiumOne("r1pk_test_YOUR_KEY");

export function App() {
  return (
    <RadiumOneProvider radiumone={radiumone}>
      <Checkout />
    </RadiumOneProvider>
  );
}

See the full walkthrough, including components and hooks, on the React reference page.

Never use a secret key (r1sk_…) in browser code, mobile apps, or anywhere a shopper can inspect it. Secret keys belong on your server only.

Subresource Integrity

Subresource Integrity (SRI) makes the browser refuse to run the SDK script if its contents don’t match a known hash — so a tampered script never loads.

How you load	What you do
npm (`loadRadiumOne()`) or React	Nothing — the loader adds the `integrity` hash for the version it loads, built into the package
CDN `<script>` tag	Add `integrity="sha384-…"` and `crossorigin="anonymous"` to the tag, with the hash for the exact version you pin

Get the hash for a CDN script tag

Release notes — each version’s release notes include the <script> tag with its integrity hash. Use these as your source of truth.
SRI manifest — for scripted version bumps, each version publishes its hashes at https://js.radiumone.io/elements/v/sri.json (sandbox: https://js-sandbox.radiumone.io/elements/v/sri.json). The manifest is served from the same host as the script, so it can’t vouch for that host — check the hash against the release notes before you ship it.

sri.json

{
  "version": "<X.Y.Z>",
  "publishedAt": "2026-05-08T12:34:56Z",
  "algorithm": "sha384",
  "files": {
    "radiumone.min.js": "sha384-…",
    "field.js": "sha384-…"
  }
}

Use files["radiumone.min.js"] for your script tag. You don’t pin field.js — the card iframe checks its own hash.

Pin only a versioned path

Path	Changes?	Use `integrity`?
`/elements/v<X.Y.Z>/radiumone.min.js`	Never	Yes
`/elements/v1/radiumone.min.js`	On every release	No — the hash stops matching and the script is blocked
`/elements/latest/radiumone.min.js`	On every release	No — for discovery only, not production

When you move to a new version, update the path and the hash together.

Runtime attestation

Beyond SRI, the card-field iframe reports its own script hash and version on every tokenize call, and RadiumOne compares it against the expected release. If a script was tampered with in transit, tokenization fails with auth:invalid-script-hash rather than silently succeeding — see Tokenization errors. You don’t need to configure anything for this; it runs automatically.

Server-side rendering

loadRadiumOne() returns null during SSR (no window). Only call SDK methods once you have a non-null instance — the React provider and hooks already handle this for you (useRadiumOne() returns null until the SDK finishes loading in the browser).

Key validation errors

RadiumOne.init() / loadRadiumOne() throw an ElementsError if the publishable key is missing or malformed:

Code	Meaning
`api:invalid_key`	No key was passed
`api:secret_key_used`	A secret key (`r1sk_…`) was passed instead of a publishable key
`api:invalid_key_format`	The key doesn’t match a known prefix
`api:test_key_in_prod_build`	A test key was used with the production CDN bundle
`api:prod_key_in_staging_build`	A production key was used with a staging/beta bundle
`loader:integrity_unset`	npm only — the installed package’s build channel doesn’t match the key’s channel (for example, a production package build with a test key)

See Fix publishable key errors for how to detect and fix each of these.

Next steps

Accept a card payment

Mount a card field, tokenize, and charge your first test payment.

Content Security Policy

CSP directives Elements needs on your checkout page.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Install and load - Elements SDK

Subresource Integrity

Get the hash for a CDN script tag

Pin only a versioned path

Runtime attestation

Server-side rendering

Key validation errors

Next steps

Accept a card payment

Content Security Policy

​Subresource Integrity

​Get the hash for a CDN script tag

​Pin only a versioned path

​Runtime attestation

​Server-side rendering

​Key validation errors

​Next steps

Accept a card payment

Content Security Policy

Subresource Integrity

Get the hash for a CDN script tag

Pin only a versioned path

Runtime attestation

Server-side rendering

Key validation errors

Next steps