Void and refund conflicts - Payments API

You called void or refund on the wrong side of the settlement batch boundary, tried to return more than remains, or tried to touch a transaction that’s no longer eligible.

TL;DR — Void while the batch is open, refund once it’s closed. 422 tx:amount-exceeds-captured means you asked for more than remains (original minus prior refunds).

When this happens

Void while the settlement batch is OPEN. Refund once it’s CLOSED. You can’t do either the other way around:

Voiding a transaction whose batch has already closed returns 409 urn:radiumone:tx:void-on-non-open-batch.
Refunding a transaction whose batch is still open returns 409 urn:radiumone:tx:refund-on-open-batch.

The boundary is the settlement batch closing, not the card network settling with the issuer. Check GET /v1/transactions/{id}/status or a settlement.* webhook if you’re unsure which state you’re in. See Resolve void and refund conflicts if you hit either error.

Void after the batch closed — 409 urn:radiumone:tx:void-on-non-open-batch.
Refund while the batch is still open — 409 urn:radiumone:tx:refund-on-open-batch.
Void while an earlier void on the same sale hasn’t resolved yet — 409 urn:radiumone:transaction:void-reversal-pending. It’s transient: check the transaction status for the earlier void’s outcome, and void again later only if the sale still isn’t voided.
Refund amount exceeds what’s left (original minus prior refunds) — 422 urn:radiumone:tx:amount-exceeds-captured.
Refund attempted after the refund window has elapsed since capture/settlement — 422 urn:radiumone:tx:refund-window-expired.
The target transaction isn’t in a refundable state (already refunded in full, voided, or otherwise) — 422 urn:radiumone:tx:refund-target-not-refundable.
The transaction’s state doesn’t allow the operation you requested at all — 409 urn:radiumone:tx:invalid-state-transition.

What you see

Signal	Value
HTTP status	`409` (batch-state, pending-void, and invalid-state-transition conflicts) or `422` (amount/window conflicts)
Error type	`tx:void-on-non-open-batch` / `tx:refund-on-open-batch` / `transaction:void-reversal-pending` / `tx:invalid-state-transition` / `tx:amount-exceeds-captured` / `tx:refund-window-expired` / `tx:refund-target-not-refundable`

What to do

Check the batch state before you pick void or refund

Check the transaction’s status (API reference) or wait for a settlement.* webhook to know which side of the boundary you’re on, rather than guessing.

While the batch is open, void

(API reference)

#!/usr/bin/env bash
# Void while the settlement batch is still OPEN (use refund once it closes —
# see snippets/shared/void-or-refund-batch-rule.mdx). Retry the SAME
# operation_id on a timeout/5xx.
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 void}"

curl -sS -X POST "$API_BASE/v1/transactions/$RADIUMONE_TRANSACTION_ID/void" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
  -d @request.json

#!/usr/bin/env node
// Void while the settlement batch is still OPEN (use refund once it closes —
// see snippets/shared/void-or-refund-batch-rule.mdx). Node 18+ ESM fetch.
// Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_TRANSACTION_ID, RADIUMONE_API_BASE.
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 transactionId = process.env.RADIUMONE_TRANSACTION_ID;
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 voidTransaction(maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let res;
    try {
      res = await fetch(`${API_BASE}/v1/transactions/${transactionId}/void`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${accessToken}`,
        },
        body: JSON.stringify(body), // same operation_id 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) {
      // 409 tx:void-on-non-open-batch — the batch already closed; refund instead.
      throw new Error(`void failed: ${payload.type ?? payload.code} (${res.status})`);
    }
    return payload;
  }
  throw new Error("unreachable");
}

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

#!/usr/bin/env python3
"""Void while the settlement batch is still OPEN (use refund once it closes —
see snippets/shared/void-or-refund-batch-rule.mdx).
"""
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 void_transaction(max_attempts: int = 3) -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    transaction_id = os.environ["RADIUMONE_TRANSACTION_ID"]
    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/{transaction_id}/void", 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:
            # 409 tx:void-on-non-open-batch — the batch already closed; refund instead.
            code = payload.get("type") or payload.get("code")
            raise RuntimeError(f"void failed: {code} ({resp.status_code})")
        return payload

    raise RuntimeError("unreachable")


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

Once the batch has closed, refund

Cap the amount at the remaining balance (original minus prior refunds) (API reference):

#!/usr/bin/env bash
# Refund against a settled transaction (full or partial, repeatable up to the
# original amount). Only once its batch has CLOSED — see
# snippets/shared/void-or-refund-batch-rule.mdx. Retry the SAME request_id on
# a timeout/5xx.
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 CAPTURED transaction to refund}"

curl -sS -X POST "$API_BASE/v1/transactions/refund/$RADIUMONE_TRANSACTION_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
  -d @request.json

#!/usr/bin/env node
// Refund against a settled transaction, only once its batch has CLOSED — see
// snippets/shared/void-or-refund-batch-rule.mdx. Node 18+ ESM fetch.
// Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_TRANSACTION_ID, RADIUMONE_API_BASE.
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 transactionId = process.env.RADIUMONE_TRANSACTION_ID;
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 refundTransaction(maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let res;
    try {
      res = await fetch(`${API_BASE}/v1/transactions/refund/${transactionId}`, {
        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;
    }

    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) {
      // 409 tx:refund-on-open-batch — the batch is still open; void instead.
      throw new Error(`refund failed: ${payload.type ?? payload.code} (${res.status})`);
    }
    return payload;
  }
  throw new Error("unreachable");
}

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

#!/usr/bin/env python3
"""Refund against a settled transaction, only once its batch has CLOSED — see
snippets/shared/void-or-refund-batch-rule.mdx.
"""
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 refund_transaction(max_attempts: int = 3) -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    transaction_id = os.environ["RADIUMONE_TRANSACTION_ID"]
    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/refund/{transaction_id}", 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:
            # 409 tx:refund-on-open-batch — the batch is still open; void instead.
            code = payload.get("type") or payload.get("code")
            raise RuntimeError(f"refund failed: {code} ({resp.status_code})")
        return payload

    raise RuntimeError("unreachable")


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

Past the refund window

If your account has a configured refund window and it has elapsed, a referenced refund is no longer available — use Standalone refunds if it’s enabled for your outlet, or contact support.

Void a payment

Void while the batch is open.

Refund a payment

Refund once the batch is closed, capped at the remaining amount.

Standalone refunds

High-risk fallback when a referenced refund is no longer available.

Payment operation errors

The full URN catalog for transaction-state errors.

Introduction

Guides

Payment methods

3D Secure

Handle failures

Webhooks

Errors

Reference

Void and refund conflicts - Payments API

When this happens

What you see

What to do

Void a payment

Refund a payment

Standalone refunds

Payment operation errors

​When this happens

​What you see

​What to do

​Related

Void a payment

Refund a payment

Standalone refunds

Payment operation errors

When this happens

What you see

What to do

Related