#!/usr/bin/env bash
# High-risk. Standalone ("open") refund — credits a card with NO original
# RadiumOne transaction bounding the amount. Requires the
# transaction-refund-unreferenced scope PLUS acquirer/terminal enablement
# (see resources/support#request-enablement). Least-privilege keys only.
# On a timeout/5xx, retry with the SAME request_id -- even after a 5xx with
# retry_allowed: false, a same-request_id replay is a lookup that never sends
# the refund again.
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 with the transaction-refund-unreferenced scope}"
curl -sS -X POST "$API_BASE/v1/transactions/refund" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json
#!/usr/bin/env python3
"""High-risk. Standalone ("open") refund — credits a card with NO original
RadiumOne transaction bounding the amount. Requires the
transaction-refund-unreferenced scope PLUS acquirer/terminal enablement (see
resources/support#request-enablement). Least-privilege keys only.
On a network timeout or any 5xx, replay the SAME request_id. RadiumOne saves a
standalone refund before it sends it, so a same-request_id replay is a lookup
that never sends the refund again -- safe even after a 5xx that says
``retry_allowed: false``. (A referenced refund replays the same way.)
"""
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_standalone_refund(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/refund", json=body, headers=headers, timeout=30)
except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
if attempt == max_attempts:
raise
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):
# replaying the SAME request_id is a lookup, not a resend, so it never
# sends the refund again. Out of attempts? Wait for the webhook.
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 # replay the same request_id (a lookup, never a second refund)
payload = resp.json()
if not resp.ok:
# 403 auth:insufficient-scope, or a routing 409/422 if not yet enabled.
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"open refund failed: {code} ({resp.status_code})")
return payload
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(create_standalone_refund(), indent=2))
{
"detail": "Missing or invalid Bearer token, or `urn:radiumone:payment-gateway:authentication-required` because your merchant account is not active (suspended, disabled or deleted). Checked on every request, not only when the token is issued.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}
{
"detail": "Insufficient permissions for this operation; `urn:radiumone:payment-gateway:auth:outlet-binding-violation`: the request's `outlet_id` names a different outlet than the one your API key is bound to; or `urn:radiumone:payment-gateway:merchant:outlet-disabled` (`retry_allowed: false`): the outlet -- the one named, the one your key is bound to, or your DEFAULT outlet -- is disabled. Re-enabling the outlet restores service; the key is not revoked.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:auth:outlet-binding-violation"
}
{
"detail": "The requested resource does not exist, or `urn:radiumone:payment-gateway:checkout:outlet-not-found`: the outlet (named, key-bound, or your DEFAULT outlet) does not exist for your account. One answer on every surface (was 400 `payment-gateway:validation-error` on transactions).",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:checkout:outlet-not-found"
}
{
"detail": "The terminal-unavailable family (`device-settling`, `device-busy` (a usable terminal is locked by a concurrent operation; `retry_allowed: true`, retry with the same `request_id`), `device-batch-rejected`, `terminal-inactive`, `operation-disabled`, `no-device-available`, `device-unpaired`, `payment-gateway:loyalty:device-not-validated`, `raw-card-not-permitted` (the request sent `card.pan` and no terminal that could serve it is enabled for raw card data -- send a payment token, or ask RadiumOne to enable it; `retry_allowed: false`); each with a `resolution` member), `payment-gateway:transaction:void-reversal-pending`, or an idempotency conflict. A sale that redeems loyalty value is refused with the loyalty terminal's own 409 BEFORE the card is charged. Also `urn:radiumone:payment-gateway:routing:channel-disabled` (`retry_allowed: false`): the outlet's channel for this request is disabled.",
"status": 409,
"title": "Conflict",
"type": "urn:radiumone:payment-gateway:routing:channel-disabled"
}
{
"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": "The request cannot be processed as sent. On a sale that redeems loyalty value, checked before anything is charged: `urn:radiumone:payment-gateway:transaction:loyalty-leg-required` (no loyalty program can serve the redemption for this outlet, channel and currency) or `urn:radiumone:payment-gateway:routing:capability-not-supported` (the loyalty program does not accept the redemption on this channel). Both are configuration outcomes: a retry does not help. The routing refusals `urn:radiumone:payment-gateway:routing:rule-rejected` and `urn:radiumone:payment-gateway:routing:no-rule-match` carry `reason` (`card`: this card cannot be used here, another may be; `transaction`: the request cannot be routed whatever the card) and `retry_allowed: false`. Currency: `urn:radiumone:payment-gateway:currency:unknown-currency` (the currency is well-formed but not an active ISO 4217 currency -- an unknown, fund, N.A. or withdrawn code; `errors[]` names the field, `retry_allowed: false`) or `urn:radiumone:payment-gateway:currency:minor-units-not-supported` (a valid ISO 4217 currency whose minor units are not 2, e.g. JPY or KWD -- only 2-decimal currencies are supported; `retry_allowed: false`).",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:transaction:loyalty-leg-required"
}
{
"detail": "A downstream dependency is unavailable or did not respond in time -- the `retry_allowed` extension says whether a retry is safe. Also `urn:radiumone:payment-gateway:routing:no-device` (no usable terminal when the transaction was attempted; `resolution: operator`, `retry_allowed: false`), `urn:radiumone:payment-gateway:routing:device-resolution-failed` (a gateway fault while selecting a terminal; `retry_allowed: false`), `urn:radiumone:payment-gateway:routing:acquirer-circuit-open` (every acquirer that could serve the request is temporarily unavailable; `retry_allowed: true`, `resolution: transient`), and -- on a sale that redeems loyalty value -- `urn:radiumone:payment-gateway:routing:loyalty-mode-unavailable` (the loyalty program could not be resolved; `retry_allowed: true`, `resolution: transient`). Nothing was charged or redeemed for any of them. `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.",
"status": 503,
"title": "Service Unavailable",
"type": "urn:radiumone:payment-gateway:routing:no-device"
}
Create standalone refund - Payments API
Send money back to a card with no original transaction to bound it. High-risk — requires enablement and a narrowly-scoped key.
POST
/
v1
/
transactions
/
refund
cURL
#!/usr/bin/env bash
# High-risk. Standalone ("open") refund — credits a card with NO original
# RadiumOne transaction bounding the amount. Requires the
# transaction-refund-unreferenced scope PLUS acquirer/terminal enablement
# (see resources/support#request-enablement). Least-privilege keys only.
# On a timeout/5xx, retry with the SAME request_id -- even after a 5xx with
# retry_allowed: false, a same-request_id replay is a lookup that never sends
# the refund again.
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 with the transaction-refund-unreferenced scope}"
curl -sS -X POST "$API_BASE/v1/transactions/refund" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json
#!/usr/bin/env python3
"""High-risk. Standalone ("open") refund — credits a card with NO original
RadiumOne transaction bounding the amount. Requires the
transaction-refund-unreferenced scope PLUS acquirer/terminal enablement (see
resources/support#request-enablement). Least-privilege keys only.
On a network timeout or any 5xx, replay the SAME request_id. RadiumOne saves a
standalone refund before it sends it, so a same-request_id replay is a lookup
that never sends the refund again -- safe even after a 5xx that says
``retry_allowed: false``. (A referenced refund replays the same way.)
"""
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_standalone_refund(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/refund", json=body, headers=headers, timeout=30)
except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
if attempt == max_attempts:
raise
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):
# replaying the SAME request_id is a lookup, not a resend, so it never
# sends the refund again. Out of attempts? Wait for the webhook.
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 # replay the same request_id (a lookup, never a second refund)
payload = resp.json()
if not resp.ok:
# 403 auth:insufficient-scope, or a routing 409/422 if not yet enabled.
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"open refund failed: {code} ({resp.status_code})")
return payload
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(create_standalone_refund(), indent=2))
{
"detail": "Missing or invalid Bearer token, or `urn:radiumone:payment-gateway:authentication-required` because your merchant account is not active (suspended, disabled or deleted). Checked on every request, not only when the token is issued.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}
{
"detail": "Insufficient permissions for this operation; `urn:radiumone:payment-gateway:auth:outlet-binding-violation`: the request's `outlet_id` names a different outlet than the one your API key is bound to; or `urn:radiumone:payment-gateway:merchant:outlet-disabled` (`retry_allowed: false`): the outlet -- the one named, the one your key is bound to, or your DEFAULT outlet -- is disabled. Re-enabling the outlet restores service; the key is not revoked.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:auth:outlet-binding-violation"
}
{
"detail": "The requested resource does not exist, or `urn:radiumone:payment-gateway:checkout:outlet-not-found`: the outlet (named, key-bound, or your DEFAULT outlet) does not exist for your account. One answer on every surface (was 400 `payment-gateway:validation-error` on transactions).",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:checkout:outlet-not-found"
}
{
"detail": "The terminal-unavailable family (`device-settling`, `device-busy` (a usable terminal is locked by a concurrent operation; `retry_allowed: true`, retry with the same `request_id`), `device-batch-rejected`, `terminal-inactive`, `operation-disabled`, `no-device-available`, `device-unpaired`, `payment-gateway:loyalty:device-not-validated`, `raw-card-not-permitted` (the request sent `card.pan` and no terminal that could serve it is enabled for raw card data -- send a payment token, or ask RadiumOne to enable it; `retry_allowed: false`); each with a `resolution` member), `payment-gateway:transaction:void-reversal-pending`, or an idempotency conflict. A sale that redeems loyalty value is refused with the loyalty terminal's own 409 BEFORE the card is charged. Also `urn:radiumone:payment-gateway:routing:channel-disabled` (`retry_allowed: false`): the outlet's channel for this request is disabled.",
"status": 409,
"title": "Conflict",
"type": "urn:radiumone:payment-gateway:routing:channel-disabled"
}
{
"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": "The request cannot be processed as sent. On a sale that redeems loyalty value, checked before anything is charged: `urn:radiumone:payment-gateway:transaction:loyalty-leg-required` (no loyalty program can serve the redemption for this outlet, channel and currency) or `urn:radiumone:payment-gateway:routing:capability-not-supported` (the loyalty program does not accept the redemption on this channel). Both are configuration outcomes: a retry does not help. The routing refusals `urn:radiumone:payment-gateway:routing:rule-rejected` and `urn:radiumone:payment-gateway:routing:no-rule-match` carry `reason` (`card`: this card cannot be used here, another may be; `transaction`: the request cannot be routed whatever the card) and `retry_allowed: false`. Currency: `urn:radiumone:payment-gateway:currency:unknown-currency` (the currency is well-formed but not an active ISO 4217 currency -- an unknown, fund, N.A. or withdrawn code; `errors[]` names the field, `retry_allowed: false`) or `urn:radiumone:payment-gateway:currency:minor-units-not-supported` (a valid ISO 4217 currency whose minor units are not 2, e.g. JPY or KWD -- only 2-decimal currencies are supported; `retry_allowed: false`).",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:transaction:loyalty-leg-required"
}
{
"detail": "A downstream dependency is unavailable or did not respond in time -- the `retry_allowed` extension says whether a retry is safe. Also `urn:radiumone:payment-gateway:routing:no-device` (no usable terminal when the transaction was attempted; `resolution: operator`, `retry_allowed: false`), `urn:radiumone:payment-gateway:routing:device-resolution-failed` (a gateway fault while selecting a terminal; `retry_allowed: false`), `urn:radiumone:payment-gateway:routing:acquirer-circuit-open` (every acquirer that could serve the request is temporarily unavailable; `retry_allowed: true`, `resolution: transient`), and -- on a sale that redeems loyalty value -- `urn:radiumone:payment-gateway:routing:loyalty-mode-unavailable` (the loyalty program could not be resolved; `retry_allowed: true`, `resolution: transient`). Nothing was charged or redeemed for any of them. `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.",
"status": 503,
"title": "Service Unavailable",
"type": "urn:radiumone:payment-gateway:routing:no-device"
}
This feature is in Beta. Behavior may change before general availability, and production access depends on your RadiumOne rollout. Contact support to confirm availability for your account.
A standalone (open, unreferenced) refund sends money to a card with no
original transaction to bound it — no amount cap, no time window, and no
card-token matching against a prior sale. It’s the right tool for a
goodwill credit or a refund whose original transaction lives outside
RadiumOne, but it also means a mistaken or compromised call can send an
arbitrary amount to an arbitrary card.
This is a high-risk operation. It’s disabled by default: it requires the
separate transaction-refund-unreferenced scope on your access token
(not included by default on a narrowly-scoped secret key, though it is
included in a secret key’s full default scope set — see
Authentication),
and the terminal/acquirer must explicitly support it.
This is a high-risk operation. Follow these practices:
Least privilege: request a secret key scoped to only the operations it needs, not a key with every scope.
Key storage: store secret keys in a server-side secrets manager, never in client code, source control, or logs.
Emergency revocation: if a key is compromised, rotate or revoke it immediately — see Emergency key revocation.
Monitoring: monitor refunds and settlements for unexpected activity and alert on anomalies.
When to use a referenced refund instead
If the original charge exists in RadiumOne, use
POST /v1/transactions/refund/{transaction_id}
instead — it derives the card from the original transaction and enforces an
amount cap, which closes off most of the risk above.
Request
Same shape as a purchase, minus 3DS and loyalty fields: request_id
(idempotency key), amount, card, channel, plus optional
order_reference, reason, metadata, and outlet_id. Omit outlet_id
to use your API key’s outlet, or your default outlet if the key isn’t bound
to one; a key bound to a different outlet gets 403urn:radiumone:payment-gateway:auth:outlet-binding-violation.
outlet_id is part of the idempotency key only when you send it.
Idempotency
Idempotent on request_id, with the same replay semantics as every other
create-type operation — see
Request conventions.
Access token from POST /v1/auth/token, sent as Authorization: Bearer <token>. Treat it as opaque.
Body
application/json
Request body for POST /v1/transactions/refund -- credit a card with no original sale.
Use this to credit a card when there is no earlier transaction to refund against.
It is shaped like a sale and is routed and settled the same way, only in the
opposite direction. Because it is not tied to an original transaction there is no
amount limit, no time window and no card check, so the ability to send one must be
enabled for your account, your acquirer and the device -- all of which are off by
default.
amount
MoneyAmount · object
required
Refund amount as a {currency, value} money object.
Show child attributes
card
PaymentCard · object
required
The card to credit. The card: its payment token (preferred), or pan + expiry (+ cvv) when the terminal is enabled for raw card data. Send exactly one of the two forms. Required: with no original to derive the card from, the caller must name it.
Transaction channel -- the source or manner of the payment, used to route the refund. The acquirer must have standalone refunds enabled on this channel.
Available options:
CARD_PRESENT,
ECOMMERCE,
MOTO,
PAYMENT_LINK,
IN_APP,
RECURRING
request_id
string
required
Merchant idempotency key for the refund transaction.
Required string length: 8 - 64
metadata
Metadata · object | null
Optional merchant-supplied metadata (max 10 KB, max 5 depth levels).
order_reference
string | null
Merchant's own reference for this credit. Stored, searchable, and forwarded to the acquirer for reconciliation. Acquirers impose their own limits and character rules (commonly 20 characters, alphanumeric) and will shorten the value to fit, so prefer short references using letters, digits, '-', '.' and '_', and put the varying part LAST -- values are shortened from the front.
Maximum string length: 128
outlet_id
string<uuid> | null
Outlet to transact on. Omit it to use the outlet your API key is bound to, or your DEFAULT outlet when the key is not bound. Sending the outlet your checkout session was created for makes the sale route exactly as that session's payment methods were discovered. A key bound to a different outlet is refused with 403 urn:radiumone:payment-gateway:auth:outlet-binding-violation. Part of the idempotency key only when sent: a retry of the same request_id naming a different outlet is refused with 409.
reason
string | null
Optional human-readable reason for the refund.
Maximum string length: 200
Response
Successful Response
Standard success envelope. Every successful response has this shape, with the operation's own payload under data.
data
TransactionResponse · object | null
The operation's result. Its shape is documented per operation; omitted on responses that carry no payload.
Show child attributes
message
string | null
Optional human-readable note. Omitted from the response when not set, which is the case for every payment operation today. Never parse it.
request_id
string | null
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.
status
string
default:ok
Always ok on a successful (2xx) response. Errors use a different body shape entirely (RFC 9457 problem details), so branch on the HTTP status code, not on this field.