Skip to main content
POST
cURL
Call this before a sale to check whether a card has a redeemable UOB Rewards balance, so you can offer points redemption at checkout. It’s a read-only, pre-sale check — it writes no transaction row.

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.

Response

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. 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 a loyalty 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

Authorization
string
header
required

Bearer access token from POST /v1/auth/token. Treat it as an opaque string — do not depend on its internal encoding, which has changed before and isn't part of the contract.

Body

application/json

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.

request_id
string
required

Idempotency key for this inquiry (echoed in response).

Required string length: 1 - 64
loyalty
LoyaltyInquiryComponent · object | null

Optional loyalty-balance component. When present, dispatches a pre-sale loyalty balance read to the loyalty leg paired with the resolved payment acquirer.

order_reference
string | null

Your order or cart reference for the purchase this inquiry belongs to. Forwarded to the acquirer for reconciliation; omit it when the inquiry comes before the order exists. It is not saved, so it cannot be searched on later.

Maximum string length: 128

Response

Successful Response

Standard success envelope. Every successful response has this shape, with the operation's own payload under data.

data
InquiryResponse · object | null

The operation's result. Its shape is documented per operation; omitted on responses that carry no payload.

message
string | null

Optional human-readable note. Omitted from the response when not set, which is the case for every payment operation today. Never parse it.

request_id
string | null

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.

status
string
default:ok

Always ok on a successful (2xx) response. Errors use a different body shape entirely (RFC 9457 problem details), so branch on the HTTP status code, not on this field.

Last modified on September 15, 2026