#!/usr/bin/env bash
# Pre-sale UOB Rewards points/voucher balance. No transaction is
# created. Branch on data.success, not response_code.
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/balance-inq" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json#!/usr/bin/env python3
"""Pre-sale UOB Rewards points/voucher balance. No transaction is created."""
import json
import os
from pathlib import Path
import requests
API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")
def check_rewards_balance() -> dict:
body = json.loads((Path(__file__).parent / "request.json").read_text())
resp = requests.post(
f"{API_BASE}/v1/transactions/balance-inq",
json=body,
headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
timeout=30,
)
payload = resp.json()
if not resp.ok:
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"balance-inq failed: {code} ({resp.status_code})")
# Branch on data.success, not response_code (a cataloged decline can still be success:true).
return payload
if __name__ == "__main__":
print(json.dumps(check_rewards_balance(), indent=2))
{
"status": "ok",
"request_id": "req_inq1005bal1a",
"data": {
"request_id": "inq-1005-balance-1",
"inquiry_type": "loyalty_balance",
"success": true,
"status": "success",
"response_code": "00",
"switch_request_id": "sw-inq-1005-balance-1",
"currency": "SGD",
"currency_minor_units": 2,
"pools": [
{
"club_code": "UNI",
"pool_id": "pool_9a8b7c6d",
"pool_name": "UNI$",
"point_balance": 4534.56,
"balance_sign": "0",
"expiry_date": "00000000"
}
],
"vouchers": [
{
"voucher_code": "UNI10OFF",
"description": "S$10 rebate",
"pool_name": "UNI$",
"points_price": 1500,
"redeem_value": 10,
"redeem_value_minor": 1000,
"max_redeemable": 3
}
]
}
}{
"detail": "Request payload failed validation.",
"status": 400,
"title": "Validation Error",
"type": "urn:radiumone:payment-gateway:validation-error"
}{
"detail": "Missing or invalid Bearer token, or `urn:radiumone:payment-gateway:authentication-required` because your merchant account is not active (suspended, disabled or deleted). Checked on every request, not only when the token is issued.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}{
"detail": "Insufficient permissions for this operation; `urn:radiumone:payment-gateway:auth:outlet-binding-violation`: the request's `outlet_id` names a different outlet than the one your API key is bound to; or `urn:radiumone:payment-gateway:merchant:outlet-disabled` (`retry_allowed: false`): the outlet -- the one named, the one your key is bound to, or your DEFAULT outlet -- is disabled. Re-enabling the outlet restores service; the key is not revoked.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:auth:outlet-binding-violation"
}{
"detail": "The requested resource does not exist, or `urn:radiumone:payment-gateway:checkout:outlet-not-found`: the outlet (named, key-bound, or your DEFAULT outlet) does not exist for your account. One answer on every surface (was 400 `payment-gateway:validation-error` on transactions).",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:checkout:outlet-not-found"
}{
"detail": "The resolved terminal cannot take this request right now -- its settlement batch is closing (`device-settling`, self-clears) or was rejected and needs an operator (`device-batch-rejected`), the terminal is not active, or the operation is disabled on it. Under the `SINGLE` device-selection strategy the request is refused rather than moved to another terminal. Also `urn:radiumone:payment-gateway:routing:raw-card-not-permitted` (`resolution: operator`, `retry_allowed: false`): the request sent `card.pan` and no terminal that could serve it is enabled for raw card data -- send a payment token instead. Also `urn:radiumone:payment-gateway:routing:channel-disabled` (`retry_allowed: false`): the outlet's channel for this request is disabled.",
"status": 409,
"title": "Terminal Unavailable",
"type": "urn:radiumone:payment-gateway:routing:raw-card-not-permitted"
}{
"detail": "`urn:radiumone:payment-gateway:transaction:loyalty-leg-required` (no loyalty program can serve the inquiry for this outlet, channel and currency) or `urn:radiumone:payment-gateway:routing:capability-not-supported` (the loyalty program does not accept balance inquiries on this channel). Configuration outcomes: a retry does not help. Currency: `urn:radiumone:payment-gateway:currency:unknown-currency` (the currency is well-formed but not an active ISO 4217 currency -- an unknown, fund, N.A. or withdrawn code; `errors[]` names the field, `retry_allowed: false`) or `urn:radiumone:payment-gateway:currency:minor-units-not-supported` (a valid ISO 4217 currency whose minor units are not 2, e.g. JPY or KWD -- only 2-decimal currencies are supported; `retry_allowed: false`).",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:transaction:loyalty-leg-required"
}{
"detail": "An unexpected error occurred.",
"status": 500,
"title": "Internal Server Error",
"type": "urn:radiumone:payment-gateway:internal-error"
}{
"detail": "A downstream dependency is unavailable or did not respond in time. `urn:radiumone:payment-gateway:service-unavailable` carries `retry_allowed` true when the failure came before any work (signing keys unavailable, service starting). `urn:radiumone:payment-gateway:request-deadline-exceeded` carries `retry_allowed` true only for GET/HEAD/OPTIONS -- a mutating request may have reached a host. Also `urn:radiumone:payment-gateway:routing:acquirer-circuit-open` (the acquirer is temporarily unavailable; `retry_allowed: true`, `resolution: transient`) and `urn:radiumone:payment-gateway:routing:no-device` (no terminal available).",
"status": 503,
"title": "Service Unavailable",
"type": "urn:radiumone:payment-gateway:service-unavailable"
}Rewards balance inquiry - Payments API
Look up a card’s UOB Rewards point balance and redeemable vouchers before offering points redemption at checkout.
#!/usr/bin/env bash
# Pre-sale UOB Rewards points/voucher balance. No transaction is
# created. Branch on data.success, not response_code.
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/balance-inq" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json#!/usr/bin/env python3
"""Pre-sale UOB Rewards points/voucher balance. No transaction is created."""
import json
import os
from pathlib import Path
import requests
API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")
def check_rewards_balance() -> dict:
body = json.loads((Path(__file__).parent / "request.json").read_text())
resp = requests.post(
f"{API_BASE}/v1/transactions/balance-inq",
json=body,
headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
timeout=30,
)
payload = resp.json()
if not resp.ok:
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"balance-inq failed: {code} ({resp.status_code})")
# Branch on data.success, not response_code (a cataloged decline can still be success:true).
return payload
if __name__ == "__main__":
print(json.dumps(check_rewards_balance(), indent=2))
{
"status": "ok",
"request_id": "req_inq1005bal1a",
"data": {
"request_id": "inq-1005-balance-1",
"inquiry_type": "loyalty_balance",
"success": true,
"status": "success",
"response_code": "00",
"switch_request_id": "sw-inq-1005-balance-1",
"currency": "SGD",
"currency_minor_units": 2,
"pools": [
{
"club_code": "UNI",
"pool_id": "pool_9a8b7c6d",
"pool_name": "UNI$",
"point_balance": 4534.56,
"balance_sign": "0",
"expiry_date": "00000000"
}
],
"vouchers": [
{
"voucher_code": "UNI10OFF",
"description": "S$10 rebate",
"pool_name": "UNI$",
"points_price": 1500,
"redeem_value": 10,
"redeem_value_minor": 1000,
"max_redeemable": 3
}
]
}
}{
"detail": "Request payload failed validation.",
"status": 400,
"title": "Validation Error",
"type": "urn:radiumone:payment-gateway:validation-error"
}{
"detail": "Missing or invalid Bearer token, or `urn:radiumone:payment-gateway:authentication-required` because your merchant account is not active (suspended, disabled or deleted). Checked on every request, not only when the token is issued.",
"status": 401,
"title": "Authentication Required",
"type": "urn:radiumone:payment-gateway:authentication-required"
}{
"detail": "Insufficient permissions for this operation; `urn:radiumone:payment-gateway:auth:outlet-binding-violation`: the request's `outlet_id` names a different outlet than the one your API key is bound to; or `urn:radiumone:payment-gateway:merchant:outlet-disabled` (`retry_allowed: false`): the outlet -- the one named, the one your key is bound to, or your DEFAULT outlet -- is disabled. Re-enabling the outlet restores service; the key is not revoked.",
"status": 403,
"title": "Permission Denied",
"type": "urn:radiumone:payment-gateway:auth:outlet-binding-violation"
}{
"detail": "The requested resource does not exist, or `urn:radiumone:payment-gateway:checkout:outlet-not-found`: the outlet (named, key-bound, or your DEFAULT outlet) does not exist for your account. One answer on every surface (was 400 `payment-gateway:validation-error` on transactions).",
"status": 404,
"title": "Not Found",
"type": "urn:radiumone:payment-gateway:checkout:outlet-not-found"
}{
"detail": "The resolved terminal cannot take this request right now -- its settlement batch is closing (`device-settling`, self-clears) or was rejected and needs an operator (`device-batch-rejected`), the terminal is not active, or the operation is disabled on it. Under the `SINGLE` device-selection strategy the request is refused rather than moved to another terminal. Also `urn:radiumone:payment-gateway:routing:raw-card-not-permitted` (`resolution: operator`, `retry_allowed: false`): the request sent `card.pan` and no terminal that could serve it is enabled for raw card data -- send a payment token instead. Also `urn:radiumone:payment-gateway:routing:channel-disabled` (`retry_allowed: false`): the outlet's channel for this request is disabled.",
"status": 409,
"title": "Terminal Unavailable",
"type": "urn:radiumone:payment-gateway:routing:raw-card-not-permitted"
}{
"detail": "`urn:radiumone:payment-gateway:transaction:loyalty-leg-required` (no loyalty program can serve the inquiry for this outlet, channel and currency) or `urn:radiumone:payment-gateway:routing:capability-not-supported` (the loyalty program does not accept balance inquiries on this channel). Configuration outcomes: a retry does not help. Currency: `urn:radiumone:payment-gateway:currency:unknown-currency` (the currency is well-formed but not an active ISO 4217 currency -- an unknown, fund, N.A. or withdrawn code; `errors[]` names the field, `retry_allowed: false`) or `urn:radiumone:payment-gateway:currency:minor-units-not-supported` (a valid ISO 4217 currency whose minor units are not 2, e.g. JPY or KWD -- only 2-decimal currencies are supported; `retry_allowed: false`).",
"status": 422,
"title": "Unprocessable Content",
"type": "urn:radiumone:payment-gateway:transaction:loyalty-leg-required"
}{
"detail": "An unexpected error occurred.",
"status": 500,
"title": "Internal Server Error",
"type": "urn:radiumone:payment-gateway:internal-error"
}{
"detail": "A downstream dependency is unavailable or did not respond in time. `urn:radiumone:payment-gateway:service-unavailable` carries `retry_allowed` true when the failure came before any work (signing keys unavailable, service starting). `urn:radiumone:payment-gateway:request-deadline-exceeded` carries `retry_allowed` true only for GET/HEAD/OPTIONS -- a mutating request may have reached a host. Also `urn:radiumone:payment-gateway:routing:acquirer-circuit-open` (the acquirer is temporarily unavailable; `retry_allowed: true`, `resolution: transient`) and `urn:radiumone:payment-gateway:routing:no-device` (no terminal available).",
"status": 503,
"title": "Service Unavailable",
"type": "urn:radiumone:payment-gateway:service-unavailable"
}Request
request_id is a reference for this call, echoed back in the response —
it isn’t an idempotency key; balance inquiry has no dedup or replay store,
so every call re-queries the rewards host. loyalty.card is the
card token from a tokenization session (same shape as a purchase’s card);
loyalty.amount is the sale amount the loyalty host prices the balance
against; loyalty.channel defaults to ECOMMERCE. Optional
order_reference links the inquiry to the order it belongs to, if you
already have one. Optional outlet_id picks the outlet to query on — 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.
Response
currency is the ISO 4217 currency the balance was read for, and
currency_minor_units its decimal places. pools lists the point pools
available on the card (each with a signed point_balance and an
expiry_date); vouchers lists redeemable vouchers with their
points_price and redeem_value_minor — the voucher’s monetary value as an
integer in the sale currency’s minor units (1000 = SGD 10.00).
redeem_value, the same value as a major-unit decimal, is deprecated:
read redeem_value_minor instead. success is the field to key
the outcome on — never response_code, which is the verbatim host code for
display and reconciliation only.
Using a redemption at checkout
To actually redeem points on a sale, pass aloyalty component on
POST /v1/transactions/purchase (Payments group, API reference tab) — see
Pay with points.
Guide and failure scenarios
See Check a rewards balance for the full guide, and Handle UOB Rewards redemption failures for what to do when nothing is redeemable or the host is unavailable.Authorizations
Body
Request a loyalty balance inquiry before a sale.
Include the loyalty component to read the customer's balance. request_id is
the idempotency key for this inquiry. Unknown fields are rejected with a 400; balance
inquiries do not take a three_ds component.
Outlet to transact on. Omit it to use the outlet your API key is bound to, or your DEFAULT outlet when the key is not bound. Sending the outlet your checkout session was created for makes the sale route exactly as that session's payment methods were discovered. A key bound to a different outlet is refused with 403 urn:radiumone:payment-gateway:auth:outlet-binding-violation. Part of the idempotency key only when sent: a retry of the same request_id naming a different outlet is refused with 409.
Response
Successful Response
Standard success envelope. Every successful response has this shape, with the operation's own payload under data.
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.