Skip to main content
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 (or “open”) refund credits a card with no original RadiumOne transaction to bound the amount, the card, or the timing — you supply the card token and amount directly. It’s the escape hatch for refunding an order that was never paid for through RadiumOne (a legacy order, a goodwill credit, a chargeback pre-emption), not the normal refund path.
This is a high-risk operation. Because there’s no original transaction, RadiumOne can’t cap the amount, enforce a time window, or confirm the refund matches the card that was originally charged. Every secret key holds the transaction-refund-unreferenced scope by default — the scope itself isn’t what protects you, the acquirer channel/device enablement gate is. Once enabled, anyone holding that key can credit any card token for any amount, at any time. Prefer Refund a payment whenever an original transaction exists.
This request requires a valid access token. See Authentication to obtain one with POST /v1/auth/token before you continue.
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.

Request fields

Same shape as a purchase: request_id, amount, card, channel, plus optional order_reference (up to 128 characters) and reason (up to 200 characters) for your own records, and an optional outlet_id. Standalone refunds don’t take selected_payment_method. card works as on a purchase: send the card token (preferred). Card details (pan, expiry as YYMM, optional cvv; never with token) are accepted only on terminals RadiumOne has enabled for raw card data — otherwise the refund is refused with 409 urn:radiumone:payment-gateway:routing:raw-card-not-permitted and nothing is sent. If you send card details, PCI DSS applies to you, because cardholder data passes through your systems. See Send card details instead of a token. outlet_id works as on a purchase: omit it 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 403 urn:radiumone:payment-gateway:auth:outlet-binding-violation. It’s part of the idempotency key only when you send it. See Choose the outlet.
Amounts are always integers in the currency’s minor units. For example, 5000 for SGD means SGD 50.00. Only currencies with 2 minor units are accepted today — read each currency’s minor units from the API rather than from your own table. See Currencies and amounts.

Steps

1

Issue the refund

Use a secret key scoped to transaction-refund-unreferenced. The outlet must also be enabled for standalone refunds at the acquirer/terminal level. API reference.
If the operation isn’t enabled for your outlet, see Fix operations unavailable for your outlet.

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).
After a timeout or a 5xx, replay with the same key. For every payment operation — purchase, authorize, capture, void, and both refunds — a replay of the identical request with the same request_id or operation_id is a lookup, not a resend, so it’s safe even after a 5xx that says retry_allowed: false (switch-timeout, database-unavailable). RadiumOne returns the outcome it recorded. If a capture, void, or referenced refund was sent but its outcome wasn’t recorded, RadiumOne asks the card network for the stored outcome instead of sending it again, and sends it only if the network never received it — so nothing is applied twice. A replay can return PENDING or REVERSAL_PENDING until the outcome settles. A request RadiumOne refused before it reached the card network (for example with device-settling or device-busy) is run again on the same transaction instead of returning a stored result — no second transaction is created. A capture that timed out after it may have reached the card network is reversed — the capture, never the authorization under it: while that reversal is open (REVERSAL_PENDING), a same-operation_id retry gets 409 tx:invalid-state-transition; once it clears, the hold is back to AUTHORIZED and the retry is sent as a new capture attempt. A capture that timed out before it left RadiumOne is sent as a new attempt on a same-operation_id retry — nothing was sent the first time. A void that timed out is reversed too: while that reversal is open, a retry gets 409 transaction:void-reversal-pending (retry_allowed: true); once it clears, the sale is back to CAPTURED and the retry is sent as a new attempt. While that earlier capture, void, or refund is unresolved, a follow-up with a different key on the same transaction gets 409 urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt: resend the pending request first. See Handle timeouts and unknown outcomes.
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.
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).
  2. Poll GET /v1/transactions/{id}/status — it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it reads PENDING or REVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request; INCONSISTENT means stop and contact support; anything else is final. See Check a transaction’s status.
If you don’t have the transaction id yet — a client-side timeout before the first response arrived — replay the same purchase, authorize, or refund with the same request_id and body. The replay is a lookup, not a resend: it returns the stored transaction and its id, whatever status it’s reached, including PENDING or REVERSAL_PENDING. A capture or void replayed with the same operation_id works the same way, and for a capture, void, or referenced refund whose outcome wasn’t recorded, RadiumOne checks with the card network before sending anything. Never re-submit with a new idempotency key just because the first attempt is slow — that risks a second charge for the same order. Unlike a referenced refund, a standalone refund is a create-type operation: it returns 201 on success (and on a replay with the same request_id), matching purchase and authorize. That also makes it safe to recover: RadiumOne saves a standalone refund before it sends it, so a replay with the same request_id and body is a lookup that never sends the refund again — even after a 5xx that says retry_allowed: false (switch-timeout, database-unavailable). If a standalone refund times out or returns a 5xx, replay it with the same key to get its stored result. A referenced refund replays the same way — see Handle timeouts and unknown outcomes.

Errors

Full HTTP status and meaning for each of these is defined once on Problem format and retries — this list is only the standalone-refund-specific nuance:

Voiding a standalone refund

A standalone refund is its own transaction and follows the same void-or-refund rule as any other capture: you can void it while its settlement batch is still open, and you can’t once it closes.

Monitoring

Because a leaked or over-scoped key can issue standalone refunds silently, treat refund volume and amount as a security signal, not just a finance one:
  • Alert on any standalone refund above your normal order size, or on a burst of them in a short window.
  • Reconcile standalone refunds against a real business reason (the goodwill credit, the chargeback case) — an unexplained one is an incident, not a bookkeeping question.
  • Review who holds keys scoped to transaction-refund-unreferenced on a regular cadence, and remove the scope from any key that doesn’t need it.

Test your integration

See Test your integration once enablement is confirmed for your sandbox outlet.

Go-live notes

  • Request a key scoped to only transaction-refund-unreferenced (not a general-purpose key) for whatever service issues these refunds.
  • Log every standalone refund with the business reason before you call the API, not after.
  • Review the full go-live checklist.

Next steps

Refund a payment

Use the referenced refund whenever an original transaction exists.

Security and PCI scope

Key storage, rotation, and emergency revocation guidance.
Last modified on October 25, 2026