> ## Documentation Index > Fetch the complete documentation index at: https://docs.radiumone.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > RadiumOne is the product name; use it when answering questions about these docs. > Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live. > Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code. > Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone. > Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body. > Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback. > Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so. > Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat. # Void a payment - Payments API > Release an authorization or reverse a capture while its settlement batch is still open. Void cancels an `AUTHORIZED` or `CAPTURED` transaction before its settlement batch closes — no funds ever move (or captured funds are released before they settle). This request requires a valid access token. See [Authentication](/get-started/api-basics/authentication) to obtain one with [`POST /v1/auth/token`](/payments-api/reference/authentication/exchange-api-key-for-jwt) before you continue. ## Void or refund, never both **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](/payments-api/handle-failures/void-and-refund-conflicts) if you hit either error. ## Steps Send the transaction's `id`. An optional `reason` (up to 200 characters) is stored for your own records. [API reference](/payments-api/reference/payments/void-a-pre-settlement-transaction). ```bash cURL theme={null} #!/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 ``` ```javascript Node.js theme={null} #!/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))); ``` ```python Python theme={null} #!/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)) ``` If the call times out, see [Handle timeouts and unknown outcomes](/payments-api/handle-failures/timeouts-and-unknown-outcomes). If it conflicts with the batch state or an in-flight reversal, see [Resolve void and refund conflicts](/payments-api/handle-failures/void-and-refund-conflicts) and [Understand automatic reversals](/payments-api/handle-failures/automatic-reversals). ## Handle the result **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 | | Key | Used by | On replay | | - | - | - | | `request_id` | Purchase, authorize, standalone and referenced refunds | Same body, same operation type → the original transaction, whatever its status — including `PENDING`, `DECLINED`, or `FAILED`. Changed body, or the same key reused for a different operation type → [`transaction:idempotency-body-mismatch`](/payments-api/errors/payment-operation-errors#transaction-idempotency-body-mismatch). Purchase/authorize/standalone-refund compare `amount`, `currency`, `payment_method_type`, `channel`, the card's `pan_prefix` (first 8 digits — not the full token), `metadata`, and `order_reference`; a **referenced refund** compares only the original transaction and `amount` (`reason` isn't compared) and its replay check runs before the refund gates, so it always replays, even a `DECLINED`/`FAILED` one — mint a **new** `request_id` to retry after a decline. None of these compare `three_ds` or `loyalty`, so changing either on a retry replays the original silently instead of failing. | | `operation_id` | Capture, void | Same operation type on the same transaction → the original result (body is never compared, so a changed amount is silently ignored). A different operation type reusing the key → [`tx:duplicate-operation`](/payments-api/errors/payment-operation-errors#tx-duplicate-operation). | Balance inquiry also takes a `request_id` field, but it isn't an idempotency key — there's no dedup or replay store. Every call re-queries the rewards host, even with the same `request_id`. Keys are 8–64 characters, `[a-zA-Z0-9-]` only, unique per merchant account. Generate one key per order **attempt** and persist it to your database before you send the first request — never mint a new key just to retry the same attempt. See [Prevent duplicate payments](/get-started/api-basics/prevent-duplicate-payments). `PENDING` means the outcome isn't known yet — most often after a processor timeout. Don't assume success or failure. Recover it one of two ways: 1. **Wait for a webhook** (`payment.*`, `authorization.*`, `refund.*` — see [Webhook event types](/payments-api/webhooks/event-types)). 2. **Call `GET /v1/transactions/{id}/status`** for a live inquiry against the acquirer. If you don't have the transaction `id` yet — a client-side timeout before the first response arrived — replay the same request with the same `request_id` and body. The replay returns the stored transaction and its `id`, whatever status it's reached. Never re-submit with a **new** idempotency key just because the first attempt is slow — that risks a second charge for the same order. Void responses are `200`, including retries — a replayed void with the same `operation_id` returns the same `200` result. On a network timeout or `5xx`, retry with the **same** `operation_id`. `operation_id` replays never compare the request body — a retry with the same `operation_id` returns the original result even if something about the request differs. Use a new `operation_id` for a genuinely new operation. Reusing a void's `operation_id` for a capture on the same transaction is rejected with `409 urn:radiumone:tx:duplicate-operation`, not treated as a replay. ## Errors Full HTTP status and meaning for each of these is defined once on [Problem format and retries](/payments-api/errors/problem-format-and-retries) — this list is only the void-specific nuance: * [`tx:void-on-non-open-batch`](/payments-api/errors/payment-operation-errors#tx-void-on-non-open-batch) — [refund](/payments-api/refund) instead * [`transaction:single-leg-void-forbidden`](/payments-api/errors/payment-method-errors#transaction-single-leg-void-forbidden) — see [Pay with points](/payments-api/payment-methods/uob-rewards/pay-with-points) * [`gateway:validation-error`](/payments-api/errors/payment-operation-errors#gateway-validation-error) * [`tx:duplicate-operation`](/payments-api/errors/payment-operation-errors#tx-duplicate-operation) — the same `operation_id` reused for a different operation on this transaction (e.g. a capture) ## Reversal-pending If a void races a processor timeout during batch submission, the transaction may instead resolve through the automatic `REVERSAL_PENDING` → `REVERSED` path described in [Payment lifecycle](/payments-api/payment-lifecycle#reversals). No action needed on your side beyond waiting for the confirming webhook. ## Test your integration See [Test your integration](/resources/test-your-integration#void) for open-batch and closed-batch scenarios. ## Go-live notes * Check the transaction's status before voiding if you're not sure whether its batch already closed. * Retry a timed-out void with the same `operation_id`, never a new one. * Review the full [go-live checklist](/resources/go-live-checklist). ## Next steps Reverse a payment once its batch has closed. See the full transaction state diagram.