Timeouts - Payments API - RadiumOne Docs

Your request to create, capture, void, or refund a transaction gets no response, or a 503 with no clear outcome. The charge may or may not have reached the card network — resolve it before you do anything else.

TL;DR — No response, or 503? Resend the identical request with the same request_id/operation_id first — that’s how you recover the transaction id and current status. Then let the confirming webhook tell you the final outcome (recommended); call status inquiry instead if you don’t use webhooks or need an answer right now. Never mint a new key for the same attempt.

When this happens

Your HTTP client times out waiting for a response — the request may have already reached RadiumOne and the acquirer. You don’t have a transaction id yet in this case — the response that would have carried it never arrived.
RadiumOne’s own upstream connection to the payment switch times out, returned as 503 urn:radiumone:gateway:switch-timeout with retry_allowed: false. The outcome is genuinely indeterminate: the charge may have been forwarded to the acquirer host before the timeout.

What you see

Signal	Value
HTTP status	No response, or `503`
Error type	`urn:radiumone:gateway:switch-timeout` (`retry_allowed: false`)
Transaction status	Often `PENDING`, until it resolves or becomes a reversal candidate
Webhook	The eventual outcome event, once it resolves

retry_allowed: false here doesn’t mean “give up” — it means don’t blindly retry as if this were a fresh attempt. A blind retry with a new idempotency key risks a duplicate charge if the original request actually landed.

Recovery path

A create-type request gets no response, or a 5xx.
Resend the identical body with the same request_id/operation_id, with backoff. This is what recovers the transaction id — the replay returns the stored result whatever it is, including PENDING.
If the replay itself comes back 409 idempotency-body-mismatch, the resend didn’t match the original attempt byte-for-byte — resend the stored original body instead.
Any other 4xx on the replay means something else is wrong with the request — fix it before you retry again.
If the replayed response is 2xx with CAPTURED, AUTHORIZED, or DECLINED, that’s final — branch on status and stop.
If it’s 2xx with PENDING, keep the id from that response and wait for the confirming webhook (recommended — it pushes the outcome to you); call status inquiry instead if you don’t have webhooks set up or need an answer right now.
If it’s 2xx with FAILED, that means the transaction didn’t complete — it’s not a guarantee that no funds moved (only VOIDED/REVERSED assert that). If the outcome was genuinely unknown after an upstream timeout, RadiumOne arms an automatic reversal instead of leaving it FAILED (REVERSAL_PENDING → REVERSED — see Understand automatic reversals). Confirm with a status GET before you consider any new attempt with a new request_id.
If you still get no response after a few tries, or you can’t reproduce the exact original body, don’t guess — wait for the confirming webhook instead, or contact support with your order_reference and approximate timestamp if you need it sooner.
Never send a new request_id to “retry faster” — that’s the path that risks a duplicate charge.

What to do

Don't create a new request

Never mint a new request_id (or operation_id) just because the first attempt was slow or came back as 503. Reuse the same key for whatever you do next.

Replay the identical request to recover the transaction id

If you don’t have a transaction id yet — the usual case after a client-side timeout — resend the exact same body with the exact same key first (API reference):

#!/usr/bin/env bash
# Purchase (authorise + capture in one call). Any 2xx is a response — branch
# on data.status. On a timeout/5xx/PENDING, retry with the SAME request_id;
# never mint a new one for the same order attempt.
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
// Purchase (authorise + capture in one call). 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 (or poll GET /v1/transactions/{id}/status) — never mint a new
// request_id for the same order 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 createPurchase(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; // network timeout: retry with the same body/request_id
    }

    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; // retry with the same request_id
    }

    const payload = await res.json();
    if (!res.ok) {
      // 4xx: not retryable by re-sending — fix the request, or handle
      // urn:radiumone:transaction:idempotency-body-mismatch if you changed it.
      throw new Error(`purchase failed: ${payload.type ?? payload.code} (${res.status})`);
    }

    if (payload.data.status === "PENDING") {
      if (attempt === maxAttempts) return payload; // caller should poll GET status / wait for webhook
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue; // retry the same request_id
    }

    // Branch on data.status: CAPTURED (success) | DECLINED (final, no retry) | FAILED.
    return payload;
  }
  throw new Error("unreachable");
}

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

#!/usr/bin/env python3
"""Purchase (authorise + capture in one call). Python 3.10+, requests.

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 (or poll GET /v1/transactions/{id}/status) — never mint a new
request_id for the same order 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(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  # network timeout: retry with the same body/request_id

        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  # retry with the same request_id

        payload = resp.json()
        if not resp.ok:
            # 4xx: not retryable by re-sending — fix the request, or handle
            # urn:radiumone:transaction:idempotency-body-mismatch if you changed it.
            code = payload.get("type") or payload.get("code")
            raise RuntimeError(f"purchase failed: {code} ({resp.status_code})")

        if payload["data"]["status"] == "PENDING":
            if attempt == max_attempts:
                return payload  # caller should poll GET status / wait for webhook
            time.sleep(backoff_seconds(attempt))
            continue  # retry the same request_id

        # Branch on data.status: CAPTURED (success) | DECLINED (final, no retry) | FAILED.
        return payload

    raise RuntimeError("unreachable")


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

The response is the stored transaction, whatever its status, including its id — this is always safe to do, any number of times.

Once you have the id, let the webhook confirm the outcome — or check now with status inquiry

If you have a webhook endpoint registered, the confirming event (payment.*, authorization.*, refund.*) arrives without you polling anything — this is the recommended path, and it’s what Webhooks overview assumes. If you don’t use webhooks, or you need an answer right now rather than waiting, call the status-inquiry endpoint instead — it never writes a new row, so it’s always safe to call on demand (API reference):

#!/usr/bin/env bash
# Live acquirer status inquiry for a transaction (no new row written). Use
# this to recover after a timeout instead of guessing the outcome.
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_TRANSACTION_ID:?set RADIUMONE_TRANSACTION_ID to the transaction to inquire}"

curl -sS "$API_BASE/v1/transactions/$RADIUMONE_TRANSACTION_ID/status" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN"

#!/usr/bin/env node
// Live acquirer status inquiry for a transaction (no new row written). Use
// this to recover after a timeout instead of guessing the outcome. Node 18+
// ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_TRANSACTION_ID, RADIUMONE_API_BASE.
const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
const transactionId = process.env.RADIUMONE_TRANSACTION_ID;

async function inquireTransactionStatus() {
  const res = await fetch(`${API_BASE}/v1/transactions/${transactionId}/status`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const payload = await res.json();
  if (!res.ok) {
    throw new Error(`status inquiry failed: ${payload.type ?? payload.code} (${res.status})`);
  }
  return payload; // branch on data.status
}

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

#!/usr/bin/env python3
"""Live acquirer status inquiry for a transaction (no new row written). Use
this to recover after a timeout instead of guessing the outcome.
"""
import json
import os

import requests

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


def inquire_transaction_status() -> dict:
    transaction_id = os.environ["RADIUMONE_TRANSACTION_ID"]
    resp = requests.get(
        f"{API_BASE}/v1/transactions/{transaction_id}/status",
        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"status inquiry failed: {code} ({resp.status_code})")
    return payload  # branch on data.status


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

No id and the replay didn't resolve it? Wait for the webhook or contact support

If you can’t reproduce the exact original body (for example, you lost the amount from a form submission), a replay isn’t possible. RadiumOne doesn’t expose a list-by-order_reference lookup, so wait for the confirming webhook (payment.*, authorization.*, refund.*), or contact support with your order_reference and approximate timestamp.

Branch on the final status

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

Reconcile via webhook if you still can't resolve it

If every synchronous option above is exhausted, wait for the confirming webhook (payment.*, authorization.*, refund.*) instead of guessing — see Webhooks overview.

Prevent it

Set a client-side HTTP timeout longer than a few seconds — a request that’s merely slow at the switch shouldn’t look identical to a dropped connection on your side.
Build the retry-with-same-key path into your integration before you go live, not during your first production incident.

Test it

See Test your integration for simulated timeout scenarios.

Prevent duplicate payments

The cross-product guide to avoiding duplicate charges.

Check a transaction's status

Status inquiry and timeout recovery, in depth.

Problem format and retries

The full retry-rules reference.

Understand automatic reversals

What happens if the switch timeout turns into a reversal.

Introduction

Guides

Payment methods

3D Secure

Handle failures

Webhooks

Errors

Reference

Timeouts - Payments API

When this happens

What you see

Recovery path

What to do

Prevent it

Test it

Prevent duplicate payments

Check a transaction's status

Problem format and retries

Understand automatic reversals

​When this happens

​What you see

​Recovery path

​What to do

​Prevent it

​Test it

​Related

Prevent duplicate payments

Check a transaction's status

Problem format and retries

Understand automatic reversals

When this happens

What you see

Recovery path

What to do

Prevent it

Test it

Related