Skip to main content
How you load Elements depends on your key:
  • Test keys (r1pk_test_…): load the sandbox CDN <script> tag (the floating build, no SRI hash). Using npm or React? Keep that code and add the sandbox tag while you test — see Test keys with npm or React.
  • Live keys (r1pk_prod_…): use npm (@latest, loadRadiumOne()) if you can — the loader bakes in a Subresource Integrity (SRI) hash for you, so there’s nothing to copy or keep in sync. Otherwise, use the pinned production CDN tag with its hash.
The npm package is for live keys. It’s public on npm, so installing it needs no registry login or token:
Then load the SDK with loadRadiumOne(). It injects the production 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.
Testing with a test key? Keep this code, and add the sandbox CDN <script> tag to your page’s <head>, before your app bundle. loadRadiumOne("r1pk_test_YOUR_KEY") then reuses the sandbox build instead of injecting its own. Remove the tag when you switch to your live key — see Test keys with npm or React.
  • 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.
  • A test key without the sandbox <script> tag on the page — or with the tag loading too late — throws a plain Error whose message contains loader:integrity_unset — see Key validation errors.
  • 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.
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.

Test keys with npm or React

The npm packages load the production bundle, which only accepts live keys. To test with a r1pk_test_… key, you don’t need to drop npm: keep your loadRadiumOne() or <RadiumOneProvider> code and add the sandbox CDN tag (https://js-sandbox.radiumone.io/elements/v1/radiumone.min.js) while you test. When the sandbox build is already on the page, loadRadiumOne() reuses it instead of loading its own, and <RadiumOneProvider> uses whatever loadRadiumOne() returns. The tag has to run before loadRadiumOne() is called:
  • Put it in <head>, before your app bundle, as a plain <script src="…">.
  • Don’t add async. Don’t add defer either if you call loadRadiumOne() from an inline script.
  • In Next.js, use next/script with strategy="beforeInteractive" in your root layout.
  • If the tag loads after loadRadiumOne() runs, the call throws an Error whose message contains loader:integrity_unset.
Remove the tag when you switch to your live key, or add it only in test builds (as the Next.js example does). While the sandbox build is on the page, loadRadiumOne() reuses it for any key — so a live key would run against the sandbox bundle.

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.

Get the hash for a CDN script tag

  • This page — the CDN tab above shows the production <script> tag with its integrity hash for the current version. Use it 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. The manifest is served from the same host as the script, so it can’t vouch for that host — check the hash against this page before you ship it.
sri.json
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

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 urn:radiumone:payment-gateway:auth:invalid-script-hash (exported as SCRIPT_INTEGRITY_ERROR_CODE) 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: npm only: the npm package is built for live keys. With a test key and no sandbox <script> tag already on the page when it runs, loadRadiumOne() throws a plain Error with no code, whose message contains loader:integrity_unset. Add the sandbox tag in <head>, before your app bundle — see Test keys with npm or React. 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.
Last modified on September 29, 2026