Add 3D Secure - Elements SDK

Elements can drive 3D Secure authentication directly in the browser, using the same tokenization session you already create for a card payment. Your server pins the amount to authenticate, the browser runs the challenge (if any), and your server charges using the resulting reference.

How it works

Your server creates a tokenization session and pins the net payable amount.
The shopper enters their card; Elements tokenizes it (elements.submit()).
The browser starts 3DS authentication (threeDS.authenticate()), which may run frictionless or present a challenge.
Your server authorizes or purchases using the card token plus the 3DS reference. The gateway independently verifies the reference before it authorizes the charge.

Before you begin

Requires enablement on your account, a CSP that allows the 3DS iframe and fetch origins — including your API origin in connect-src, or a challenge times out after 5 minutes instead of failing fast (see Content Security Policy) — and Elements SDK v1.6.0 or later.

Steps

Create a payment session and pin the amount

Create a session as usual, then pin the amount that 3DS will authenticate — this must be the amount you’ll actually charge, which may be lower than the gross order amount if you redeem loyalty points.

#!/usr/bin/env bash
# Create a tokenization session for Elements. Pass session_id/session_secret/
# pubkey_jws to the browser unchanged — never re-serialize pubkey_jws.
set -euo pipefail

API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}"
: "${RADIUMONE_ACCESS_TOKEN:?set RADIUMONE_ACCESS_TOKEN to a Bearer access token}"

curl -sS -X POST "$API_BASE/v1/sessions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
  -d @request.json

#!/usr/bin/env node
// Create a tokenization/checkout session for Elements. Node 18+ ESM fetch.
// Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE (optional override).
import { readFileSync } from "node:fs";

const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url)));

async function createPaymentSession() {
  const res = await fetch(`${API_BASE}/v1/sessions`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(body),
  });
  const payload = await res.json();
  if (!res.ok) {
    throw new Error(`sessions create failed: ${payload.type ?? payload.code} (${res.status})`);
  }
  // Pass session_id, session_secret and pubkey_jws to the browser byte-for-byte.
  return payload;
}

createPaymentSession().then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Create a tokenization/checkout session for Elements. Python 3.10+, requests."""
import json
import os
from pathlib import Path

import requests

API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")


def create_payment_session() -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    resp = requests.post(
        f"{API_BASE}/v1/sessions",
        json=body,
        headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
        timeout=30,
    )
    payload = resp.json()
    if not resp.ok:
        raise RuntimeError(f"sessions create failed: {payload.get('type') or payload.get('code')} ({resp.status_code})")
    # Pass session_id, session_secret and pubkey_jws to the browser byte-for-byte.
    return payload


if __name__ == "__main__":
    print(json.dumps(create_payment_session(), indent=2))

#!/usr/bin/env bash
# Beta — requires enablement. Pin the net payable amount (after loyalty redemption)
# BEFORE the browser calls threeDS.authenticate() — required for 3DS + rewards.
set -euo pipefail

API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}"
: "${RADIUMONE_ACCESS_TOKEN:?set RADIUMONE_ACCESS_TOKEN to a Bearer access token}"
: "${RADIUMONE_SESSION_ID:?set RADIUMONE_SESSION_ID to the session to pin}"

curl -sS -X PATCH "$API_BASE/v1/sessions/$RADIUMONE_SESSION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
  -d @request.json

#!/usr/bin/env node
// Beta — requires enablement. Pin the net payable amount before threeDS.authenticate().
// Node 18+ ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_SESSION_ID, RADIUMONE_API_BASE.
import { readFileSync } from "node:fs";

const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
const sessionId = process.env.RADIUMONE_SESSION_ID;
const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url)));

async function updateSessionAmount() {
  const res = await fetch(`${API_BASE}/v1/sessions/${sessionId}`, {
    method: "PATCH",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(body),
  });
  const payload = await res.json();
  if (!res.ok) {
    // 422 sessions:amount-not-pinnable if net_payable_amount > gross or the session expired.
    throw new Error(`sessions PATCH failed: ${payload.type ?? payload.code} (${res.status})`);
  }
  return payload;
}

updateSessionAmount().then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Beta — requires enablement. Pin the net payable amount before 3DS. Python 3.10+, requests."""
import json
import os
from pathlib import Path

import requests

API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")


def update_session_amount() -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    session_id = os.environ["RADIUMONE_SESSION_ID"]
    resp = requests.patch(
        f"{API_BASE}/v1/sessions/{session_id}",
        json=body,
        headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
        timeout=30,
    )
    payload = resp.json()
    if not resp.ok:
        # 422 sessions:amount-not-pinnable if net_payable_amount > gross or the session expired.
        raise RuntimeError(f"sessions PATCH failed: {payload.get('type') or payload.get('code')} ({resp.status_code})")
    return payload


if __name__ == "__main__":
    print(json.dumps(update_session_amount(), indent=2))

There’s no public PATCH /v1/sessions/{id} reference page yet — see the ThreeDS reference for how this step fits the browser-driven flow. Keep ttl_minutes at 30 or less for a 3DS checkout — see Token lifetime below.

Tokenize the card in the browser

const elements = radiumone.elements();
const card = elements.create("card");
card.mount("#card-element");

const { token } = await elements.submit({
  sessionId: session.session_id,
  sessionSecret: session.session_secret,
  pubkeyJws: session.pubkey_jws,
});

Authenticate with 3D Secure

const threeDS = radiumone.threeDS();

const { status, ref } = await threeDS.authenticate({
  sessionId: session.session_id,
  sessionSecret: session.session_secret,
  cardToken: token,
});

if (status === "AUTHENTICATED" || status === "ATTEMPTED") {
  // proceed to charge — see the next step
} else {
  // NOT_AUTHENTICATED, FAILED, REJECTED, EXPIRED: don't charge.
  // This branch decides your UX only — the gateway independently
  // re-verifies the ref at purchase time regardless of this status.
  showDeclined(status);
}

A decline resolves, it doesn’t throw. See Authentication results for every status and its meaning, and for 3DS error remedies.

Charge with the 3DS reference on your server

Send the token and the 3DS ref from the browser to your server, then purchase or authorize with three_ds:{ref} (API reference).

#!/usr/bin/env bash
# Requires enablement. Purchase using a completed Elements 3DS result ref.
# The gateway checks the ref is single-use, unexpired, and amount-bound.
set -euo pipefail

API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}"
: "${RADIUMONE_ACCESS_TOKEN:?set RADIUMONE_ACCESS_TOKEN to a Bearer access token}"

curl -sS -X POST "$API_BASE/v1/transactions/purchase" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
  -d @request.json

#!/usr/bin/env node
// Requires enablement. Purchase using a completed Elements 3DS result ref.
// The gateway checks the ref is single-use, unexpired, and amount-bound.
// Node 18+ ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE (optional override).
//
// Shared result pattern: any 2xx is a response you branch on `data.status`.
// On a network timeout, a 5xx, or `status:"PENDING"`, retry with the SAME
// request_id — never mint a new one for the same attempt.
import { readFileSync } from "node:fs";

const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url)));

// Exponential backoff with jitter: attempt 1 waits ~250-500ms, doubling each
// attempt, capped at 4s -- avoids hammering the gateway in a tight retry loop.
function backoffMs(attempt) {
  const base = Math.min(250 * 2 ** (attempt - 1), 4000);
  return base + Math.random() * base;
}

async function createPurchaseWithThreeDsRef(maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let res;
    try {
      res = await fetch(`${API_BASE}/v1/transactions/purchase`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${accessToken}`,
        },
        body: JSON.stringify(body), // same request_id every attempt
      });
    } catch (networkErr) {
      if (attempt === maxAttempts) throw networkErr;
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue;
    }

    if (res.status >= 500) {
      if (attempt === maxAttempts) throw new Error(`server error ${res.status} after ${attempt} attempts`);
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue;
    }

    const payload = await res.json();
    if (!res.ok) {
      throw new Error(`request failed: ${payload.type ?? payload.code} (${res.status})`);
    }

    if (payload.data.status === "PENDING") {
      if (attempt === maxAttempts) return payload;
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue;
    }

    return payload; // branch on data.status
  }
  throw new Error("unreachable");
}

createPurchaseWithThreeDsRef().then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Requires enablement. Purchase using a completed Elements 3DS result ref.
The gateway checks the ref is single-use, unexpired, and amount-bound.

Shared result pattern: any 2xx is a response you branch on 'status'. On a
network timeout, a 5xx, or status 'PENDING', retry with the SAME
request_id -- never mint a new one for the same attempt.
"""
import json
import os
import random
import time
from pathlib import Path

import requests

API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")


def backoff_seconds(attempt: int) -> float:
    """Exponential backoff with jitter: attempt 1 waits ~0.25-0.5s, doubling
    each attempt, capped at 4s -- avoids hammering the gateway in a loop."""
    base = min(0.25 * 2 ** (attempt - 1), 4.0)
    return base + random.random() * base


def create_purchase_with_three_ds_ref(max_attempts: int = 3) -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    headers = {"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"}

    for attempt in range(1, max_attempts + 1):
        try:
            resp = requests.post(f"{API_BASE}/v1/transactions/purchase", json=body, headers=headers, timeout=30)
        except requests.exceptions.Timeout:
            if attempt == max_attempts:
                raise
            time.sleep(backoff_seconds(attempt))
            continue

        if resp.status_code >= 500:
            if attempt == max_attempts:
                raise RuntimeError(f"server error {resp.status_code} after {attempt} attempts")
            time.sleep(backoff_seconds(attempt))
            continue

        payload = resp.json()
        if not resp.ok:
            code = payload.get("type") or payload.get("code")
            raise RuntimeError(f"request failed: {code} ({resp.status_code})")

        if payload["data"]["status"] == "PENDING":
            if attempt == max_attempts:
                return payload
            time.sleep(backoff_seconds(attempt))
            continue

        return payload  # branch on data.status

    raise RuntimeError("unreachable")


if __name__ == "__main__":
    print(json.dumps(create_purchase_with_three_ds_ref(), indent=2))

Handle the result

Any 2xx response is a result you must branch on status — never on response_code (that’s the verbatim host/acquirer code; useful for support tickets, not for your app logic).

Status	Meaning	What to do
`AUTHORIZED`	Funds reserved (authorize only)	Capture within the capture window, or void to release
`CAPTURED`	Funds captured (purchase, capture, or refund)	Fulfil the order (or process the refund)
`VOIDED`	Authorization released	No funds moved
`DECLINED`	Issuer or acquirer declined	Final for this attempt — don’t retry the same card without a new attempt from the shopper
`FAILED`	The transaction didn’t complete — the acquirer returned a non-decline error code, or the gateway couldn’t place the request. Not a guarantee that no funds moved — `VOIDED` and `REVERSED` are the only statuses that positively assert that.	Confirm via `GET /v1/transactions/{id}/status` before retrying, then retry (a genuinely new attempt, not a replay of the same `request_id`) with a new `request_id`
`PENDING`	Outcome not yet known (async)	Wait for a webhook, or poll `GET /v1/transactions/{id}/status`
`AUTH_EXPIRED`	Authorization lapsed before capture	Create a new authorization
`REVERSAL_PENDING` / `REVERSED`	Automatic compensating reversal after an upstream timeout left the outcome genuinely unknown (never left `FAILED` in this case)	No merchant action; webhook confirms the final state

Key	Used by	On replay
`request_id`	Purchase, authorize, standalone and referenced refunds	Same body, same operation type → the original transaction, whatever its status — including `PENDING`, `DECLINED`, or `FAILED`. Changed body, or the same key reused for a different operation type → `transaction:idempotency-body-mismatch`. Purchase/authorize/standalone-refund compare `amount`, `currency`, `payment_method_type`, `channel`, the card’s `pan_prefix` (first 8 digits — not the full token), `metadata`, and `order_reference`; a referenced refund compares only the original transaction and `amount` (`reason` isn’t compared) and its replay check runs before the refund gates, so it always replays, even a `DECLINED`/`FAILED` one — mint a new `request_id` to retry after a decline. None of these compare `three_ds` or `loyalty`, so changing either on a retry replays the original silently instead of failing.
`operation_id`	Capture, void	Same operation type on the same transaction → the original result (body is never compared, so a changed amount is silently ignored). A different operation type reusing the key → `tx:duplicate-operation`.

Balance inquiry also takes a request_id field, but it isn’t an idempotency key — there’s no dedup or replay store. Every call re-queries the rewards host, even with the same request_id.

Keys are 8–64 characters, [a-zA-Z0-9-] only, unique per merchant account. Generate one key per order attempt and persist it to your database before you send the first request — never mint a new key just to retry the same attempt. See Prevent duplicate payments.

PENDING means the outcome isn’t known yet — most often after a processor timeout. Don’t assume success or failure. Recover it one of two ways:

Wait for a webhook (payment.*, authorization.*, refund.* — see Webhook event types).
Call GET /v1/transactions/{id}/status for a live inquiry against the acquirer.

If you don’t have the transaction id yet — a client-side timeout before the first response arrived — replay the same request with the same request_id and body. The replay returns the stored transaction and its id, whatever status it’s reached. Never re-submit with a new idempotency key just because the first attempt is slow — that risks a second charge for the same order. If the charge itself is rejected for a 3DS reason (for example three-ds:ref-invalid or three-ds:ref-expired), see Authentication results for remedies, or Handle 3D Secure failures in Elements for the recovery-action version of the same failures.

Server policy

Charge only after your server receives a ref from this checkout’s own session flow — never accept a ref from an unrelated session, and never skip straight to charging because the browser reported AUTHENTICATED. The gateway independently checks the ref is single-use, unexpired, authenticated, and bound to the same card token, currency and amount before it authorizes.

Token lifetime

The card token from elements.submit() is transient (about 30 minutes) and the 3DS authentication is bound to it. Keep ttl_minutes at 30 or less for a 3DS checkout. If the token lapses or the shopper switches cards mid-flow:

Before charging: authenticate() rejects with three-ds:card-token-invalid — re-bind the card (elements.submit() again) and re-authenticate.
At charge time: the purchase/authorize call rejects with 422 urn:radiumone:three-ds:card-token-mismatch if the charged token differs from the one that was authenticated — re-bind and re-authenticate rather than retrying the charge with the same ref.

See Handle 3D Secure failures in Elements and Handle expired sessions and card tokens for the full recovery flow.

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 your integration

See Test your integration for 3DS scenario coverage.

Go-live notes

Confirm your account has 3DS enabled before relying on this flow in production.
Make sure your CSP allows the 3DS iframe/fetch origins — see Content Security Policy.
Review the go-live checklist before launch.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Add 3D Secure - Elements SDK

How it works

Before you begin

Steps

Handle the result

Server policy

Token lifetime

Test your integration

Go-live notes

Next steps

Challenge presentation and redirects

Authentication results

​How it works

​Before you begin

​Steps

​Handle the result

​Server policy

​Token lifetime

​Test your integration

​Go-live notes

​Next steps

Challenge presentation and redirects

Authentication results

How it works

Before you begin

Steps

Handle the result

Server policy

Token lifetime

Test your integration

Go-live notes

Next steps