Refunds require enablement
This request requires a valid access token. See Authentication to obtain one with
POST /v1/auth/token before you continue.Void while the settlement batch is OPEN. Refund once it’s CLOSED. You can’t do either the other way around:
- Voiding a transaction whose batch has already closed returns
409 urn:radiumone:payment-gateway:tx:void-on-non-open-batch. - Refunding a transaction whose batch is still open returns
409 urn:radiumone:payment-gateway:tx:refund-on-open-batch.
GET /v1/transactions/{id}/status or a settlement.* webhook if you’re unsure which state you’re in. See Resolve void and refund conflicts if you hit either error.Partial and multiple refunds
Send anamount up to the original transaction’s amount minus any prior refunds already issued against it. You can refund the same transaction more than once — for example, refunding one line item now and another later — as long as the running total never exceeds the original amount.
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.Refund is a new transaction
A referenced refund creates its own transaction record with its ownid and its own CAPTURED status on success — it doesn’t change the status of the original payment. Look up the refund by the id returned in the response, not by the original transaction’s id.
Steps
1
Refund the transaction
Send the original transaction’s If the call times out, see Handle timeouts and unknown outcomes. If it conflicts with the batch state or the remaining amount, see Resolve void and refund conflicts.
id, a request_id for this refund attempt, and the amount to return. 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).
A retry with the same
request_id is always replayed — you get the stored refund back, whatever its status, including DECLINED or FAILED. This is checked before any of the refund gates (batch state, window, cap) run, so a changed refundable amount since your first call never turns a replay into a 422. The match is: the same original transaction, the same amount, and a key that was previously used for a refund — reason isn’t compared. Any other reuse of the key (a different original transaction, a different amount, or a key already used for something other than a refund) returns 409 urn:radiumone:payment-gateway:transaction:duplicate-body-mismatch instead of replaying.
A wrong transaction_id in the path always returns 404, even if the request_id matches a stored refund — the 404 takes precedence over the replay.
If the outcome is unknown — no response, or any 5xx, even one that says retry_allowed: false — replay the identical refund with the same request_id. The replay is a lookup, not a resend: RadiumOne returns the refund it recorded, and if the refund reached the card network but the outcome wasn’t recorded, it asks the network for the stored outcome instead of refunding again. It sends the refund only if the network never received it. 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 refund-specific nuance:urn:radiumone:payment-gateway:tx:refund-on-open-batch— void insteadurn:radiumone:payment-gateway:tx:invalid-state-transition— the original transaction’s state doesn’t allow a refundurn:radiumone:payment-gateway:routing:operation-disabled— refunds are switched off on the terminal that processed the original transaction; contact supporturn:radiumone:payment-gateway:transaction:duplicate-body-mismatch— therequest_idwas already used with a different body (see the replay rules above)urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt— an earlier capture, void, or refund on the original transaction was sent but has no recorded outcome; resend the onepending_operation_idnames firsturn:radiumone:payment-gateway:tx:refund-window-expired/urn:radiumone:payment-gateway:tx:refund-target-not-refundable— the original transaction can no longer be refundedurn:radiumone:payment-gateway:routing:original-acquirer-unavailable— the original acquirer is temporarily unavailable and nothing was sent; retry later with the samerequest_idurn:radiumone:payment-gateway:transaction:product-not-supported— refunding a loyalty leg directly isn’t supported; see Refunds and cancellationsurn:radiumone:payment-gateway:tx:amount-exceeds-captured— for a newrequest_idonly; a replay of an existing refund’s key never hits thisurn:radiumone:payment-gateway:tx:currency-mismatch— refunds must use the original transaction’s currencyurn:radiumone:payment-gateway:routing:capability-not-supported— request enablementurn:radiumone:payment-gateway:validation-error
No original transaction to reference?
If you need to credit a card without a prior RadiumOne transaction, see Standalone refunds — a high-risk, separately gated operation.Test your integration
See Test your integration for partial-refund and closed/open-batch scenarios.Go-live notes
- Request refund enablement for every acquirer channel you plan to refund through — it isn’t on by default, and there’s no self-service toggle. See Request enablement.
- Refund only after you’ve confirmed the batch closed — check status or wait for a
settlement.*webhook. - Track how much you’ve already refunded against a transaction; the gateway enforces the cap, but your own reconciliation should too.
- Review the full go-live checklist.
Next steps
Standalone refunds
Credit a card with no original transaction — high-risk, gated.
Settlement and reconciliation
Confirm when a batch closes before you refund.