Skip to main content
Once the shopper has chosen what to redeem (see Check a rewards balance), send one purchase request with the gross order amount and the redemption. RadiumOne redeems the points first, then charges the card for the residual — your server never calls a separate “redeem” endpoint.

How it works

  1. Your server creates an access token, then a session.
  2. The shopper enters their card and the browser tokenizes it with Elements.
  3. Your server sends the token to check the rewards balance.
  4. Your server sends one purchase with the gross amount and the loyalty block. 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

amount on the purchase is the gross order total, the same figure you’d send without any redemption. RadiumOne deducts the redeemed value — you never send the net amount yourself. Sending the net amount double-deducts the redemption.
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 on status — 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.
Balance inquiry also takes a request_id field, but it isn’t an idempotency key — there’s no dedup or replay store. Every call re-queries the rewards host, even with the same request_id.
Keys are 8–64 characters, [a-zA-Z0-9-] only, unique per merchant account. Generate one key per order attempt and persist it to your database before you send the first request — never mint a new key just to retry the same attempt. See Prevent duplicate payments.
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:
  1. Wait for a webhook (payment.*, authorization.*, refund.* — see Webhook event types).
  2. Poll GET /v1/transactions/{id}/status — it returns the transaction as RadiumOne holds it. Poll every 60 seconds while it reads PENDING or REVERSAL_PENDING, and contact support if it isn’t final 60 minutes after your server sent the original request; INCONSISTENT means stop and contact support; anything else is final. See Check a transaction’s status.
If you don’t have the transaction 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 degraded outcome isn’t an error response — it’s a normal 201 with status: "AUTHORIZED" and no loyalty block. If your integration only checks for a loyalty block on success, make sure you still capture the authorization. A hold can’t be voided: an uncaptured authorization is only released when its capture window runs out, which may not be what you want for a completed order. The webhook for this outcome is authorization.created (a hold, not a payment): don’t fulfil until you’ve captured it and received payment.captured. The same applies to a UOB Rewards payment on hosted checkout, where the hold still shows the session as completed and sends the shopper back on a signed success redirect: fulfil only on payment.captured, never on the session status or the success redirect. See Final events for a one-shot sale.

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, no loyalty block) 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.
Last modified on October 30, 2026