How it works
- Your server creates an access token, then a session.
- The shopper enters their card and the browser tokenizes it with Elements.
- Your server sends the token to check the rewards balance.
- Your server sends one purchase with the gross
amountand theloyaltyblock. RadiumOne redeems the points, then authorizes and captures the card for whatever remains.
This request requires a valid access token. See Authentication to obtain one with
POST /v1/auth/token before you continue.The amount is always gross
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.Steps
1
Send the purchase with the loyalty block
Include the vouchers (and/or
point_redeem_amount) the shopper selected
from the balance inquiry, respecting each voucher’s max_redeemable. API reference.Set selected_payment_method to uob_irr — the UOB Rewards
payment_methods[].type from payment method
discovery. It’s
recommended now and will be required once RadiumOne switches enforcement
on. Sending card with a loyalty block that names something to redeem is
refused with 422
urn:radiumone:payment-gateway:checkout:method-intent-conflict.Handle the result
Any 2xx response is a result you must branch onstatus — never on response_code (that’s the verbatim host/acquirer code; useful for support tickets, not for your app logic).
After a timeout or a
5xx, replay with the same key. For every payment operation — purchase, authorize, capture, void, and both refunds — a replay of the identical request with the same request_id or operation_id is a lookup, not a resend, so it’s safe even after a 5xx that says retry_allowed: false (switch-timeout, database-unavailable). RadiumOne returns the outcome it recorded. If a capture, void, or referenced refund was sent but its outcome wasn’t recorded, RadiumOne asks the card network for the stored outcome instead of sending it again, and sends it only if the network never received it — so nothing is applied twice. A replay can return PENDING or REVERSAL_PENDING until the outcome settles. A request RadiumOne refused before it reached the card network (for example with device-settling or device-busy) is run again on the same transaction instead of returning a stored result — no second transaction is created. A capture that timed out after it may have reached the card network is reversed — the capture, never the authorization under it: while that reversal is open (REVERSAL_PENDING), a same-operation_id retry gets 409 tx:invalid-state-transition; once it clears, the hold is back to AUTHORIZED and the retry is sent as a new capture attempt. A capture that timed out before it left RadiumOne is sent as a new attempt on a same-operation_id retry — nothing was sent the first time. A void that timed out is reversed too: while that reversal is open, a retry gets 409 transaction:void-reversal-pending (retry_allowed: true); once it clears, the sale is back to CAPTURED and the retry is sent as a new attempt. While that earlier capture, void, or refund is unresolved, a follow-up with a different key on the same transaction gets 409 urn:radiumone:payment-gateway:tx:followup-outcome-in-doubt: resend the pending request first. See Handle timeouts and unknown outcomes.PENDING means the outcome isn’t known yet — most often after a processor timeout. Don’t assume success or failure. Recover it one of two ways:
- Wait for a webhook (
payment.*,authorization.*,refund.*— see Webhook event types). - Poll
GET /v1/transactions/{id}/status— it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it readsPENDINGorREVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request;INCONSISTENTmeans stop and contact support; anything else is final. See Check a transaction’s status.
id yet — a client-side timeout before the first response arrived — replay the same purchase, authorize, or refund with the same request_id and body. The replay is a lookup, not a resend: it returns the stored transaction and its id, whatever status it’s reached, including PENDING or REVERSAL_PENDING. A capture or void replayed with the same operation_id works the same way, and for a capture, void, or referenced refund whose outcome wasn’t recorded, RadiumOne checks with the card network before sending anything. Never re-submit with a new idempotency key just because the first attempt is slow — that risks a second charge for the same order.
The presence of a loyalty block in the response is your outcome
signal. If it’s absent, no points moved and the card was not charged:
it’s held (status: "AUTHORIZED") for the full gross amount. Treat it like a
card authorization, not a purchase — see the degraded row below.
Outcomes
See Handle UOB Rewards redemption failures for the full walkthrough on each outcome above.
A purchase can come back as an authorization
A degraded sale is a hold, and it reports like any other hold from then on:Webhooks
The webhook payload adds loyalty-specific fields alongside the usual transaction data:data.transaction.leg (PAYMENT or LOYALTY) and
data.transaction.redemption (status, card_amount, points_amount).
Branch on redemption.status independently of the transaction status — a
declined redemption is a warning, not a failed payment. See
Webhook event types for the full
payload reference.
Test your integration
See Test your integration for partial, full, degraded and timeout scenarios.Go-live notes
- Confirm enablement (see the checklist) for your production outlet before relying on this in production.
- Add monitoring for degraded (
AUTHORIZED, noloyaltyblock) outcomes so an uncaptured authorization doesn’t go unnoticed. - Review the go-live checklist.
Next steps
Refunds and cancellations
What you can and can’t do after a redeemed sale.
Rewards with 3D Secure
Authenticate the card amount left after the redemption.