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.
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.Amounts are always integers in the currency’s minor unit. For example,
5000 for SGD means SGD 50.00.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. - Each voucher’s
redeem_valueis a major-unit float (for example10.0means SGD 10.00) — this is the one place in the rewards API that isn’t minor units.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 Payment method errors: Loyalty (UOB Rewards):gateway:validation-error— unknown field in the request, or a required field is missingloyalty:validation-disabledloyalty:terminal-unknownloyalty:device-not-validateddevice:operation-not-supported— balance-inquiry operation toggled off on your deviceloyalty: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.