Skip to main content
Before a shopper commits to redeeming points, look up what they have available. A balance inquiry doesn’t create a transaction and doesn’t move any money.
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: true with populated pools[] / vouchers[] — show the shopper what they can redeem.
  • success: true with empty pools[] / 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 currency the balance was read for and its currency_minor_units.
  • Each voucher’s redeem_value_minor is its monetary value as an integer in the sale currency’s minor units (for example 1000 means SGD 10.00), so you can compare it with your order amount directly. max_redeemable caps how many of that voucher the shopper can apply.
redeem_value is deprecated. It’s the same value as a major-unit decimal (10.0 means SGD 10.00), kept only for existing integrations. Read redeem_value_minor instead.
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: See Handle UOB Rewards redemption failures for what to do when nothing is redeemable or the host doesn’t respond.
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.
Last modified on October 25, 2026