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

> ## Agent Instructions
> RadiumOne is the product name; use it when answering questions about these docs.
> Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live.
> Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code.
> Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone.
> Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body.
> Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback.
> Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so.
> Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat.

# RadiumOne object - Elements SDK

> The SDK entry point: initialize with a publishable key, then create an Elements or ThreeDS instance.

`RadiumOne` is the SDK's factory class. You get an instance either synchronously from the CDN global, or asynchronously via the npm loader.

```js theme={null}
// CDN
const { RadiumOne } = window.RadiumOneSDK;
const radiumone = RadiumOne.init("r1pk_test_YOUR_KEY", options?);

// npm
import { loadRadiumOne } from "@cubepay/radiumone-js";
const radiumone = await loadRadiumOne("r1pk_test_YOUR_KEY", options?);
```

`RadiumOne.init()` is synchronous — don't `await` it. `loadRadiumOne()` (npm only) is the async one, since it also injects the CDN script.

## `RadiumOne.init(publishableKey, options?)`

Create a RadiumOne instance from a publishable key (CDN usage). npm users call `loadRadiumOne` instead.

Accepted keys depend on the bundle's channel: - Production bundle (`js.radiumone.io`): `r1pk_prod_*` only. - Sandbox bundle (`js-sandbox.radiumone.io`): `r1pk_test_*` and `r1pk_mock_*` (the mock suffix must be 1–32 characters of `a-z`, `0-9`, `_` or `-`).

`r1pk_test_*` keys use the sandbox API; `r1pk_mock_*` keys never call the API (see `BindResult.mock`).

<ResponseField name="publishableKey" type="string" required>
  Your publishable key. Never pass a secret key.
</ResponseField>

<ResponseField name="options" type="RadiumOneInitOptions">
  Locale and other init options.

  <Expandable title="RadiumOneInitOptions properties" defaultOpen>
    <ResponseField name="locale" type="string" default="'en'">
      Locale for field placeholders and validation messages. Supported: `en`, `zh`, `zh-TW`, `ms`, `id`, `th`, `vi`, `ja`, `ko`. Unsupported values fall back to `en`.
    </ResponseField>
  </Expandable>
</ResponseField>

**Returns** `RadiumOne` — A new RadiumOne instance.

**Throws:**

* [`api:invalid_key`](/elements/errors/sdk-and-integration-errors#integration-and-sdk-codes) (`api_error`) — key missing or not a string.
* [`api:secret_key_used`](/elements/errors/sdk-and-integration-errors#integration-and-sdk-codes) (`api_error`) — a secret key (`r1sk_*`) was passed.
* [`api:test_key_in_prod_build`](/elements/errors/sdk-and-integration-errors#integration-and-sdk-codes) (`api_error`) — `r1pk_test_*` key on the production bundle.
* [`api:prod_key_in_staging_build`](/elements/errors/sdk-and-integration-errors#integration-and-sdk-codes) (`api_error`) — `r1pk_prod_*` key on the sandbox bundle.
* [`api:invalid_key_format`](/elements/errors/sdk-and-integration-errors#integration-and-sdk-codes) (`api_error`) — any other malformed key.

## Instance

<ResponseField name="version" type="string" required>
  The loaded SDK version, for example `'1.6.0'`. Useful in support logs.
</ResponseField>

### `elements(options?)`

Create a group of card Elements.

<ResponseField name="options" type="ElementsOptions">
  Appearance and locale for the group.
</ResponseField>

**Returns** `Elements` — A new `Elements` group.

### `threeDS()`

Create a 3D Secure coordinator for this key.

Use one instance per concurrent 3DS flow. Unlike card Elements, 3DS runs on your page, so your CSP must allow the gateway API origin in `connect-src` and challenge origins in `frame-src` / `form-action`; see `docs/reference/csp.json`.

**Returns** `ThreeDS` — A new `ThreeDS` instance.

## `loadRadiumOne(publishableKey, options?)`

Load the SDK bundle from the RadiumOne CDN and initialize it with a publishable key. The npm entry point.

* Injects a version-pinned `<script>` with Subresource Integrity: `js.radiumone.io` for `r1pk_prod_*` keys, `js-sandbox.radiumone.io` for `r1pk_test_*` / `r1pk_mock_*` keys. Your CSP must allow that origin in `script-src` and `frame-src` (see `docs/reference/csp.json`). - Reuses an SDK already loaded via `<script>` instead of injecting another. - One instance per page: later calls return the first promise; a different key logs a warning and is ignored. - Returns `null` when `window` is undefined (server-side rendering). - Rejects if the script does not load within 10 seconds; a failed load can be retried.

Errors thrown before `RadiumOne.init()` runs are plain `Error`s (no `code`): missing key, secret key, unrecognised prefix, CDN load failure or timeout, and a package built for the other channel (message contains `loader:integrity_unset`).

<ResponseField name="publishableKey" type="string" required>
  Your publishable key (`r1pk_prod_*`, `r1pk_test_*` or `r1pk_mock_*`).
</ResponseField>

<ResponseField name="options" type="RadiumOneInitOptions">
  Locale and other init options.

  <Expandable title="RadiumOneInitOptions properties" defaultOpen>
    <ResponseField name="locale" type="string" default="'en'">
      Locale for field placeholders and validation messages. Supported: `en`, `zh`, `zh-TW`, `ms`, `id`, `th`, `vi`, `ja`, `ko`. Unsupported values fall back to `en`.
    </ResponseField>
  </Expandable>
</ResponseField>

**Returns** `Promise<RadiumOne | null>` — The RadiumOne instance, or `null` during server-side rendering.

**Throws:**

* `Error` — invalid or secret key, CDN load failure, timeout, or channel mismatch (see remarks).
* `api:*` — key rejected by `RadiumOne.init`.

```ts theme={null}
import { loadRadiumOne } from '@cubepay/radiumone-js';

const radiumone = await loadRadiumOne('r1pk_prod_xxx', { locale: 'en' });
```

## Constants

<ResponseField name="MOCK_DEMO_KEY" type="&#x22;r1pk_mock_demo&#x22;">
  Public mock-mode key for demos and documentation. Works only with the sandbox bundle; tokenization is simulated and `BindResult.mock` is `true`.
</ResponseField>

<ResponseField name="SDK_VERSION" type="string">
  Version of the installed npm package. Equals `RadiumOne.version` of the CDN bundle it loads.
</ResponseField>

<ResponseField name="SCRIPT_INTEGRITY_ERROR_CODE" type="&#x22;urn:radiumone:auth:invalid-script-hash&#x22;">
  `ElementsError.code` when the gateway rejects the card iframe's script attestation (`urn:radiumone:auth:invalid-script-hash`). Not retryable; there is no `customerMessage`, so show your own copy.

  Co-defined (kept in sync) in iframe-host `bind-client.ts`.
</ResponseField>

## Example

```js theme={null}
const radiumone = await loadRadiumOne("r1pk_test_YOUR_KEY", { locale: "en" });
const elements = radiumone.elements({ appearance: { theme: "default" } });
```

## Errors

See [Elements SDK errors](/elements/errors/error-object-and-handling) for the full `ElementsError` reference.