This request requires a valid access token. See Authentication to obtain one with
POST /v1/auth/token before you continue.Before you begin
You need the shopper’s card token from an Elements bind — the same numeric
token you’d use for a purchase, not a separate rewards-specific token.
loyalty.card takes the same card object as a purchase, so card details
instead of a token work only on terminals RadiumOne has enabled for raw card
data — see Send card details instead of a token.Steps
1
Tokenize the card with Elements
Mount a card field and call
elements.submit() as you would for any
payment. See Accept a card payment with Elements
for the full tokenization flow.2
Send the balance inquiry from your server
Send the token and the quote amount (the order total you’re pricing
against) as
loyalty.amount. API reference.outlet_id is optional: omit it to use your API key’s outlet, or your
default outlet if the key isn’t bound to one. If you’ll send an
outlet_id on the purchase, send the same one here.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.3
Interpret the response
Branch on
data.success — not response_code, which is the verbatim
host code and can indicate a cataloged “approved” outcome even when
nothing is redeemable.success: truewith populatedpools[]/vouchers[]— show the shopper what they can redeem.success: truewith emptypools[]/vouchers[]— nothing is redeemable for this card right now. Let the shopper pay with the card alone.- Each pool has a signed
point_balance—balance_sign: "0"means positive,"1"means negative. Don’t infer the sign from the number alone. - The response states the
currencythe balance was read for and itscurrency_minor_units. - Each voucher’s
redeem_value_minoris its monetary value as an integer in the sale currency’s minor units (for example1000means SGD 10.00), so you can compare it with your order amount directly.max_redeemablecaps how many of that voucher the shopper can apply.
4
Show the shopper their options
Render the pools and vouchers your UI supports, and let the shopper pick
before you move on to Pay with points.
Errors
Defined once on the Errors pages:urn:radiumone:payment-gateway:validation-error— unknown field in the request, or a required field is missingurn:radiumone:payment-gateway:currency:unknown-currency/urn:radiumone:payment-gateway:currency:minor-units-not-supported—loyalty.amount.currencyisn’t an active ISO 4217 currency, or doesn’t have 2 minor units. See Currencies and amountsurn:radiumone:payment-gateway:loyalty:validation-disabledurn:radiumone:payment-gateway:loyalty:terminal-unknownurn:radiumone:payment-gateway:loyalty:device-not-validatedurn:radiumone:payment-gateway:routing:operation-disabled— balance inquiry is toggled off on every candidate loyalty terminalurn:radiumone:payment-gateway:settlement:device-settling/urn:radiumone:payment-gateway:settlement:device-batch-rejected— the loyalty terminal is settling (retry later) or blocked (contact support)urn:radiumone:payment-gateway:auth:outlet-binding-violation/urn:radiumone:payment-gateway:merchant:outlet-disabled— theoutlet_idisn’t your key’s outlet, or the outlet is disabledurn:radiumone:payment-gateway:loyalty:param-download-failed
request_id on a balance inquiry uses the same [a-zA-Z0-9-] charset as
elsewhere, just with a shorter minimum length: 1–64 characters instead of
8–64. It isn’t an idempotency key here — a balance inquiry has no dedup or
replay store, so every call re-queries the rewards host regardless of
whether you reuse the same request_id.Next steps
Pay with points
Send the purchase that redeems the selected balance.
UOB Rewards overview
Eligibility and enablement checklist.