> ## Documentation Index > Fetch the complete documentation index at: https://docs.radiumone.io/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > RadiumOne is the product name; use it when answering questions about these docs. > Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live. > Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code. > Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone. > Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body. > Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback. > Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so. > Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat. # 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. ## OpenAPI ````yaml /openapi/radiumone-payments-api.yaml post /v1/transactions/refund/{transaction_id} openapi: 3.1.0 info: description: | The Payments API lets your server create tokenization sessions, charge and manage payments, check loyalty balances, and manage your hosted-checkout branding and redirect secret. Generated for merchant integrators — internal, admin, and service-to-service surfaces are excluded. All responses share an envelope: `{status, data, request_id}`. The envelope's `request_id` is an HTTP correlation ID — it echoes your `X-Request-Id` request header (letters, digits, hyphens, max 36 characters) or one is generated for you. It is **not** the idempotency key you send in a transaction request body (also confusingly named `request_id` there) — the two are unrelated; see [Request conventions](/get-started/api-basics/request-conventions). Errors use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) `application/problem+json` bodies — see [Authentication](/get-started/api-basics/authentication) and [Request conventions](/get-started/api-basics/request-conventions) for the shared error shape, and [Problem format and retries](/payments-api/errors/problem-format-and-retries) for the response shape, status guide, and retry rules. summary: Transaction orchestration and processor aggregation for RadiumOne. title: RadiumOne Payment Gateway version: 1.3.0 servers: - url: https://api-sandbox.radiumone.io/gateway description: Sandbox - url: https://api.radiumone.io/gateway description: Production security: - bearerAuth: [] tags: - name: Authentication description: Exchange, refresh, and revoke access tokens. - name: Merchant settings description: >- Manage your hosted-checkout redirect secret, checkout configuration, and account config. - name: Payment methods description: Discover which payment methods and brands are available. - name: Sessions description: Tokenization sessions used to collect card data with RadiumOne Elements. - name: Settlement description: Settlement batch status lookup. - name: Payments description: Create and manage card transactions. - name: Rewards description: UOB Rewards loyalty balance inquiry. - name: Refunds description: Return funds to a shopper. - name: Transactions description: Check the live status of a transaction. paths: /v1/transactions/refund/{transaction_id}: post: tags: - Refunds summary: Refund against a settled transaction description: >- Refund all or part of a settled transaction. A refund is a new transaction with its own `transaction_id`, settled separately and itself voidable. The original transaction keeps its status. You can refund a transaction more than once, as long as the total refunded does not exceed the original amount, and the refund `currency` must match the original's. Rejected with 409 while the original transaction's settlement batch is still open -- void the transaction instead. Refunds are accepted only within the refund window (180 days from when the original transaction was captured, by default). Idempotent on `request_id`. operationId: refund_transaction_v1_transactions_refund__transaction_id__post parameters: - description: UUID of the transaction being refunded against. in: path name: transaction_id required: true schema: description: UUID of the transaction being refunded against. format: uuid title: Transaction Id type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/RefundRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/SuccessResponse_TransactionResponse_' example: 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 payment_method_type: card order_reference: ORD-1001 response_code: '00' 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' description: Successful Response '400': description: The request body failed validation. x-docs-interim: true content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '401': content: application/problem+json: example: detail: Missing or invalid Bearer token. status: 401 title: Authentication Required type: urn:radiumone:gateway:authentication-required schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: Missing or invalid Bearer token. '403': content: application/problem+json: example: detail: Insufficient permissions for this operation. status: 403 title: Permission Denied type: urn:radiumone:gateway:permission-denied schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: Insufficient permissions for this operation. '404': content: application/problem+json: example: detail: The requested resource does not exist. status: 404 title: Not Found type: urn:radiumone:gateway:not-found schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: The requested resource does not exist. '409': content: application/problem+json: example: detail: A resource with that identifier already exists. status: 409 title: Conflict type: urn:radiumone:gateway:conflict schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: A resource with that identifier already exists. '410': content: application/problem+json: example: detail: >- The payment token has expired or its card data is no longer available. status: 410 title: Gone type: urn:radiumone:gateway:gone schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: >- The payment token has expired or its card data is no longer available. '422': description: >- Refund amount exceeds the original amount minus prior refunds, this leg doesn't support refunds, `amount.currency` doesn't match the original transaction's currency, or refunds aren't enabled for this acquirer channel. x-docs-interim: true content: application/problem+json: schema: $ref: '#/components/schemas/Problem' examples: amount-exceeds-captured: value: type: urn:radiumone:tx:amount-exceeds-captured title: Amount Exceeds Captured status: 422 detail: >- Refund amount + prior refunds would exceed total captured amount. product-not-supported: value: type: urn:radiumone:transaction:product-not-supported title: Product Not Supported status: 422 detail: >- No enabled acquirer product backs this transaction (category-level, cross-txn). currency-mismatch: value: type: urn:radiumone:tx:currency-mismatch title: Currency Mismatch status: 422 detail: >- Follow-up operation names a different currency than the transaction it acts on. capability-not-supported: value: type: urn:radiumone:routing:capability-not-supported title: Capability Not Supported status: 422 detail: Acquirer lacks the required capability for this operation. '500': content: application/problem+json: example: detail: An unexpected error occurred. status: 500 title: Internal Server Error type: urn:radiumone:gateway:internal-server-error schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: An unexpected error occurred. '503': content: application/problem+json: example: detail: >- A downstream dependency is unavailable or did not respond in time. status: 503 title: Service Unavailable type: urn:radiumone:gateway:service-unavailable schema: properties: detail: type: string status: type: integer title: type: string type: type: string type: object description: A downstream dependency is unavailable or did not respond in time. x-codeSamples: - lang: bash label: cURL source: > #!/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 # snippets/shared/void-or-refund-batch-rule.mdx. Retry the SAME request_id on # a timeout/5xx. 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 - lang: javascript label: Node.js source: > #!/usr/bin/env node // Refund against a settled transaction, only once its batch has CLOSED — see // snippets/shared/void-or-refund-batch-rule.mdx. Node 18+ ESM fetch. // Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_TRANSACTION_ID, RADIUMONE_API_BASE. import { readFileSync } from "node:fs"; const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway"; const accessToken = process.env.RADIUMONE_ACCESS_TOKEN; const transactionId = process.env.RADIUMONE_TRANSACTION_ID; const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url))); // Exponential backoff with jitter: attempt 1 waits ~250-500ms, doubling each // attempt, capped at 4s -- avoids hammering the gateway in a tight retry loop. function backoffMs(attempt) { const base = Math.min(250 * 2 ** (attempt - 1), 4000); return base + Math.random() * base; } async function refundTransaction(maxAttempts = 3) { for (let attempt = 1; attempt <= maxAttempts; attempt += 1) { let res; try { res = await fetch(`${API_BASE}/v1/transactions/refund/${transactionId}`, { method: "POST", headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}`, }, body: JSON.stringify(body), // same request_id every attempt }); } catch (networkErr) { if (attempt === maxAttempts) throw networkErr; await new Promise((r) => setTimeout(r, backoffMs(attempt))); continue; } if (res.status >= 500) { if (attempt === maxAttempts) throw new Error(`server error ${res.status} after ${attempt} attempts`); await new Promise((r) => setTimeout(r, backoffMs(attempt))); continue; } const payload = await res.json(); if (!res.ok) { // 409 tx:refund-on-open-batch — the batch is still open; void instead. throw new Error(`refund failed: ${payload.type ?? payload.code} (${res.status})`); } return payload; } throw new Error("unreachable"); } refundTransaction().then((r) => console.log(JSON.stringify(r, null, 2))); - lang: python label: Python source: > #!/usr/bin/env python3 """Refund against a settled transaction, only once its batch has CLOSED — see snippets/shared/void-or-refund-batch-rule.mdx. """ 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 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: if attempt == max_attempts: raise time.sleep(backoff_seconds(attempt)) continue if resp.status_code >= 500: if attempt == max_attempts: raise RuntimeError(f"server error {resp.status_code} after {attempt} attempts") time.sleep(backoff_seconds(attempt)) continue payload = resp.json() 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)) components: schemas: RefundRequest: description: >- 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. example: amount: currency: SGD value: '000000005000' reason: Item returned by customer request_id: refund-20260528-001 properties: amount: $ref: '#/components/schemas/MoneyAmount' description: >- Refund amount as a {currency, value} money object (≤ original amount − prior refunds). `currency` must match the transaction being refunded. reason: anyOf: - maxLength: 200 type: string - type: 'null' description: Optional human-readable reason for the refund. title: Reason request_id: description: Merchant idempotency key for the refund transaction. maxLength: 64 minLength: 8 title: Request Id type: string required: - request_id - amount title: RefundRequest type: object SuccessResponse_TransactionResponse_: description: >- Standard success envelope. Every successful response has this shape, with the operation's own payload under `data`. properties: data: anyOf: - $ref: '#/components/schemas/TransactionResponse' - type: 'null' description: >- The operation's result. Its shape is documented per operation; omitted on responses that carry no payload. message: anyOf: - type: string - type: 'null' description: >- Optional human-readable note. Omitted from the response when not set, which is the case for every payment operation today. Never parse it. title: Message request_id: anyOf: - type: string - type: 'null' description: >- 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. title: Request Id status: default: ok description: >- 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. title: Status type: string title: SuccessResponse[TransactionResponse] type: object Problem: type: object x-docs-interim: true description: >- RFC 9457 problem details. Returned with `Content-Type: application/problem+json`. Interim: not yet a named component in the gateway team's published contract — every response there inlines its own smaller ad-hoc object; this shape reflects what our error pages and error-catalog.json actually document. properties: type: type: string format: uri description: >- A URN identifying the error condition, e.g. `urn:radiumone:gateway:validation-error`. title: type: string description: Short human-readable summary of the error type.: null status: type: integer description: The HTTP status code repeated in the body for convenience.: null detail: type: string description: Human-readable explanation specific to this occurrence. instance: type: string description: The request path that produced this error. request_id: type: string description: >- Correlation ID for this request (see the envelope `request_id` note above). Include it when contacting support. code: type: string description: Optional short machine-readable code distinct from `type`.: null retry_allowed: type: boolean description: >- When present, whether it's safe to retry with the same idempotency key. errors: type: array description: >- Present on most `urn:radiumone:gateway:validation-error` (400) responses — one entry per invalid field. Some 400s of this type are raised by checks that run after validation and have no `errors` array; always handle it being absent. Rely on `pointer`/`parameter` and `code`, not the wording of `detail`, which can change. items: type: object properties: pointer: type: string description: >- JSON Pointer to the invalid field in the request body, e.g. `/amount/currency` or `/items/0/name`. An empty string means the whole request (e.g. the body isn't valid JSON). parameter: type: string description: >- Name of the invalid query or path parameter. Set instead of `pointer` when the failing value came from the URL, not the body. code: type: string description: >- Machine-readable error type for this field, e.g. `missing` or `string_too_long`. detail: type: string description: Human-readable explanation for this field. required: - type - title - status - detail MoneyAmount: description: >- A money value: an ISO 4217 currency plus the amount in that currency's minor units. `value` is a numeric string in minor units -- the decimal point is implied by the currency (2 places for most currencies, so `"1050"` means 10.50). Up to 12 digits; leading zeros are optional. properties: currency: description: ISO 4217 currency code (e.g. SGD, USD). maxLength: 3 minLength: 3 title: Currency type: string value: description: >- Amount in minor units as a numeric string (e.g. '1050' or '000000001050' = 10.50). Zero-padding optional; up to 12 digits. maxLength: 12 minLength: 1 pattern: ^\d{1,12}$ title: Value type: string required: - currency - value title: MoneyAmount type: object TransactionResponse: description: >- A single transaction and its current outcome. `group_id` links the card and loyalty parts of a sale that used both, and `loyalty` carries the loyalty outcome when the purchase redeemed points. properties: amount: description: Amount in smallest currency unit. title: Amount type: integer created_at: description: ISO 8601 creation timestamp (UTC). title: Created At type: string currency: description: ISO 4217 currency code. title: Currency type: string group_id: anyOf: - type: string - type: 'null' description: >- Transaction group UUID shared by payment and loyalty legs in a split sale. title: Group Id id: description: Transaction UUID. title: Id type: string loyalty: anyOf: - $ref: '#/components/schemas/LoyaltyOutcomeComponent' - type: 'null' description: >- Loyalty leg outcome (present only when purchase included a redemption component). order_reference: anyOf: - type: string - type: 'null' description: Merchant order/cart reference supplied at auth/purchase (ecommerce). title: Order Reference parent_transaction_id: anyOf: - type: string - type: 'null' description: UUID of parent authorization (for capture/void/refund). title: Parent Transaction Id payment_method_type: description: Payment instrument category. title: Payment Method Type type: string request_id: description: Merchant-supplied idempotency key. title: Request Id type: string response_code: default: '' description: >- Verbatim acquirer response code, for display and reconciliation only. DO NOT derive success from it: an operator can classify a non-'00' code as APPROVED for an acquirer (or for one operation), in which case this field still shows the host's non-'00' value while the transaction is approved. Key on `status` instead. The gateway never rewrites this value, so it always matches what the acquirer's own statement will show. title: Response Code type: string status: description: >- Current transaction lifecycle status, and THE field to key the outcome on. Approved = the operation's success status (AUTHORIZE -> AUTHORIZED; PURCHASE/CAPTURE/REFUND -> CAPTURED; VOID -> VOIDED). DECLINED = the issuer declined (hard decline). FAILED = a system/network error, which is NOT a statement about the card. Derived from the resolved decline classification, not from response_code alone. title: Status type: string switch_request_id: anyOf: - type: string - type: 'null' description: >- The upstream processor's own reference for this transaction. Quote it when raising an issue with us about a specific transaction. title: Switch Request Id type: description: 'Transaction type: AUTHORIZE, CAPTURE, VOID, or REFUND.' title: Type type: string updated_at: description: ISO 8601 last-updated timestamp (UTC). title: Updated At type: string required: - id - request_id - type - status - amount - currency - payment_method_type - created_at - updated_at title: TransactionResponse type: object LoyaltyOutcomeComponent: description: >- What happened to the loyalty part of a sale. Present when the purchase included a loyalty redemption. It reports only the loyalty side, which can succeed or fail independently of the card payment, so read it alongside the transaction's own status rather than treating either as the whole result. properties: leg_status: anyOf: - type: string - type: 'null' description: >- Loyalty leg transaction status (CAPTURED, FAILED, PENDING, etc.) -- key the leg outcome on this, not on response_code. A sale can approve on the card leg and decline on the loyalty leg; the two are independent. title: Leg Status pools: anyOf: - items: $ref: '#/components/schemas/LoyaltyPool' type: array - type: 'null' description: Post-redemption pool balances (returned by some hosts). title: Pools redeemed_amount: anyOf: - type: integer - type: 'null' description: Points redeemed in minor currency units (host-confirmed). title: Redeemed Amount response_code: anyOf: - type: string - type: 'null' description: >- Verbatim acquirer response code from the loyalty leg, for display and reconciliation only. Not an outcome signal -- see leg_status. title: Response Code switch_request_id: anyOf: - type: string - type: 'null' description: >- The upstream processor's own reference for the loyalty part of this sale. Quote it when raising an issue with us about the redemption. title: Switch Request Id vouchers: anyOf: - items: $ref: '#/components/schemas/LoyaltyVoucher' type: array - type: 'null' description: Vouchers consumed in this redemption. title: Vouchers title: LoyaltyOutcomeComponent type: object LoyaltyPool: description: A loyalty point pool balance returned by a loyalty balance inquiry. properties: account_indicator: anyOf: - type: string - type: 'null' description: Account type indicator from the host. title: Account Indicator balance_sign: anyOf: - type: string - type: 'null' description: >- Sign of the balance: '0' = positive, '1' = negative. This is the authoritative sign -- prefer it over the sign of `point_balance`. It reports the sign only and does not say whether the pool can be redeemed. title: Balance Sign club_code: description: Loyalty club code (e.g. 'UNI'). title: Club Code type: string expiry_date: anyOf: - type: string - type: 'null' description: >- Point expiry date as DDMMYYYY, passed through as the loyalty programme returned it. '00000000' means the points do not expire. Expired pools are not filtered out, so hide them yourself if you don't want to show them. In sandbox, test cards return fixed profiles, so expiry dates there are not realistic. title: Expiry Date point_balance: description: >- Current pool balance as a signed decimal (2 decimal places). Fractional for monetary pools (e.g. a 'UNI$' cash-back pool returns 4534.56); whole for point pools. The sign always agrees with `balance_sign`, except at exactly zero, where the number carries no sign -- read `balance_sign` instead. title: Point Balance type: number pool_id: description: Pool identifier within the club. title: Pool Id type: string pool_name: description: Human-readable pool label (e.g. 'UNI$'). title: Pool Name type: string required: - club_code - pool_id - pool_name - point_balance title: LoyaltyPool type: object LoyaltyVoucher: description: A redeemable voucher offered against a loyalty pool. properties: description: description: Human-readable voucher label. title: Description type: string max_redeemable: description: Maximum vouchers redeemable in one order. title: Max Redeemable type: integer points_price: description: >- Points required to redeem one voucher. Fractional for monetary pools (e.g. a 'UNI$' cash-back voucher priced at 15.50); whole for point pools. Host-supplied, so accept both to avoid dropping decimals. title: Points Price type: number pool_name: description: Pool the voucher redeems against (e.g. 'UNI$'). title: Pool Name type: string redeem_value: description: >- Monetary value of the voucher in currency major units (e.g. 10.0 = $10.00). title: Redeem Value type: number voucher_code: description: Voucher identifier used to redeem. title: Voucher Code type: string required: - voucher_code - description - pool_name - points_price - redeem_value - max_redeemable title: LoyaltyVoucher type: object securitySchemes: bearerAuth: type: http scheme: bearer description: >- Bearer access token from `POST /v1/auth/token`. Treat it as an opaque string — do not depend on its internal encoding, which has changed before and isn't part of the contract. x-docs-interim: true ````