> ## 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.
# Pay with points - Payments API
> Send a single purchase that redeems UOB Rewards points and vouchers, then charges the card for the remainder.
Once the shopper has chosen what to redeem (see
[Check a rewards balance](/payments-api/payment-methods/uob-rewards/check-balance)), send
**one** purchase request with the gross order amount and the redemption.
RadiumOne redeems the points first, then charges the card for the residual —
your server never calls a separate "redeem" endpoint.
## How it works
1. Your server creates an access token, then a session.
2. The shopper enters their card and the browser tokenizes it with Elements.
3. Your server sends the token to check the rewards balance.
4. Your server sends **one** purchase with the gross `amount` and the
`loyalty` block. RadiumOne redeems the points, then authorizes and
captures the card for whatever remains.
This request requires a valid access token. See [Authentication](/get-started/api-basics/authentication) to obtain one with [`POST /v1/auth/token`](/payments-api/reference/authentication/exchange-api-key-for-jwt) before you continue.
## The amount is always gross
`amount` on the purchase is the **gross** order total, the same figure you'd
send without any redemption. RadiumOne deducts the redeemed value — you
never send the net amount yourself. Sending the net amount double-deducts
the redemption.
Amounts are always integers in the currency's minor unit. For example, `5000` for `SGD` means SGD 50.00.
## Steps
Include the vouchers (and/or `point_redeem_amount`) the shopper selected
from the balance inquiry, respecting each voucher's `max_redeemable`. [API reference](/payments-api/reference/payments/purchase).
```bash cURL theme={null}
#!/usr/bin/env bash
# Purchase with a UOB Rewards redemption. `amount` stays the GROSS
# order total — the gateway redeems points first, then charges the card
# residual. The `loyalty` block in the response is your outcome signal:
# if absent, no points moved and the card was charged in full.
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}"
curl -sS -X POST "$API_BASE/v1/transactions/purchase" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json
```
```javascript Node.js theme={null}
#!/usr/bin/env node
// Purchase with a UOB Rewards redemption. `amount` stays the GROSS
// order total — the gateway redeems points first, then charges the card
// residual. The `loyalty` block in the response is your outcome signal:
// if absent, no points moved and the card was charged in full.
// Node 18+ ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE (optional override).
//
// Shared result pattern: any 2xx is a response you branch on `data.status`.
// On a network timeout, a 5xx, or `status:"PENDING"`, retry with the SAME
// request_id — never mint a new one for the same attempt.
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 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 createPurchaseWithRewards(maxAttempts = 3) {
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
let res;
try {
res = await fetch(`${API_BASE}/v1/transactions/purchase`, {
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) {
throw new Error(`request failed: ${payload.type ?? payload.code} (${res.status})`);
}
if (payload.data.status === "PENDING") {
if (attempt === maxAttempts) return payload;
await new Promise((r) => setTimeout(r, backoffMs(attempt)));
continue;
}
return payload; // branch on data.status
}
throw new Error("unreachable");
}
createPurchaseWithRewards().then((r) => console.log(JSON.stringify(r, null, 2)));
```
```python Python theme={null}
#!/usr/bin/env python3
"""Purchase with a UOB Rewards redemption. `amount` stays the GROSS
order total — the gateway redeems points first, then charges the card
residual. The `loyalty` block in the response is your outcome signal:
if absent, no points moved and the card was charged in full.
Shared result pattern: any 2xx is a response you branch on 'status'. On a
network timeout, a 5xx, or status 'PENDING', retry with the SAME
request_id -- never mint a new one for the same attempt.
"""
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_purchase_with_rewards(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/purchase", 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:
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"request failed: {code} ({resp.status_code})")
if payload["data"]["status"] == "PENDING":
if attempt == max_attempts:
return payload
time.sleep(backoff_seconds(attempt))
continue
return payload # branch on data.status
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(create_purchase_with_rewards(), indent=2))
```
## 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).
| Status | Meaning | What to do |
| - | - | - |
| `AUTHORIZED` | Funds reserved (authorize only) | Capture within the capture window, or void to release |
| `CAPTURED` | Funds captured (purchase, capture, or refund) | Fulfil the order (or process the refund) |
| `VOIDED` | Authorization released | No funds moved |
| `DECLINED` | Issuer or acquirer declined | Final for this attempt — don't retry the same card without a new attempt from the shopper |
| `FAILED` | The transaction didn't complete — the acquirer returned a non-decline error code, or the gateway couldn't place the request. **Not a guarantee that no funds moved** — `VOIDED` and `REVERSED` are the only statuses that positively assert that. | Confirm via `GET /v1/transactions/{id}/status` before retrying, then retry (a genuinely new attempt, not a replay of the same `request_id`) with a **new** `request_id` |
| `PENDING` | Outcome not yet known (async) | Wait for a webhook, or poll `GET /v1/transactions/{id}/status` |
| `AUTH_EXPIRED` | Authorization lapsed before capture | Create a new authorization |
| `REVERSAL_PENDING` / `REVERSED` | Automatic compensating reversal after an upstream timeout left the outcome genuinely unknown (never left `FAILED` in this case) | No merchant action; webhook confirms the final state |
| Key | Used by | On replay |
| - | - | - |
| `request_id` | Purchase, authorize, standalone and referenced refunds | Same body, same operation type → the original transaction, whatever its status — including `PENDING`, `DECLINED`, or `FAILED`. Changed body, or the same key reused for a different operation type → [`transaction:idempotency-body-mismatch`](/payments-api/errors/payment-operation-errors#transaction-idempotency-body-mismatch). Purchase/authorize/standalone-refund compare `amount`, `currency`, `payment_method_type`, `channel`, the card's `pan_prefix` (first 8 digits — not the full token), `metadata`, and `order_reference`; a **referenced refund** compares only the original transaction and `amount` (`reason` isn't compared) and its replay check runs before the refund gates, so it always replays, even a `DECLINED`/`FAILED` one — mint a **new** `request_id` to retry after a decline. None of these compare `three_ds` or `loyalty`, so changing either on a retry replays the original silently instead of failing. |
| `operation_id` | Capture, void | Same operation type on the same transaction → the original result (body is never compared, so a changed amount is silently ignored). A different operation type reusing the key → [`tx:duplicate-operation`](/payments-api/errors/payment-operation-errors#tx-duplicate-operation). |
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](/get-started/api-basics/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](/payments-api/webhooks/event-types)).
2. **Call `GET /v1/transactions/{id}/status`** for a live inquiry against the acquirer.
If you don't have the transaction `id` yet — a client-side timeout before the first response arrived — replay the same request with the same `request_id` and body. The replay returns the stored transaction and its `id`, whatever status it's reached. Never re-submit with a **new** idempotency key just because the first attempt is slow — that risks a second charge for the same order.
**The presence of a `loyalty` block in the response is your outcome
signal.** If it's absent, no points moved and the card was charged in full —
treat it exactly like a normal card purchase.
## Outcomes
| Scenario | What you see |
| - | - |
| Partial redemption | Payment leg `CAPTURED` for the card residual, `loyalty` block present with `leg_status: "CAPTURED"`, both legs share one `group_id` |
| Full redemption | No card charge. The response's primary row is the loyalty leg; there may be no separate payment leg |
| Redemption declined or unavailable (**degraded**) | No `loyalty` block. The card is left **`AUTHORIZED` for the full gross amount** — you must [capture](/payments-api/capture) or [void](/payments-api/void) it yourself |
| Redemption times out at the loyalty host | Automatic reversal; the group settles as partially voided. No merchant action needed beyond confirming via webhook |
See [Handle UOB Rewards redemption failures](/payments-api/handle-failures/rewards-redemption-failures) for the full walkthrough on each outcome above.
A degraded outcome isn't an error response — it's a normal `201` with
`status: "AUTHORIZED"` and no `loyalty` block. If your integration only
checks for a `loyalty` block on success, make sure you still capture or
void the authorization; an uncaptured authorization will expire on its own
capture-window timer, which may not be what you want for a completed order.
## Webhooks
The webhook payload adds loyalty-specific fields alongside the usual
transaction data: `data.transaction.leg` (`PAYMENT` or `LOYALTY`) and
`data.transaction.redemption` (`status`, `card_amount`, `points_amount`).
Branch on `redemption.status` independently of the transaction `status` — a
declined redemption is a warning, not a failed payment. See
[Webhook event types](/payments-api/webhooks/event-types#loyalty-redemptions) for the full
payload reference.
## Test your integration
See [Test your integration](/resources/test-your-integration#uob-rewards) for
partial, full, degraded and timeout scenarios.
## Go-live notes
* Confirm enablement (see the [checklist](/payments-api/payment-methods/uob-rewards/overview#enablement-checklist)) for your production outlet before relying on this in production.
* Add monitoring for degraded (`AUTHORIZED`, no `loyalty` block) outcomes so an uncaptured authorization doesn't go unnoticed.
* Review the [go-live checklist](/resources/go-live-checklist).
## Next steps
What you can and can't do after a redeemed sale.
Combining a redemption with 3DS — coming soon.