This request requires a valid access token. See Authentication to obtain one with
POST /v1/auth/token before you continue.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 If the operation isn’t enabled for your outlet, see Fix operations unavailable for your outlet.
transaction-refund-unreferenced. The outlet must also be enabled for standalone refunds at the acquirer/terminal level. API reference.Handle the result
Any 2xx response is a result you must branch onstatus — 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.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:
- Wait for a webhook (
payment.*,authorization.*,refund.*— see Webhook event types). - Poll
GET /v1/transactions/{id}/status— it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it readsPENDINGorREVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request;INCONSISTENTmeans stop and contact support; anything else is final. See Check a transaction’s status.
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:urn:radiumone:payment-gateway:auth:insufficient-scope— your key’s token doesn’t have thetransaction-refund-unreferencedscopeurn:radiumone:payment-gateway:routing:operation-disabled— standalone refunds are toggled off on every terminal that can route this requesturn:radiumone:payment-gateway:routing:no-acquirer-available— no acquirer on this channel offers standalone refunds for this cardurn:radiumone:payment-gateway:settlement:device-settling/urn:radiumone:payment-gateway:settlement:device-batch-rejected— the terminal is settling (retry later with the samerequest_id) or blocked (contact support)urn:radiumone:payment-gateway:routing:device-busy/urn:radiumone:payment-gateway:routing:acquirer-circuit-open— a terminal is busy with another operation, or the acquirer is briefly out of service; nothing was sent (retry shortly with the samerequest_id)urn:radiumone:payment-gateway:routing:raw-card-not-permitted— you sent card details instead of a card token and no terminal that could take the refund is enabled to accept themurn:radiumone:payment-gateway:merchant:outlet-disabled— the resolved outlet is disabledurn:radiumone:payment-gateway:validation-errorurn:radiumone:payment-gateway:transaction:duplicate-body-mismatch— same body-hash comparison as purchase and authorize:request_id,amount,currency,payment_method_type,channel_type, the card’span_prefix(first 8 digits, not the full token; for card details, a keyed hash of the card number and expiry, without the CVV),metadata, andorder_referenceare hashed and compared.reasonand the full card token aren’t hashed, so changing either on a retry still replays the original silently.
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-unreferencedon 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.