#!/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 the docs page
# /payments-api/handle-failures/void-and-refund-conflicts. On no response or
# any 5xx (even retry_allowed: false), resend this exact request with the SAME
# request_id: the replay is a lookup that recovers the outcome, never a second
# refund.
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 python3
"""Refund against a settled transaction, only once its batch has CLOSED — 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
request_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 refund 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"
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, requests.exceptions.ConnectionError) as exc:
# No response: replay the same request_id (a lookup, never a second refund).
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-request_id replay recovers the outcome instead of refunding 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, void or refund on the original has no recorded outcome.
# Resend that request (its own key and body) first, then this one.
raise RuntimeError(f"resend the pending {payload.get('pending_operation')} {payload.get('pending_operation_id')} first")
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))
{
"status": "ok",
"request_id": "req_ord1001refnd1",
"data": {
"id": "7182930b-4c15-4d74-e081-920314253647",
"request_id": "ord-1001-refund-1",
"type": "REFUND",
"status": "CAPTURED",
"amount": 2000,
"currency": "SGD",
"currency_minor_units": 2,
"payment_method_type": "card",
"order_reference": "ORD-1001",
"response_code": "00",
"auth_code": "G7H8J9",
"rrn": "427311000301",
"parent_transaction_id": null,
"switch_request_id": "sw-ord-1001-refund-1",
"created_at": "2026-09-14T11:00:00.000Z",
"updated_at": "2026-09-14T11:00: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": "`urn:radiumone:payment-gateway:tx:refund-on-open-batch` (the original's batch is still open -- void instead), `urn:radiumone:payment-gateway:tx:invalid-state-transition` (the original has not moved money), `urn:radiumone:payment-gateway:routing:operation-disabled` (refund is switched off on the original's terminal; `resolution: operator`), or `urn:radiumone:payment-gateway:transaction:duplicate-body-mismatch` (`request_id` already names a different refund), or `urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt` (an earlier capture, void or refund on the original has no recorded outcome -- resend it first; `pending_operation_id` names it).",
"status": 409,
"title": "Conflict",
"type": "urn:radiumone:payment-gateway:tx:refund-on-open-batch"
}{
"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:tx:amount-exceeds-captured`, `urn:radiumone:payment-gateway:tx:currency-mismatch`, `urn:radiumone:payment-gateway:tx:refund-window-expired`, `urn:radiumone:payment-gateway:tx:refund-target-not-refundable`, `urn:radiumone:payment-gateway:transaction:product-not-supported` (the target is a loyalty redemption -- refund the card payment), or `urn:radiumone:payment-gateway:routing:capability-not-supported`. A retry does not help.",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:tx:amount-exceeds-captured"
}{
"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"
}Refund - Payments API
Refund all or part of a settled transaction. Each refund is a new transaction that you can void or reverse, and you can repeat it up to the allowed amount.
#!/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 the docs page
# /payments-api/handle-failures/void-and-refund-conflicts. On no response or
# any 5xx (even retry_allowed: false), resend this exact request with the SAME
# request_id: the replay is a lookup that recovers the outcome, never a second
# refund.
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 python3
"""Refund against a settled transaction, only once its batch has CLOSED — 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
request_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 refund 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"
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, requests.exceptions.ConnectionError) as exc:
# No response: replay the same request_id (a lookup, never a second refund).
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-request_id replay recovers the outcome instead of refunding 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, void or refund on the original has no recorded outcome.
# Resend that request (its own key and body) first, then this one.
raise RuntimeError(f"resend the pending {payload.get('pending_operation')} {payload.get('pending_operation_id')} first")
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))
{
"status": "ok",
"request_id": "req_ord1001refnd1",
"data": {
"id": "7182930b-4c15-4d74-e081-920314253647",
"request_id": "ord-1001-refund-1",
"type": "REFUND",
"status": "CAPTURED",
"amount": 2000,
"currency": "SGD",
"currency_minor_units": 2,
"payment_method_type": "card",
"order_reference": "ORD-1001",
"response_code": "00",
"auth_code": "G7H8J9",
"rrn": "427311000301",
"parent_transaction_id": null,
"switch_request_id": "sw-ord-1001-refund-1",
"created_at": "2026-09-14T11:00:00.000Z",
"updated_at": "2026-09-14T11:00: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": "`urn:radiumone:payment-gateway:tx:refund-on-open-batch` (the original's batch is still open -- void instead), `urn:radiumone:payment-gateway:tx:invalid-state-transition` (the original has not moved money), `urn:radiumone:payment-gateway:routing:operation-disabled` (refund is switched off on the original's terminal; `resolution: operator`), or `urn:radiumone:payment-gateway:transaction:duplicate-body-mismatch` (`request_id` already names a different refund), or `urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt` (an earlier capture, void or refund on the original has no recorded outcome -- resend it first; `pending_operation_id` names it).",
"status": 409,
"title": "Conflict",
"type": "urn:radiumone:payment-gateway:tx:refund-on-open-batch"
}{
"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:tx:amount-exceeds-captured`, `urn:radiumone:payment-gateway:tx:currency-mismatch`, `urn:radiumone:payment-gateway:tx:refund-window-expired`, `urn:radiumone:payment-gateway:tx:refund-target-not-refundable`, `urn:radiumone:payment-gateway:transaction:product-not-supported` (the target is a loyalty redemption -- refund the card payment), or `urn:radiumone:payment-gateway:routing:capability-not-supported`. A retry does not help.",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:tx:amount-exceeds-captured"
}{
"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
Body
Refund a transaction whose settlement batch has closed.
While the batch is still open, void the transaction instead. The refund is created
as its own transaction, so it carries a request_id idempotency key, just like a
sale, rather than an operation_id.
You don't send card details: the refund goes back to the card used on the original 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.