Expired sessions - Hosted checkout

TL;DR: A session that hits its TTL becomes expired and can’t be paid — confirm with a GET, then start a new session.

A checkout session only lives for its ttl_minutes (5–60, default depends on your environment — see Session lifecycle). If the shopper doesn’t finish paying before it elapses, the session moves to expired and can’t be paid.

When this happens

The shopper leaves the hosted page open past the TTL without completing payment.
The hosted page’s own countdown times out: it redirects the shopper to your raw cancel_url with reason=timeout appended.
The shopper closes the tab or navigates away before the TTL — see Handle abandoned checkouts for that path instead; it looks the same server-side but nothing redirects the shopper back.

What you see

Signal	Value
Redirect (countdown timeout only)	Raw `cancel_url?reason=timeout` — no `checkout_id`, `sig`, or other params
Redirect (shopper navigates back manually before the countdown fires)	Raw `cancel_url` with no query params at all
Session status (`GET`)	`expired`
Webhook	None — an expiry is never charged, so no `payment.*` event fires

reason=timeout only appears on the countdown’s own auto-redirect. Don’t rely on it as your only signal that a session expired — always confirm with a GET request, since a shopper who manually clicks back or closes the tab gets no query params at all.

What to do

Treat any cancel-URL return as unpaid, provisionally

A return to cancel_url — with or without reason=timeout — never carries a sig, so don’t infer anything from it beyond “the shopper didn’t complete the redirect flow.” Confirm with the next step.

Confirm the session's actual status

Call the authenticated session-status endpoint (using your secret key) from your server (API reference):

#!/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))

A status of expired confirms no charge happened.

Start a new session if the shopper wants to try again

Create a fresh checkout session (API reference). You can reuse the same order_reference — an expired session’s order_reference is no longer idempotency-active, so this creates a genuinely new session rather than replaying the old one.

#!/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))

Prevent it

Set ttl_minutes to match how long your checkout page is realistically open (for example, longer for a page reachable from an abandoned-cart email link).
Surface your own countdown or warning in your own UI before the hosted page’s timer fires, if your integration keeps the shopper on your domain (embedded mode).

Session lifecycle

Statuses, TTL, and retry rules in full.

Redirect integration

How the cancel-return step fits into the full flow.

Handle abandoned checkouts

When the shopper never returns at all.

Handle failures

All ten failure scenarios, symptom → page.

Introduction

Guides

3D Secure

Handle failures

Errors

Reference

Expired sessions - Hosted checkout

When this happens

What you see

What to do

Prevent it

Session lifecycle

Redirect integration

Handle abandoned checkouts

Handle failures

​When this happens

​What you see

​What to do

​Prevent it

​Related

Session lifecycle

Redirect integration

Handle abandoned checkouts

Handle failures

When this happens

What you see

What to do

Prevent it

Related