- 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.
- npm
- CDN
- React
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 Testing with a test key? Keep this code, and add the sandbox CDN
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.<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
nullwhen there’s nowindow(for example, during a Next.js server render). Guard fornullbefore using the result. - A test key without the sandbox
<script>tag on the page — or with the tag loading too late — throws a plainErrorwhose message containsloader: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 ar1pk_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 adddefereither if you callloadRadiumOne()from an inline script. - In Next.js, use
next/scriptwithstrategy="beforeInteractive"in your root layout. - If the tag loads after
loadRadiumOne()runs, the call throws anErrorwhose message containsloader:integrity_unset.
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 itsintegrityhash 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
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 withurn: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.