TL;DR: A missing redirect isn’t a failed payment — confirm with a webhook or
GET, not the browser.When this happens
- The shopper’s device loses connectivity right after submitting the card form.
- The shopper closes the browser tab or app before the hosted page finishes redirecting.
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.What you see
| Signal | Value |
|---|---|
| Redirect | Never arrives at success_url or cancel_url |
| Session status | processing while the charge is in flight, then a terminal status (completed, authorized for an uncaptured hold, or failed) once it resolves — independent of whether the shopper’s browser is still connected |
| Webhook | payment.captured, payment.declined, or payment.failed fires once the gateway resolves the charge |
What to do
1
Don't assume the payment failed
A missing redirect only tells you the shopper’s browser didn’t complete the round trip — it says nothing about whether the charge itself succeeded.
2
Wait for the authoritative signal
Fulfil only from a webhook or an authenticated
GET — never because the redirect didn’t happen (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. 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))
#!/usr/bin/env node
// Minimal webhook handler using Node's built-in http server (no framework).
// Verify the signature on the RAW body, respond 2xx quickly (before any slow
// work), and dedupe on the event id -- deliveries are at-least-once and unordered.
import { createServer } from "node:http";
import { createHmac, timingSafeEqual } from "node:crypto";
const WEBHOOK_SECRET = process.env.RADIUMONE_WEBHOOK_SECRET ?? "";
const seenEventIds = new Set(); // replace with a persistent store in production
const SECRET_PATTERN = /^whsec_[0-9a-fA-F]{64}$/;
const SIGNATURE_HEX_PATTERN = /^[0-9a-fA-F]{64}$/;
const TIMESTAMP_PATTERN = /^\d+$/;
// Fails closed on every malformed input (missing header, bad secret shape,
// non-integer timestamp) -- never throws. See verify-webhook-signature for
// the fully-documented, standalone version of this function.
function verifySignature(secret, header, rawBody, toleranceSeconds = 300) {
if (typeof secret !== "string" || !SECRET_PATTERN.test(secret)) return false;
if (typeof header !== "string" || header.length === 0) return false;
const fields = {};
for (const part of header.split(",")) {
const idx = part.indexOf("=");
if (idx < 0) return false;
fields[part.slice(0, idx)] = part.slice(idx + 1);
}
const { v, t, s } = fields;
if (!v || !t || !s) return false;
if (v !== "1") return false;
if (!TIMESTAMP_PATTERN.test(t)) return false;
if (!SIGNATURE_HEX_PATTERN.test(s)) return false;
if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSeconds) return false;
const key = Buffer.from(secret.slice("whsec_".length), "hex");
const signingInput = Buffer.concat([Buffer.from(`${v}.${t}.`), rawBody]);
const expectedHex = createHmac("sha256", key).update(signingInput).digest("hex");
const expected = Buffer.from(expectedHex, "hex");
const actual = Buffer.from(s, "hex");
return expected.length === actual.length && timingSafeEqual(expected, actual);
}
const server = createServer((req, res) => {
if (req.method !== "POST" || req.url !== "/webhooks/radiumone") {
res.writeHead(404).end();
return;
}
const chunks = [];
req.on("data", (chunk) => chunks.push(chunk));
req.on("end", () => {
const rawBody = Buffer.concat(chunks); // verify against RAW bytes, not parsed JSON
const header = req.headers["x-radiumone-signature"] ?? "";
if (!verifySignature(WEBHOOK_SECRET, header, rawBody)) {
res.writeHead(401).end();
return;
}
const event = JSON.parse(rawBody.toString("utf8"));
if (seenEventIds.has(event.id)) {
res.writeHead(200).end(); // duplicate delivery: acknowledge, don't reprocess
return;
}
seenEventIds.add(event.id);
// Respond 2xx immediately; do slow work (DB writes, fulfilment) after
// responding, e.g. via a queue. Never rely on the payload alone to
// fulfil -- confirm amount and status match your order first.
res.writeHead(200).end();
console.log("received", event.type, event.id);
});
});
server.listen(process.env.PORT ?? 3001);
#!/usr/bin/env python3
"""Minimal webhook handler using Python's built-in http.server (no framework).
Verify the signature on the RAW body, respond 2xx quickly (before any slow
work), and dedupe on the event ``id`` -- deliveries are at-least-once and
unordered.
"""
import hmac
import hashlib
import json
import os
import re
import time
from http.server import BaseHTTPRequestHandler, HTTPServer
WEBHOOK_SECRET = os.environ.get("RADIUMONE_WEBHOOK_SECRET", "")
SEEN_EVENT_IDS: set[str] = set() # replace with a persistent store in production
_SECRET_PATTERN = re.compile(r"^whsec_[0-9a-fA-F]{64}$")
_SIGNATURE_HEX_PATTERN = re.compile(r"^[0-9a-fA-F]{64}$")
_TIMESTAMP_PATTERN = re.compile(r"^\d+$")
# Fails closed on every malformed input (missing header, bad secret shape,
# non-integer timestamp) -- never raises. See verify-webhook-signature for
# the fully-documented, standalone version of this function.
def verify_signature(secret: str, header: str, raw_body: bytes, tolerance_seconds: int = 300) -> bool:
if not _SECRET_PATTERN.match(secret):
return False
if not header:
return False
fields = {}
for part in header.split(","):
if "=" not in part:
return False
k, _, v = part.partition("=")
fields[k] = v
v, t, s = fields.get("v"), fields.get("t"), fields.get("s")
if not v or not t or not s:
return False
if v != "1":
return False
if not _TIMESTAMP_PATTERN.match(t):
return False
if not _SIGNATURE_HEX_PATTERN.match(s):
return False
if abs(int(time.time()) - int(t)) > tolerance_seconds:
return False
key = bytes.fromhex(secret[len("whsec_"):])
signing_input = f"{v}.{t}.".encode("utf-8") + raw_body
expected_hex = hmac.new(key, signing_input, hashlib.sha256).hexdigest()
return hmac.compare_digest(bytes.fromhex(expected_hex), bytes.fromhex(s))
class WebhookHandler(BaseHTTPRequestHandler):
def do_POST(self):
if self.path != "/webhooks/radiumone":
self.send_response(404)
self.end_headers()
return
length = int(self.headers.get("Content-Length", 0))
raw_body = self.rfile.read(length) # verify against RAW bytes, not parsed JSON
header = self.headers.get("X-RadiumOne-Signature", "")
if not verify_signature(WEBHOOK_SECRET, header, raw_body):
self.send_response(401)
self.end_headers()
return
event = json.loads(raw_body)
if event["id"] in SEEN_EVENT_IDS:
self.send_response(200) # duplicate delivery: acknowledge, don't reprocess
self.end_headers()
return
SEEN_EVENT_IDS.add(event["id"])
# Respond 2xx immediately; do slow work (DB writes, fulfilment) after
# responding, e.g. via a queue. Never rely on the payload alone to
# fulfil -- confirm amount and status match your order first.
self.send_response(200)
self.end_headers()
print("received", event["type"], event["id"])
if __name__ == "__main__":
HTTPServer(("", int(os.environ.get("PORT", 3001))), WebhookHandler).serve_forever()
3
Poll with backoff until the session reaches a terminal state
If you’re reconciling by polling rather than waiting on the webhook, back off between calls —
processing can legitimately last a few seconds while the gateway completes the charge. Stop once you see completed, failed, expired, or cancelled. An expired session with decline_reason: "expired_while_processing" expired mid-payment: its outcome is unknown and the charge may have gone through, so wait for the payment.* webhook or poll the transaction status, and fulfil only on payment.captured — see Session expired mid-payment.Related
Verify the payment result
The full decision table for every result signal.
Session lifecycle
Statuses in full, including
processing.Handle payment service outages during checkout
When the gateway itself — not just the shopper’s connection — is the problem.
Handle failures
All ten failure scenarios, symptom → page.