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.

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: 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.
  • Each voucher’s redeem_value is a major-unit float (for example 10.0 means SGD 10.00) — this is the one place in the rewards API that isn’t minor units. max_redeemable caps 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): 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 September 15, 2026