#!/usr/bin/env bash
# Void while the settlement batch is still OPEN (use refund once it closes —
# see /payments-api/handle-failures/void-and-refund-conflicts in the docs). On no response
# or any 5xx (even retry_allowed: false), resend this exact request with the
# SAME operation_id: the replay is a lookup that recovers the outcome, never a
# second void. A 409 transaction:void-reversal-pending (retry_allowed: true)
# means an earlier void that timed out is still being reversed: retry later.
# A 409 tx:invalid-state-transition means the transaction isn't CAPTURED -- an
# uncaptured authorization can't be voided; it lapses when its capture window ends.
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 python3
"""Void while the settlement batch is still OPEN (use refund once it closes —
see /payments-api/handle-failures/void-and-refund-conflicts in the docs).
On no response or any 5xx -- even retry_allowed: false -- replay the SAME
operation_id with the identical body. The replay is a lookup, not a resend:
RadiumOne returns the recorded outcome, or asks the card network for the stored
one, and only sends the void if the network never received it.
"""
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")
OUTCOME_IN_DOUBT = "urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt"
VOID_REVERSAL_PENDING = "urn:radiumone:payment-gateway:transaction:void-reversal-pending"
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, requests.exceptions.ConnectionError) as exc:
# No response: replay the same operation_id (a lookup, never a second void).
if attempt == max_attempts:
raise RuntimeError(f"no response after {attempt} attempts -- wait for the webhook") from exc
time.sleep(backoff_seconds(attempt))
continue
if resp.status_code >= 500:
try:
problem = resp.json()
except ValueError:
problem = {}
# Any 5xx -- even retry_allowed: false (switch-timeout, database-unavailable):
# the same-operation_id replay recovers the outcome instead of voiding again.
if attempt == max_attempts:
raise RuntimeError(
f"{problem.get('type') or 'server error'} ({resp.status_code}) after {attempt} attempts -- wait for the webhook"
)
time.sleep(backoff_seconds(attempt))
continue
payload = resp.json()
if resp.status_code == 409 and payload.get("type") == OUTCOME_IN_DOUBT:
# An earlier capture or void on this transaction has no recorded outcome.
# Resend that request (its own operation_id and body) first, then this one.
raise RuntimeError(f"resend the pending {payload.get('pending_operation')} {payload.get('pending_operation_id')} first")
if resp.status_code == 409 and payload.get("type") == VOID_REVERSAL_PENDING:
# retry_allowed: true -- an earlier void (e.g. one that timed out) is still being
# reversed. Retry this same operation_id later; once the reversal clears it's sent
# as a new attempt (or returns the void RadiumOne already sent again).
raise RuntimeError(f"earlier void still being reversed -- retry later (retry_after: {payload.get('retry_after')}s)")
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))
{
"status": "ok",
"request_id": "req_ord1002void1",
"data": {
"id": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081",
"request_id": "ord-1002-auth-1",
"type": "AUTHORIZE",
"status": "VOIDED",
"amount": 10000,
"currency": "SGD",
"currency_minor_units": 2,
"payment_method_type": "card",
"order_reference": "ORD-1002",
"response_code": "00",
"auth_code": "D4E5F6",
"rrn": "427310000201",
"parent_transaction_id": null,
"switch_request_id": "sw-ord-1002-void-1",
"created_at": "2026-09-14T10:00:00.000Z",
"updated_at": "2026-09-14T10:06:01.000Z"
}
}{
"detail": "Request payload failed validation.",
"status": 400,
"title": "Validation Error",
"type": "urn:radiumone:payment-gateway:validation-error"
}{
"detail": "Missing or invalid Bearer token.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}{
"detail": "Insufficient permissions for this operation.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:permission-denied"
}{
"detail": "The requested resource does not exist.",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:not-found"
}{
"detail": "The transaction's terminal cannot take the operation: `urn:radiumone:payment-gateway:settlement:device-settling` (its batch is settling; `retry_allowed: true`, `resolution: transient`), `urn:radiumone:payment-gateway:settlement:device-batch-rejected` or `urn:radiumone:payment-gateway:settlement:stuck-reversals` (`resolution: operator`), or `urn:radiumone:payment-gateway:routing:operation-disabled` (the operation is switched off on the terminal; `resolution: operator`). Also `urn:radiumone:payment-gateway:tx:invalid-state-transition` (the transaction is not in a state that allows the operation), `urn:radiumone:payment-gateway:tx:duplicate-operation` (`operation_id` was already used for a different operation on this transaction) and `urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt` (an earlier capture or void on this transaction has no recorded outcome -- resend it with its own `operation_id` first; `pending_operation_id` names it). For a void, `tx:invalid-state-transition` means the transaction is not CAPTURED -- e.g. an uncaptured authorization hold, which cannot be voided and is released when its capture window expires. Also `urn:radiumone:payment-gateway:tx:void-on-non-open-batch` (the batch is already settling or settled -- refund instead), `urn:radiumone:payment-gateway:transaction:void-reversal-pending` (an earlier void is still being reversed; `retry_allowed: true`, `resolution: transient`), `urn:radiumone:payment-gateway:transaction:single-leg-void-forbidden` (the transaction is one part of a combined sale), or `urn:radiumone:payment-gateway:transaction:group-inconsistent-precondition`.",
"status": 409,
"title": "Conflict",
"type": "urn:radiumone:payment-gateway:settlement:device-settling"
}{
"detail": "The payment token has expired or its card data is no longer available.",
"status": 410,
"title": "Gone",
"type": "urn:radiumone:payment-gateway:token:data-purged"
}{
"detail": "`urn:radiumone:payment-gateway:routing:capability-not-supported` (the acquirer does not support void on this channel), or the card token of a loyalty redemption has lapsed (see the error catalog). A retry does not help.",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:routing:capability-not-supported"
}{
"detail": "An unexpected error occurred.",
"status": 500,
"title": "Internal Server Error",
"type": "urn:radiumone:payment-gateway:internal-error"
}{
"detail": "A downstream dependency is unavailable or did not respond in time. `urn:radiumone:payment-gateway:service-unavailable` carries `retry_allowed` true when the failure came before any work (signing keys unavailable, service starting). `urn:radiumone:payment-gateway:request-deadline-exceeded` carries `retry_allowed` true only for GET/HEAD/OPTIONS -- a mutating request may have reached a host. Also `urn:radiumone:payment-gateway:routing:original-acquirer-unavailable`: the acquirer that processed the original transaction is temporarily unavailable; nothing was sent.",
"status": 503,
"title": "Service Unavailable",
"type": "urn:radiumone:payment-gateway:service-unavailable"
}Void - Payments API
Cancel a captured transaction before it settles; an uncaptured authorization can’t be voided. Once the transaction is in a settled batch, refund it instead.
#!/usr/bin/env bash
# Void while the settlement batch is still OPEN (use refund once it closes —
# see /payments-api/handle-failures/void-and-refund-conflicts in the docs). On no response
# or any 5xx (even retry_allowed: false), resend this exact request with the
# SAME operation_id: the replay is a lookup that recovers the outcome, never a
# second void. A 409 transaction:void-reversal-pending (retry_allowed: true)
# means an earlier void that timed out is still being reversed: retry later.
# A 409 tx:invalid-state-transition means the transaction isn't CAPTURED -- an
# uncaptured authorization can't be voided; it lapses when its capture window ends.
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 python3
"""Void while the settlement batch is still OPEN (use refund once it closes —
see /payments-api/handle-failures/void-and-refund-conflicts in the docs).
On no response or any 5xx -- even retry_allowed: false -- replay the SAME
operation_id with the identical body. The replay is a lookup, not a resend:
RadiumOne returns the recorded outcome, or asks the card network for the stored
one, and only sends the void if the network never received it.
"""
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")
OUTCOME_IN_DOUBT = "urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt"
VOID_REVERSAL_PENDING = "urn:radiumone:payment-gateway:transaction:void-reversal-pending"
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, requests.exceptions.ConnectionError) as exc:
# No response: replay the same operation_id (a lookup, never a second void).
if attempt == max_attempts:
raise RuntimeError(f"no response after {attempt} attempts -- wait for the webhook") from exc
time.sleep(backoff_seconds(attempt))
continue
if resp.status_code >= 500:
try:
problem = resp.json()
except ValueError:
problem = {}
# Any 5xx -- even retry_allowed: false (switch-timeout, database-unavailable):
# the same-operation_id replay recovers the outcome instead of voiding again.
if attempt == max_attempts:
raise RuntimeError(
f"{problem.get('type') or 'server error'} ({resp.status_code}) after {attempt} attempts -- wait for the webhook"
)
time.sleep(backoff_seconds(attempt))
continue
payload = resp.json()
if resp.status_code == 409 and payload.get("type") == OUTCOME_IN_DOUBT:
# An earlier capture or void on this transaction has no recorded outcome.
# Resend that request (its own operation_id and body) first, then this one.
raise RuntimeError(f"resend the pending {payload.get('pending_operation')} {payload.get('pending_operation_id')} first")
if resp.status_code == 409 and payload.get("type") == VOID_REVERSAL_PENDING:
# retry_allowed: true -- an earlier void (e.g. one that timed out) is still being
# reversed. Retry this same operation_id later; once the reversal clears it's sent
# as a new attempt (or returns the void RadiumOne already sent again).
raise RuntimeError(f"earlier void still being reversed -- retry later (retry_after: {payload.get('retry_after')}s)")
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))
{
"status": "ok",
"request_id": "req_ord1002void1",
"data": {
"id": "1b2c3d4e-5f60-4718-9a2b-3c4d5e6f7081",
"request_id": "ord-1002-auth-1",
"type": "AUTHORIZE",
"status": "VOIDED",
"amount": 10000,
"currency": "SGD",
"currency_minor_units": 2,
"payment_method_type": "card",
"order_reference": "ORD-1002",
"response_code": "00",
"auth_code": "D4E5F6",
"rrn": "427310000201",
"parent_transaction_id": null,
"switch_request_id": "sw-ord-1002-void-1",
"created_at": "2026-09-14T10:00:00.000Z",
"updated_at": "2026-09-14T10:06:01.000Z"
}
}{
"detail": "Request payload failed validation.",
"status": 400,
"title": "Validation Error",
"type": "urn:radiumone:payment-gateway:validation-error"
}{
"detail": "Missing or invalid Bearer token.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}{
"detail": "Insufficient permissions for this operation.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:permission-denied"
}{
"detail": "The requested resource does not exist.",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:not-found"
}{
"detail": "The transaction's terminal cannot take the operation: `urn:radiumone:payment-gateway:settlement:device-settling` (its batch is settling; `retry_allowed: true`, `resolution: transient`), `urn:radiumone:payment-gateway:settlement:device-batch-rejected` or `urn:radiumone:payment-gateway:settlement:stuck-reversals` (`resolution: operator`), or `urn:radiumone:payment-gateway:routing:operation-disabled` (the operation is switched off on the terminal; `resolution: operator`). Also `urn:radiumone:payment-gateway:tx:invalid-state-transition` (the transaction is not in a state that allows the operation), `urn:radiumone:payment-gateway:tx:duplicate-operation` (`operation_id` was already used for a different operation on this transaction) and `urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt` (an earlier capture or void on this transaction has no recorded outcome -- resend it with its own `operation_id` first; `pending_operation_id` names it). For a void, `tx:invalid-state-transition` means the transaction is not CAPTURED -- e.g. an uncaptured authorization hold, which cannot be voided and is released when its capture window expires. Also `urn:radiumone:payment-gateway:tx:void-on-non-open-batch` (the batch is already settling or settled -- refund instead), `urn:radiumone:payment-gateway:transaction:void-reversal-pending` (an earlier void is still being reversed; `retry_allowed: true`, `resolution: transient`), `urn:radiumone:payment-gateway:transaction:single-leg-void-forbidden` (the transaction is one part of a combined sale), or `urn:radiumone:payment-gateway:transaction:group-inconsistent-precondition`.",
"status": 409,
"title": "Conflict",
"type": "urn:radiumone:payment-gateway:settlement:device-settling"
}{
"detail": "The payment token has expired or its card data is no longer available.",
"status": 410,
"title": "Gone",
"type": "urn:radiumone:payment-gateway:token:data-purged"
}{
"detail": "`urn:radiumone:payment-gateway:routing:capability-not-supported` (the acquirer does not support void on this channel), or the card token of a loyalty redemption has lapsed (see the error catalog). A retry does not help.",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:routing:capability-not-supported"
}{
"detail": "An unexpected error occurred.",
"status": 500,
"title": "Internal Server Error",
"type": "urn:radiumone:payment-gateway:internal-error"
}{
"detail": "A downstream dependency is unavailable or did not respond in time. `urn:radiumone:payment-gateway:service-unavailable` carries `retry_allowed` true when the failure came before any work (signing keys unavailable, service starting). `urn:radiumone:payment-gateway:request-deadline-exceeded` carries `retry_allowed` true only for GET/HEAD/OPTIONS -- a mutating request may have reached a host. Also `urn:radiumone:payment-gateway:routing:original-acquirer-unavailable`: the acquirer that processed the original transaction is temporarily unavailable; nothing was sent.",
"status": 503,
"title": "Service Unavailable",
"type": "urn:radiumone:payment-gateway:service-unavailable"
}Authorizations
Path Parameters
Body
Request body for POST /v1/transactions/{id}/void.
Cancels a CAPTURED transaction (a sale, a captured authorization or a refund) before its settlement batch closes. An uncaptured authorization hold cannot be voided. Idempotent via operation_id scoped to the parent transaction.
Response
Successful Response
Standard success envelope. Every successful response has this shape, with the operation's own payload under data.
Correlation ID for this HTTP request, for logs and support. Send your own in the X-Request-Id header (letters, digits and hyphens, up to 36 characters -- other characters are stripped) or the gateway generates one. This is NOT the request_id idempotency key you send in a transaction body; the two are unrelated.