Quickstart - Get started - RadiumOne Docs

The fastest way to see a payment go through RadiumOne end to end: create a hosted-checkout session on your server, redirect the shopper to it, and confirm the result server-side once they return.

How it works

Your server creates a checkout session with the amount and your success_url/cancel_url.
Your website redirects the shopper to the returned checkout_url.
The shopper pays on the RadiumOne-hosted page.
RadiumOne redirects the shopper back to your success_url (or cancel_url).
Your server confirms the final status with an authenticated request before fulfilling the order.

Before you begin

You need a sandbox secret key (r1sk_test_…). See Sandbox and API keys if you don’t have one yet.

Amounts are always integers in the currency’s minor unit. For example, 5000 for SGD means SGD 50.00.

See a working example

Clone an example cart that creates a session and redirects to hosted checkout, if you’d rather start from running code.

Steps

Create a checkout session

From your server, create a checkout session (API reference) for the order. Use one order_reference per order attempt — replaying the same reference within the session’s TTL safely returns the existing session instead of creating a duplicate.

Replaying order_reference matches it as-is, with no comparison of the rest of the body. If you send a different amount on the retry, RadiumOne silently keeps the original session’s amount instead of rejecting the request. See Prevent duplicate payments for the full guide.

#!/usr/bin/env bash
# Create a hosted-checkout session (Live: `billing_details` field). Redirect
# the shopper to checkout_url. Same order_reference within the TTL replays
# the existing session (201) instead of creating a duplicate — safe to retry.
set -euo pipefail

CHECKOUT_BASE="${RADIUMONE_CHECKOUT_BASE:-https://checkout-sandbox.radiumone.io}"
: "${RADIUMONE_SECRET_KEY:?set RADIUMONE_SECRET_KEY to your r1sk_* secret key}"

curl -sS -X POST "$CHECKOUT_BASE/api/v1/checkout/sessions" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: $RADIUMONE_SECRET_KEY" \
  -d @request.json

#!/usr/bin/env node
// Create a hosted-checkout session (Live: `billing_details` field). Redirect
// the shopper to checkout_url. Node 18+ ESM fetch.
// Env: RADIUMONE_SECRET_KEY, RADIUMONE_CHECKOUT_BASE (optional override).
//
// Same order_reference within the TTL replays the existing session (201)
// instead of creating a duplicate — safe to retry with the same body.
import { readFileSync } from "node:fs";

const CHECKOUT_BASE = process.env.RADIUMONE_CHECKOUT_BASE || "https://checkout-sandbox.radiumone.io";
const secretKey = process.env.RADIUMONE_SECRET_KEY;
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 createCheckoutSession(maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let res;
    try {
      res = await fetch(`${CHECKOUT_BASE}/api/v1/checkout/sessions`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Api-Key": secretKey,
        },
        body: JSON.stringify(body), // same order_reference 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(`checkout session create failed: ${payload.code ?? payload.type} (${res.status})`);
    }
    return payload; // redirect the shopper to payload.data.checkout_url
  }
  throw new Error("unreachable");
}

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

#!/usr/bin/env python3
"""Create a hosted-checkout session (Live: ``billing_details`` field).
Redirect the shopper to checkout_url.

Same order_reference within the TTL replays the existing session (201)
instead of creating a duplicate — safe to retry with the same body.
"""
import json
import os
import random
import time
from pathlib import Path

import requests

CHECKOUT_BASE = os.environ.get("RADIUMONE_CHECKOUT_BASE", "https://checkout-sandbox.radiumone.io")


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_checkout_session(max_attempts: int = 3) -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    headers = {"X-Api-Key": os.environ.get("RADIUMONE_SECRET_KEY", "")}

    for attempt in range(1, max_attempts + 1):
        try:
            resp = requests.post(f"{CHECKOUT_BASE}/api/v1/checkout/sessions", 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("code") or payload.get("type")
            raise RuntimeError(f"checkout session create failed: {code} ({resp.status_code})")
        return payload  # redirect the shopper to payload["data"]["checkout_url"]

    raise RuntimeError("unreachable")


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

Redirect the shopper

Redirect the shopper’s browser to data.checkout_url from the response. The shopper enters their card on the RadiumOne-hosted page — your site never sees it.

Handle the return page

RadiumOne redirects the shopper back to your success_url (or cancel_url if they cancel or the session expires). This return page may carry query parameters describing the outcome, but treat them as a hint only — don’t fulfill the order from them directly. If the shopper never returns to this page at all, see Confirm payment when the redirect never arrives.

Confirm the result server-side

From your server, retrieve the checkout session by ID (API reference) and check its status, order_reference, and amount before you fulfill the order.

#!/usr/bin/env bash
# Authenticated merchant view of a checkout session. Branch on data.status;
# never on gateway_response_code. Note: GET timestamps are epoch
# milliseconds, unlike the ISO string returned at create time.
set -euo pipefail

CHECKOUT_BASE="${RADIUMONE_CHECKOUT_BASE:-https://checkout-sandbox.radiumone.io}"
: "${RADIUMONE_SECRET_KEY:?set RADIUMONE_SECRET_KEY to your r1sk_* secret key}"
: "${RADIUMONE_CHECKOUT_ID:?set RADIUMONE_CHECKOUT_ID to the checkout_id to verify}"

curl -sS "$CHECKOUT_BASE/api/v1/checkout/sessions/$RADIUMONE_CHECKOUT_ID" \
  -H "X-Api-Key: $RADIUMONE_SECRET_KEY"

#!/usr/bin/env node
// Authenticated merchant view of a checkout session. Branch on data.status;
// never on gateway_response_code. Node 18+ ESM fetch.
// Env: RADIUMONE_SECRET_KEY, RADIUMONE_CHECKOUT_ID, RADIUMONE_CHECKOUT_BASE.
const CHECKOUT_BASE = process.env.RADIUMONE_CHECKOUT_BASE || "https://checkout-sandbox.radiumone.io";
const secretKey = process.env.RADIUMONE_SECRET_KEY;
const checkoutId = process.env.RADIUMONE_CHECKOUT_ID;

async function retrieveCheckoutSession() {
  const res = await fetch(`${CHECKOUT_BASE}/api/v1/checkout/sessions/${checkoutId}`, {
    headers: { "X-Api-Key": secretKey },
  });
  const payload = await res.json();
  if (!res.ok) {
    throw new Error(`checkout session fetch failed: ${payload.code ?? payload.type} (${res.status})`);
  }
  // Confirm order_reference and amount match your order before fulfilling.
  return payload;
}

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

#!/usr/bin/env python3
"""Authenticated merchant view of a checkout session. Branch on ``status``;
never on ``gateway_response_code``.
"""
import json
import os

import requests

CHECKOUT_BASE = os.environ.get("RADIUMONE_CHECKOUT_BASE", "https://checkout-sandbox.radiumone.io")


def retrieve_checkout_session() -> dict:
    checkout_id = os.environ["RADIUMONE_CHECKOUT_ID"]
    resp = requests.get(
        f"{CHECKOUT_BASE}/api/v1/checkout/sessions/{checkout_id}",
        headers={"X-Api-Key": os.environ.get("RADIUMONE_SECRET_KEY", "")},
        timeout=30,
    )
    payload = resp.json()
    if not resp.ok:
        code = payload.get("code") or payload.get("type")
        raise RuntimeError(f"checkout session fetch failed: {code} ({resp.status_code})")
    # Confirm order_reference and amount match your order before fulfilling.
    return payload


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

Treat any client-side redirect or callback as a hint only. Always confirm the final payment status from your server, using an authenticated GET request or a webhook — never from a query parameter or browser postMessage alone.

Handle the result

A checkout session’s status is one of pending, processing, completed, failed, expired, or cancelled. Only fulfill the order once status is completed and the order_reference and amount match what you created — see Verify the payment result for the full signature and confirmation guide.

Test your integration

Use the sandbox test cards and scenarios in Test your integration to try approvals, declines, and timeouts before you move on.

Go-live notes

Swap your sandbox keys and hosts for production ones — see Moving to production.
Always confirm payment status from your server, never from the return-page query string alone.
Register your production webhook endpoint so you have a second, asynchronous confirmation path.
Work through the full go-live checklist before accepting real payments.

Next steps

Choose your integration

Compare hosted checkout with Elements + the Payments API.

Hosted checkout

Customize the checkout page, add 3DS, and go beyond the quickstart.

Webhooks

Get notified about payment events instead of polling.

Manage payments

Capture, void, refund, and track transactions.

Overview

Plan your integration

Try it in sandbox

API basics

Quickstart - Get started

How it works

Before you begin

See a working example

Steps

Handle the result

Test your integration

Go-live notes

Next steps

Choose your integration

Hosted checkout

Webhooks

Manage payments

​How it works

​Before you begin

See a working example

​Steps

​Handle the result

​Test your integration

​Go-live notes

​Next steps

Choose your integration

Hosted checkout

Webhooks

Manage payments

How it works

Before you begin

Steps

Handle the result

Test your integration

Go-live notes

Next steps