Rewards redemption failures - Payments API

A balance inquiry or a redemption purchase doesn’t behave the way you expected — nothing is redeemable, the request itself is rejected, or the loyalty host doesn’t respond in time.

TL;DR — 422 means fix the request (loyalty pairing or kind); a host timeout during a purchase degrades to a normal card-only AUTHORIZED, not an error — retry the redemption itself with a new request_id if you want another attempt.

When this happens

The purchase sent a loyalty component, but the routed acquirer has no loyalty leg configured — 422 urn:radiumone:transaction:loyalty-leg-required.
The loyalty.kind you sent (voucher or coupon) is schema-accepted but not dispatchable — only sale (points redemption) is live — 422 urn:radiumone:loyalty:redemption-kind-not-supported.
A balance inquiry succeeds at the host level but nothing is redeemable for this card right now — success: true with empty pools[]/vouchers[]. This is not an error.
The loyalty host doesn’t respond in time during a purchase’s redemption leg — the redemption is treated as a warning, not a fatal failure: the purchase falls through to a card-only authorization. See Pay with points: outcomes for exactly what your server sees (a degraded, AUTHORIZED, no-loyalty-block result).

What you see

Signal	Value
HTTP status	`422` (loyalty-leg / redemption-kind)
Balance inquiry, nothing redeemable	`success: true`, empty `pools`/`vouchers`
Host timeout on a redemption purchase	Normal `201`, `status: "AUTHORIZED"`, no `loyalty` block in the response

What to do

Hide redemption when there's no balance

If a balance inquiry returns empty pools[]/vouchers[], don’t show a redemption option — let the shopper pay with the card alone (API reference):

#!/usr/bin/env bash
# Pre-sale UOB Rewards points/voucher balance. No transaction is
# created. Branch on data.success, not response_code.
set -euo pipefail

API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}"
: "${RADIUMONE_ACCESS_TOKEN:?set RADIUMONE_ACCESS_TOKEN to a Bearer access token}"

curl -sS -X POST "$API_BASE/v1/transactions/balance-inq" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
  -d @request.json

#!/usr/bin/env node
// Pre-sale UOB Rewards points/voucher balance. No transaction is
// created. Node 18+ ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE.
import { readFileSync } from "node:fs";

const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url)));

async function checkRewardsBalance() {
  const res = await fetch(`${API_BASE}/v1/transactions/balance-inq`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${accessToken}`,
    },
    body: JSON.stringify(body),
  });
  const payload = await res.json();
  if (!res.ok) {
    throw new Error(`balance-inq failed: ${payload.type ?? payload.code} (${res.status})`);
  }
  // Branch on data.success, not response_code (a cataloged decline can still be success:true).
  return payload;
}

checkRewardsBalance().then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Pre-sale UOB Rewards points/voucher balance. No transaction is created."""
import json
import os
from pathlib import Path

import requests

API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")


def check_rewards_balance() -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    resp = requests.post(
        f"{API_BASE}/v1/transactions/balance-inq",
        json=body,
        headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
        timeout=30,
    )
    payload = resp.json()
    if not resp.ok:
        code = payload.get("type") or payload.get("code")
        raise RuntimeError(f"balance-inq failed: {code} ({resp.status_code})")
    # Branch on data.success, not response_code (a cataloged decline can still be success:true).
    return payload


if __name__ == "__main__":
    print(json.dumps(check_rewards_balance(), indent=2))

Only send kind: 'sale'

Don’t send loyalty.kind: "voucher" or "coupon" — they’re accepted by the schema but always rejected. Points and voucher redemption both go through kind: "sale" (API reference):

#!/usr/bin/env bash
# Purchase with a UOB Rewards redemption. `amount` stays the GROSS
# order total — the gateway redeems points first, then charges the card
# residual. The `loyalty` block in the response is your outcome signal:
# if absent, no points moved and the card was charged in full.
set -euo pipefail

API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}"
: "${RADIUMONE_ACCESS_TOKEN:?set RADIUMONE_ACCESS_TOKEN to a Bearer access token}"

curl -sS -X POST "$API_BASE/v1/transactions/purchase" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
  -d @request.json

#!/usr/bin/env node
// Purchase with a UOB Rewards redemption. `amount` stays the GROSS
// order total — the gateway redeems points first, then charges the card
// residual. The `loyalty` block in the response is your outcome signal:
// if absent, no points moved and the card was charged in full.
// Node 18+ ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE (optional override).
//
// Shared result pattern: any 2xx is a response you branch on `data.status`.
// On a network timeout, a 5xx, or `status:"PENDING"`, retry with the SAME
// request_id — never mint a new one for the same attempt.
import { readFileSync } from "node:fs";

const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url)));

// Exponential backoff with jitter: attempt 1 waits ~250-500ms, doubling each
// attempt, capped at 4s -- avoids hammering the gateway in a tight retry loop.
function backoffMs(attempt) {
  const base = Math.min(250 * 2 ** (attempt - 1), 4000);
  return base + Math.random() * base;
}

async function createPurchaseWithRewards(maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let res;
    try {
      res = await fetch(`${API_BASE}/v1/transactions/purchase`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${accessToken}`,
        },
        body: JSON.stringify(body), // same request_id every attempt
      });
    } catch (networkErr) {
      if (attempt === maxAttempts) throw networkErr;
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue;
    }

    if (res.status >= 500) {
      if (attempt === maxAttempts) throw new Error(`server error ${res.status} after ${attempt} attempts`);
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue;
    }

    const payload = await res.json();
    if (!res.ok) {
      throw new Error(`request failed: ${payload.type ?? payload.code} (${res.status})`);
    }

    if (payload.data.status === "PENDING") {
      if (attempt === maxAttempts) return payload;
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue;
    }

    return payload; // branch on data.status
  }
  throw new Error("unreachable");
}

createPurchaseWithRewards().then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Purchase with a UOB Rewards redemption. `amount` stays the GROSS
order total — the gateway redeems points first, then charges the card
residual. The `loyalty` block in the response is your outcome signal:
if absent, no points moved and the card was charged in full.

Shared result pattern: any 2xx is a response you branch on 'status'. On a
network timeout, a 5xx, or status 'PENDING', retry with the SAME
request_id -- never mint a new one for the same attempt.
"""
import json
import os
import random
import time
from pathlib import Path

import requests

API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")


def backoff_seconds(attempt: int) -> float:
    """Exponential backoff with jitter: attempt 1 waits ~0.25-0.5s, doubling
    each attempt, capped at 4s -- avoids hammering the gateway in a loop."""
    base = min(0.25 * 2 ** (attempt - 1), 4.0)
    return base + random.random() * base


def create_purchase_with_rewards(max_attempts: int = 3) -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    headers = {"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"}

    for attempt in range(1, max_attempts + 1):
        try:
            resp = requests.post(f"{API_BASE}/v1/transactions/purchase", json=body, headers=headers, timeout=30)
        except requests.exceptions.Timeout:
            if attempt == max_attempts:
                raise
            time.sleep(backoff_seconds(attempt))
            continue

        if resp.status_code >= 500:
            if attempt == max_attempts:
                raise RuntimeError(f"server error {resp.status_code} after {attempt} attempts")
            time.sleep(backoff_seconds(attempt))
            continue

        payload = resp.json()
        if not resp.ok:
            code = payload.get("type") or payload.get("code")
            raise RuntimeError(f"request failed: {code} ({resp.status_code})")

        if payload["data"]["status"] == "PENDING":
            if attempt == max_attempts:
                return payload
            time.sleep(backoff_seconds(attempt))
            continue

        return payload  # branch on data.status

    raise RuntimeError("unreachable")


if __name__ == "__main__":
    print(json.dumps(create_purchase_with_rewards(), indent=2))

Confirm loyalty-leg pairing before relying on this in production

A 422 loyalty-leg-required means your acquirer/outlet isn’t paired with a loyalty leg — see the enablement checklist and contact support.

Monitor for degraded outcomes on a host timeout

If the response has no loyalty block, treat it exactly like a normal card purchase — the card is AUTHORIZED for the full gross amount, and you still need to capture or void it. Add monitoring so an uncaptured degraded authorization doesn’t go unnoticed. If you need to retry the redemption itself, use a new request_id per attempt.

Test it

See Test your integration for partial, full, degraded, and timeout scenarios.

Check a rewards balance

Look up what’s redeemable before the shopper pays.

Pay with points

The redemption purchase, and every outcome it can return.

UOB Rewards overview

Eligibility and the enablement checklist.

Payment method errors

The full URN catalog for loyalty errors.

Introduction

Guides

Payment methods

3D Secure

Handle failures

Webhooks

Errors

Reference

Rewards redemption failures - Payments API

When this happens

What you see

What to do

Test it

Check a rewards balance

Pay with points

UOB Rewards overview

Payment method errors

​When this happens

​What you see

​What to do

​Test it

​Related

Check a rewards balance

Pay with points

UOB Rewards overview

Payment method errors

When this happens

What you see

What to do

Test it

Related