The three layers, in order of trust
| Layer | Trust level | What it tells you |
|---|---|---|
Webhook (payment.*) or authenticated GET | Authoritative | The gateway’s own record of the transaction — status, amount, currency, order reference |
Redirect signature (sig) | UX hint only | The redirect URL wasn’t tampered with in the browser — not proof a charge happened |
postMessage event (embedded mode) | UX hint only | Unauthenticated in-page signal — any page can send a same-shaped message |
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.Authoritative: webhook or authenticated GET
Your server should confirm a payment one of two ways:- Wait for a gateway webhook. The sale’s first final event tells you whether to fulfil: only
payment.capturedmeans the shopper was charged. See Final events for a one-shot sale for every event that can come first and what to do with each, and Verify webhook signatures. - Call the authenticated session GET directly, with your secret key:
#!/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. An expired
# session with data.decline_reason "expired_while_processing" has an unknown
# outcome (the charge may have gone through): wait for the payment.* webhook
# or poll the transaction status; fulfil only on payment.captured.
# null (or an unrecognised value) means no charge was submitted.
# data.status "authorized" is a hold, not a payment: capture it (Payments
# API, using data.gateway_transaction_id) or let the hold lapse -- it can't
# be voided -- and fulfil only on payment.captured. Treat a status you don't recognise as not paid.
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.type} (${res.status})`);
}
const session = payload.data;
if (session.status === "authorized") {
// A hold, not a payment: the card is held for the full amount but nothing
// was captured. Capture it (Payments API, using gateway_transaction_id) or
// let the hold lapse -- a hold can't be voided. Fulfil only once the
// payment.captured webhook arrives.
return { ...payload, action: "capture_or_let_hold_lapse" };
}
if (!["pending", "processing", "completed", "failed", "expired", "cancelled"].includes(session.status)) {
// More statuses may be added: treat one you don't recognise as not paid.
return { ...payload, action: "treat_as_not_paid" };
}
if (session.status === "expired" && session.decline_reason === "expired_while_processing") {
// Expired mid-payment: the outcome is unknown and the charge may have gone
// through. Hold the order (no retry session yet) and wait for the payment.*
// webhook for this order_reference: fulfil on payment.captured (or void
// before settlement); declined/reversed/failed mean nothing was kept.
// Or poll the transaction status every 60 s -- only if
// gateway_transaction_id is set (usually null here: then the id comes only
// from the payment.* webhook).
return { ...payload, action: "await_payment_webhook" };
}
// decline_reason null (or any value you don't recognise, treated as null):
// no charge was submitted by an expired session. Confirm order_reference and
// amount match your order before fulfilling a completed one.
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:
problem_type = payload.get("type")
raise RuntimeError(f"checkout session fetch failed: {problem_type} ({resp.status_code})")
session = payload["data"]
if session["status"] == "authorized":
# A hold, not a payment: the card is held for the full amount but
# nothing was captured. Capture it (Payments API, using
# gateway_transaction_id) or let the hold lapse -- a hold can't be
# voided. Fulfil only once the payment.captured webhook arrives.
return {**payload, "action": "capture_or_let_hold_lapse"}
if session["status"] not in ("pending", "processing", "completed", "failed", "expired", "cancelled"):
# More statuses may be added: treat one you don't recognise as not paid.
return {**payload, "action": "treat_as_not_paid"}
if session["status"] == "expired" and session.get("decline_reason") == "expired_while_processing":
# Expired mid-payment: the outcome is unknown and the charge may have
# gone through. Hold the order (no retry session yet) and wait for the
# payment.* webhook for this order_reference: fulfil on payment.captured
# (or void before settlement); declined/reversed/failed mean nothing
# was kept. Or poll the transaction status every 60 s --
# only if gateway_transaction_id is set (usually None here: then the
# id comes only from the payment.* webhook).
return {**payload, "action": "await_payment_webhook"}
# decline_reason None (or any value you don't recognise, treated as None):
# no charge was submitted by an expired session. Confirm order_reference
# and amount match your order before fulfilling a completed one.
return payload
if __name__ == "__main__":
print(json.dumps(retrieve_checkout_session(), indent=2))
Always send your secret key. A
GET without X-Api-Key doesn’t fail — it returns a reduced public view with display fields only (amount, currency, currency_minor_units, description, line items, status, expiry, locale, mode, payment methods), which the hosted page itself uses. It has none of your merchant-only fields and is rate-limited per client IP and checkout. Never use it to confirm an outcome.data.order_reference and data.amount/data.currency match the order you’re fulfilling — don’t fulfil solely because status says completed without also matching the order.
authorized is a hold, not a payment — fulfil only on payment.captured. Occasionally a sale ends with the card held for the full amount instead of charged — for example, when the shopper paid with UOB Rewards points and the points redemption failed. The session shows status: "authorized", and the shopper still returns to your success_url (a signed redirect carries status=authorized; in embedded mode, CHECKOUT_COMPLETE carries status: "authorized"). Hosted checkout never captures it, so the transaction stays AUTHORIZED (webhook authorization.created), not CAPTURED. Capture the hold using the session’s gateway_transaction_id and fulfil once payment.captured arrives, or let the hold lapse (a hold can’t be voided). Treat any status you don’t recognise as not paid. See Final events for a one-shot sale.checkout_id or API key on the GET returns 404 urn:radiumone:checkout-hpp:resource-not-found; a missing session, or one that belongs to a different account, returns 404 urn:radiumone:checkout-hpp:session-not-found with an identical body either way — don’t try to distinguish the two.
UX hint: the redirect signature
If you’ve configured a redirect secret, a successful redirect to yoursuccess_url carries checkout_id, status, ts, sig, and transaction_id when one is known. ts is a Unix timestamp in seconds (contrast with the authenticated GET response, where expires_at/created_at/updated_at are epoch milliseconds, and the create response’s expires_at, which is an ISO 8601 string). Verifying sig confirms the URL wasn’t altered in the shopper’s browser — it is not proof that a charge happened, and it is never sent at all on a decline, expiry, or back-button return (see Redirect integration).
RadiumOne doesn’t check
ts itself — the checkout team’s guidance is that your server enforces the tolerance: reject a signed return whose ts is more than 5 minutes old, the same as an invalid sig.In two rare cases — replaying the payment-completion call on a session that’s already reached a terminal state — the redirect can carry
success_url (or, for a failed session, cancel_url) with none of the usual query parameters, not even checkout_id. If you see a return with no parameters at all, don’t assume anything from the URL — confirm the outcome with an authenticated GET as described above.Key encoding differs from webhooks. The redirect signature’s HMAC key is the full
rsec_… secret string, used directly. This is different from the webhook signature, whose key is the raw bytes obtained by hex-decoding the string after stripping whsec_. Using the wrong encoding for either one makes every signature fail to verify.#!/usr/bin/env node
// Verify an HPP redirect signature. Node 18+, no dependencies.
//
// Key: the FULL `rsec_...` secret STRING, used directly as the HMAC key
// (this differs from the webhook secret, which is hex-decoded after
// stripping its prefix -- see verify-webhook-signature).
// Payload: `${checkout_id}|${status}|${transaction_id_or_empty}|${ts}`.
// `state` is NOT part of the signed payload.
// Fail closed: if a secret is configured and `sig` is missing (or invalid),
// treat the redirect as UNVERIFIED -- never as proof of payment. Always
// confirm fulfilment via an authenticated GET or a webhook.
import { createHmac, timingSafeEqual } from "node:crypto";
const SECRET_PATTERN = /^rsec_[0-9a-fA-F]{48}$/;
const SIGNATURE_HEX_PATTERN = /^[0-9a-fA-F]{64}$/;
/**
* @param {{secret: string, checkoutId: string, status: string, transactionId: string|null,
* ts: number, sig: string|null, storedCheckoutId: string, toleranceSeconds?: number, now?: number}} args
* @returns {boolean}
*/
export function verifyRedirectSignature({
secret,
checkoutId,
status,
transactionId,
ts,
sig,
storedCheckoutId,
toleranceSeconds = 300,
now = Math.floor(Date.now() / 1000),
}) {
// Fail closed: an empty, missing, or wrong-shaped secret is never a valid
// signing key -- never fall through to HMAC-ing with an empty string.
if (typeof secret !== "string" || !SECRET_PATTERN.test(secret)) return false;
if (typeof sig !== "string" || sig.length === 0) return false;
if (!checkoutId || !storedCheckoutId || !status) return false;
if (checkoutId !== storedCheckoutId) return false;
// Number.isInteger (not isFinite): a signed/fractional ts (e.g. 1700000000.5)
// is not a valid Unix timestamp and must be rejected, not silently truncated.
if (typeof ts !== "number" || !Number.isInteger(ts) || Math.abs(now - ts) > toleranceSeconds) return false;
if (!SIGNATURE_HEX_PATTERN.test(sig)) return false;
const payload = `${checkoutId}|${status}|${transactionId ?? ""}|${ts}`;
const expected = Buffer.from(createHmac("sha256", secret).update(payload).digest("hex"), "hex");
const actual = Buffer.from(sig, "hex");
if (expected.length !== actual.length) return false;
return timingSafeEqual(expected, actual);
}
// Example: verifying a success_url visit.
// const url = new URL(req.url, "https://shop.example.com");
// const ok = verifyRedirectSignature({
// secret: process.env.RADIUMONE_REDIRECT_SECRET,
// checkoutId: url.searchParams.get("checkout_id"),
// status: url.searchParams.get("status"),
// transactionId: url.searchParams.get("transaction_id"),
// ts: Number(url.searchParams.get("ts")),
// sig: url.searchParams.get("sig"),
// storedCheckoutId: sessionRecord.checkoutId, // your own stored order/session mapping
// });
// // The signature is a UX hint only. Always confirm amount + status via
// // GET /api/v1/checkout/sessions/{id} (X-Api-Key) or a gateway webhook.
#!/usr/bin/env python3
"""Verify an HPP redirect signature. Python 3.10+, standard library only.
Key: the FULL ``rsec_...`` secret STRING, used directly as the HMAC key
(this differs from the webhook secret, which is hex-decoded after
stripping its prefix -- see verify-webhook-signature).
Payload: ``{checkout_id}|{status}|{transaction_id_or_empty}|{ts}``.
``state`` is NOT part of the signed payload.
Fail closed: if a secret is configured and ``sig`` is missing (or invalid),
treat the redirect as UNVERIFIED -- never as proof of payment. Always
confirm fulfilment via an authenticated GET or a webhook.
"""
import hmac
import hashlib
import re
import time
# fullmatch (not match): plain `match()` with a trailing `$` lets Python
# accept a string with one trailing "\n" (same class of bug as PCRE without
# the `D` modifier) -- see verify-webhook-signature/python.py.
_SECRET_PATTERN = re.compile(r"^rsec_[0-9a-fA-F]{48}$")
_SIGNATURE_HEX_PATTERN = re.compile(r"^[0-9a-fA-F]{64}$")
def verify_redirect_signature(
secret: str,
checkout_id: str,
status: str,
transaction_id: str | None,
ts,
sig: str | None,
stored_checkout_id: str,
tolerance_seconds: int = 300,
now: int | None = None,
) -> bool:
now = int(time.time()) if now is None else now
# Fail closed: an empty, missing, or wrong-shaped secret is never a
# valid signing key -- never fall through to HMAC-ing with an empty string.
if not isinstance(secret, str) or not _SECRET_PATTERN.fullmatch(secret):
return False
if not sig:
return False
if not checkout_id or not stored_checkout_id or not status:
return False
if checkout_id != stored_checkout_id:
return False
if not isinstance(ts, int) or isinstance(ts, bool):
return False
if abs(now - ts) > tolerance_seconds:
return False
if not _SIGNATURE_HEX_PATTERN.fullmatch(sig):
return False
payload = f"{checkout_id}|{status}|{transaction_id or ''}|{ts}"
expected_hex = hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest()
return hmac.compare_digest(bytes.fromhex(expected_hex), bytes.fromhex(sig))
# Example: verifying a success_url visit (Flask-style).
# def _parse_ts(raw):
# # Never let a malformed query param crash the handler -- an unparsable
# # ts must reach verify_redirect_signature as a non-int (it rejects any
# # non-int/bool ts), not raise before the fail-closed check even runs.
# try:
# return int(raw)
# except (TypeError, ValueError):
# return None
#
# ok = verify_redirect_signature(
# secret=os.environ["RADIUMONE_REDIRECT_SECRET"],
# checkout_id=request.args.get("checkout_id"),
# status=request.args.get("status"),
# transaction_id=request.args.get("transaction_id"),
# ts=_parse_ts(request.args.get("ts")),
# sig=request.args.get("sig"),
# stored_checkout_id=session_record.checkout_id,
# )
# # The signature is a UX hint only. Always confirm amount + status via
# # GET /api/v1/checkout/sessions/{id} (X-Api-Key) or a gateway webhook.
<?php
declare(strict_types=1);
/**
* Verify an HPP redirect signature. PHP 8.1+, no framework.
*
* Key: the FULL `rsec_...` secret STRING, used directly as the HMAC key
* (this differs from the webhook secret, which is hex-decoded after
* stripping its prefix -- see verify-webhook-signature).
* Payload: "{checkout_id}|{status}|{transaction_id_or_empty}|{ts}".
* `state` is NOT part of the signed payload.
* Fail closed: if a secret is configured and `sig` is missing (or invalid),
* treat the redirect as UNVERIFIED -- never as proof of payment. Always
* confirm fulfilment via an authenticated GET or a webhook.
*
* `$ts` is `int|string|null` -- a non-numeric or missing value is rejected
* rather than coerced, so a malformed query param never silently becomes 0.
*/
function verifyRedirectSignature(
string $secret,
string $checkoutId,
string $status,
?string $transactionId,
mixed $ts,
?string $sig,
string $storedCheckoutId,
int $toleranceSeconds = 300,
?int $now = null
): bool {
$now ??= time();
// Fail closed: an empty, missing, or wrong-shaped secret is never a
// valid signing key -- never fall through to HMAC-ing with an empty string.
// `D` anchors `$` to the absolute end of the subject -- without it PCRE
// lets `$` match just before a single trailing "\n", so a secret/signature
// sourced from a file with a trailing newline would wrongly pass shape
// validation here.
if (!preg_match('/^rsec_[0-9a-fA-F]{48}$/D', $secret)) {
return false;
}
if ($sig === null || $sig === '') {
return false;
}
if ($checkoutId === '' || $storedCheckoutId === '' || $status === '') {
return false;
}
if ($checkoutId !== $storedCheckoutId) {
return false;
}
if (is_int($ts)) {
$timestamp = $ts;
} elseif (is_string($ts) && ctype_digit($ts)) {
$timestamp = (int) $ts;
} else {
return false;
}
if (abs($now - $timestamp) > $toleranceSeconds) {
return false;
}
if (!preg_match('/^[0-9a-fA-F]{64}$/D', $sig)) {
return false;
}
$payload = "{$checkoutId}|{$status}|" . ($transactionId ?? '') . "|{$timestamp}";
$expectedHex = hash_hmac('sha256', $payload, $secret);
return hash_equals($expectedHex, strtolower($sig));
}
// Example: verifying a success_url visit.
// $ok = verifyRedirectSignature(
// getenv('RADIUMONE_REDIRECT_SECRET'),
// $_GET['checkout_id'] ?? '',
// $_GET['status'] ?? '',
// $_GET['transaction_id'] ?? null,
// $_GET['ts'] ?? null,
// $_GET['sig'] ?? null,
// $sessionRecord['checkout_id'],
// );
// // The signature is a UX hint only. Always confirm amount + status via
// // GET /api/v1/checkout/sessions/{id} (X-Api-Key) or a gateway webhook.
import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.util.regex.Pattern;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
/**
* Verify an HPP redirect signature. Java 17+, no framework
* ({@code javax.crypto.Mac} only).
*
* Key: the FULL {@code rsec_...} secret STRING, used directly as the HMAC
* key (this differs from the webhook secret, which is hex-decoded after
* stripping its prefix -- see verify-webhook-signature).
* Payload: {@code "{checkout_id}|{status}|{transaction_id_or_empty}|{ts}"}.
* {@code state} is NOT part of the signed payload.
* Fail closed: if a secret is configured and {@code sig} is missing (or
* invalid), treat the redirect as UNVERIFIED -- never as proof of payment.
* Always confirm fulfilment via an authenticated GET or a webhook.
*
* {@code ts} is passed as a {@code String} so a malformed/non-numeric
* timestamp can be rejected instead of failing {@code Long.parseLong} at
* the caller.
*/
public final class VerifyRedirectSignature {
private static final Pattern SECRET_PATTERN = Pattern.compile("^rsec_[0-9a-fA-F]{48}$");
private static final Pattern SIGNATURE_HEX_PATTERN = Pattern.compile("^[0-9a-fA-F]{64}$");
private static final Pattern TIMESTAMP_PATTERN = Pattern.compile("^-?\\d+$");
private VerifyRedirectSignature() {
}
public static boolean verify(
String secret,
String checkoutId,
String status,
String transactionId,
String ts,
String sig,
String storedCheckoutId,
int toleranceSeconds,
Long now) {
long nowSeconds = now != null ? now : System.currentTimeMillis() / 1000L;
// Fail closed: an empty, missing, or wrong-shaped secret is never a
// valid signing key -- never fall through to HMAC-ing with an empty string.
if (secret == null || !SECRET_PATTERN.matcher(secret).matches()) {
return false;
}
if (sig == null || sig.isEmpty()) {
return false;
}
if (checkoutId == null || checkoutId.isEmpty() || storedCheckoutId == null || storedCheckoutId.isEmpty()
|| status == null || status.isEmpty()) {
return false;
}
if (!checkoutId.equals(storedCheckoutId)) {
return false;
}
if (ts == null || !TIMESTAMP_PATTERN.matcher(ts).matches()) {
return false;
}
long timestamp;
try {
timestamp = Long.parseLong(ts);
} catch (NumberFormatException e) {
return false;
}
if (Math.abs(nowSeconds - timestamp) > toleranceSeconds) {
return false;
}
if (!SIGNATURE_HEX_PATTERN.matcher(sig).matches()) {
return false;
}
String payload = checkoutId + "|" + status + "|" + (transactionId != null ? transactionId : "") + "|" + timestamp;
byte[] expected;
try {
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
expected = mac.doFinal(payload.getBytes(StandardCharsets.UTF_8));
} catch (Exception e) {
return false;
}
byte[] actual = hexToBytes(sig);
return MessageDigest.isEqual(expected, actual);
}
private static byte[] hexToBytes(String hex) {
byte[] out = new byte[hex.length() / 2];
for (int i = 0; i < out.length; i++) {
out[i] = (byte) Integer.parseInt(hex.substring(i * 2, i * 2 + 2), 16);
}
return out;
}
// Example: verifying a success_url visit (plain servlet).
// boolean ok = VerifyRedirectSignature.verify(
// System.getenv("RADIUMONE_REDIRECT_SECRET"),
// request.getParameter("checkout_id"),
// request.getParameter("status"),
// request.getParameter("transaction_id"),
// request.getParameter("ts"),
// request.getParameter("sig"),
// sessionRecord.getCheckoutId(),
// 300,
// null);
// // The signature is a UX hint only. Always confirm amount + status via
// // GET /api/v1/checkout/sessions/{id} (X-Api-Key) or a gateway webhook.
}
sig, treat it as unverified — never as confirmation of payment. Also confirm that checkout_id in the URL matches the ID your server stored for that order before trusting anything else in the URL. See Reject invalid redirect signatures for the full walkthrough.
Decision table
| Situation | What to do |
|---|---|
Redirect with a valid sig | Still confirm via webhook or authenticated GET before fulfilling. status=authorized is an uncaptured hold — fulfil on payment.captured only (see the warning above) |
Redirect with no sig (no secret configured) | Confirm via webhook or authenticated GET — the URL alone proves nothing |
Redirect with an invalid/stale sig | Treat as unverified; confirm via webhook or authenticated GET; investigate if it recurs |
postMessage event received (embedded mode) | Confirm via webhook or authenticated GET before navigating the shopper onward |
| Webhook received | Authoritative — check order_reference and amount, then act on it: fulfil on payment.captured only (final events) |
Authenticated GET shows status: "completed" | Authoritative — check order_reference and amount, then fulfil |
Authenticated GET shows status: "authorized" | The card is held, not charged — capture it through the Payments API using gateway_transaction_id, or let the hold lapse (a hold can’t be voided); fulfil on payment.captured only (see the warning above) |
Authenticated GET shows status: "failed" | The payment was declined — see Handle declined hosted checkout payments |
Authenticated GET shows status: "expired" | The session can’t be paid. decline_reason: null — no charge was submitted. "expired_while_processing" — the outcome is unknown and the charge may have gone through; the payment.* webhook or the transaction status is the final answer. Fulfil only on payment.captured (see Session expired mid-payment) |
Redirect secret: rotate, don’t delete
A redirect secret can be rotated or deleted from your server (via the gateway API, using a bearer access token):#!/usr/bin/env bash
# Rotate the redirect-signature secret. The plaintext is returned exactly
# once — store it immediately. Old and new secrets both verify for a grace
# window after rotation.
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 with the merchant-secret-rotate scope}"
curl -sS -X POST "$API_BASE/v1/merchant/redirect-secret/rotate" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN"
#!/usr/bin/env node
// Rotate the redirect-signature secret. The plaintext is returned exactly
// once — store it immediately. Node 18+ ESM fetch.
// Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE.
const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
async function rotateRedirectSecret() {
const res = await fetch(`${API_BASE}/v1/merchant/redirect-secret/rotate`, {
method: "POST",
headers: { Authorization: `Bearer ${accessToken}` },
});
const payload = await res.json();
if (!res.ok) {
throw new Error(`redirect-secret rotate failed: ${payload.type ?? payload.code} (${res.status})`);
}
// Never log payload.data.redirect_secret — store it in your secret manager only.
return payload;
}
rotateRedirectSecret().then((r) => console.log(JSON.stringify(r, null, 2)));
#!/usr/bin/env python3
"""Rotate the redirect-signature secret. The plaintext is returned exactly
once — store it immediately.
"""
import json
import os
import requests
API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")
def rotate_redirect_secret() -> dict:
resp = requests.post(
f"{API_BASE}/v1/merchant/redirect-secret/rotate",
headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
timeout=30,
)
payload = resp.json()
if not resp.ok:
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"redirect-secret rotate failed: {code} ({resp.status_code})")
# Never log payload["data"]["redirect_secret"] — store it in your secret manager only.
return payload
if __name__ == "__main__":
print(json.dumps(rotate_redirect_secret(), indent=2))
ttl_minutes (5–60 minutes — see Session lifecycle). If you want those in-flight sessions’ redirects to keep verifying, keep the old secret available in your own verifier for at least 65 minutes after you rotate (the 60-minute maximum session lifetime, plus the redirect signature’s 5-minute timestamp tolerance), then remove it.
Deleting the redirect secret downgrades your protection. Once deleted, redirect URLs no longer carry a
sig at all, so the UX-hint layer disappears entirely — you’re relying solely on the webhook/authenticated-GET layer (which you should already be doing). If you no longer want signed redirects, prefer leaving the secret in place and simply not depending on it, or contact support about your options — don’t delete it as a routine operation.Next steps
Webhook event types
The full authoritative payload reference.
Session lifecycle
Statuses, TTL, and cancellation.
Handle failures
Ten common failure scenarios and what to do for each.
Redirect and signature errors
Every signal a return to your site can and can’t carry.