> ## Documentation Index
> Fetch the complete documentation index at: https://docs.radiumone.io/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> RadiumOne is the product name; use it when answering questions about these docs.
> Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live.
> Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code.
> Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone.
> Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body.
> Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback.
> Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so.
> Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat.
# Create standalone refund - Payments API
> Send money back to a card with no original transaction to bound it. High-risk — requires enablement and a narrowly-scoped key.
export const RequiresEnablement = ({feature}) =>
{feature ? <>{feature} requires : "This feature requires"} enablement on your account before you can use it in production. See Request enablement.
;
This feature is in **Beta**. Behavior may change before general availability, and production access depends on your RadiumOne rollout. [Contact support](/resources/support) to confirm availability for your account.
A standalone (open, unreferenced) refund sends money to a card with **no
original transaction to bound it** — no amount cap, no time window, and no
card-token matching against a prior sale. It's the right tool for a
goodwill credit or a refund whose original transaction lives outside
RadiumOne, but it also means a mistaken or compromised call can send an
arbitrary amount to an arbitrary card.
This is a high-risk operation. It's disabled by default: it requires the
separate `transaction-refund-unreferenced` scope on your access token
(not included by default on a narrowly-scoped secret key, though it **is**
included in a secret key's full default scope set — see
[Authentication](/get-started/api-basics/authentication#scopes-and-least-privilege-keys)),
and the terminal/acquirer must explicitly support it.
This is a high-risk operation. Follow these practices:
* **Least privilege**: request a secret key scoped to only the operations it needs, not a key with every scope.
* **Key storage**: store secret keys in a server-side secrets manager, never in client code, source control, or logs.
* **Emergency revocation**: if a key is compromised, rotate or revoke it immediately — see [Emergency key revocation](/resources/support#emergency-key-revocation).
* **Monitoring**: monitor refunds and settlements for unexpected activity and alert on anomalies.
## When to use a referenced refund instead
If the original charge exists in RadiumOne, use
[`POST /v1/transactions/refund/{transaction_id}`](/payments-api/refund)
instead — it derives the card from the original transaction and enforces an
amount cap, which closes off most of the risk above.
## Request
Same shape as a purchase, minus 3DS and loyalty fields: `request_id`
(idempotency key), `amount`, `card`, `channel`, plus optional
`order_reference`, `reason`, and `metadata`.
## Idempotency
Idempotent on `request_id`, with the same replay semantics as every other
create-type operation — see
[Request conventions](/get-started/api-basics/request-conventions#idempotency-and-retries).
## Guide and failure scenarios
See [Standalone refunds](/payments-api/standalone-refunds) for the full guide, and
[Handle replays and idempotency conflicts](/payments-api/handle-failures/idempotent-replays-and-conflicts) and
[Fix operations unavailable for your outlet](/payments-api/handle-failures/operation-unavailable-for-outlet)
for what can go wrong.
## OpenAPI
````yaml openapi/radiumone-payments-api.yaml POST /v1/transactions/refund
openapi: 3.1.0
info:
description: |
The Payments API lets your server create tokenization sessions, charge and
manage payments, check loyalty balances, and manage your hosted-checkout
branding and redirect secret. Generated for merchant integrators —
internal, admin, and service-to-service surfaces are excluded.
All responses share an envelope: `{status, data, request_id}`. The
envelope's `request_id` is an HTTP correlation ID — it echoes your
`X-Request-Id` request header (letters, digits, hyphens, max 36 characters)
or one is generated for you. It is **not** the idempotency key you send in
a transaction request body (also confusingly named `request_id` there) —
the two are unrelated; see
[Request conventions](/get-started/api-basics/request-conventions). Errors
use [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)
`application/problem+json` bodies — see
[Authentication](/get-started/api-basics/authentication) and
[Request conventions](/get-started/api-basics/request-conventions) for the
shared error shape, and [Problem format and
retries](/payments-api/errors/problem-format-and-retries) for the response
shape, status guide, and retry rules.
summary: Transaction orchestration and processor aggregation for RadiumOne.
title: RadiumOne Payment Gateway
version: 1.3.0
servers:
- url: https://api-sandbox.radiumone.io/gateway
description: Sandbox
- url: https://api.radiumone.io/gateway
description: Production
security:
- bearerAuth: []
tags:
- name: Authentication
description: Exchange, refresh, and revoke access tokens.
- name: Merchant settings
description: >-
Manage your hosted-checkout redirect secret, checkout configuration, and
account config.
- name: Payment methods
description: Discover which payment methods and brands are available.
- name: Sessions
description: Tokenization sessions used to collect card data with RadiumOne Elements.
- name: Settlement
description: Settlement batch status lookup.
- name: Payments
description: Create and manage card transactions.
- name: Rewards
description: UOB Rewards loyalty balance inquiry.
- name: Refunds
description: Return funds to a shopper.
- name: Transactions
description: Check the live status of a transaction.
paths:
/v1/transactions/refund:
post:
tags:
- Refunds
summary: Open refund with no original transaction
description: >-
Credit a card without referencing an original transaction.
Use this only when there is no original transaction to refund against;
otherwise use
`POST /v1/transactions/refund/{transaction_id}`. The refund is routed
and settled like a
sale, returns 201 with its own `transaction_id`, and is itself voidable.
Because no
original transaction limits the amount, the capability is disabled by
default: your API
key needs the `transaction-refund-unreferenced` scope, and unreferenced
refunds must be
enabled for your account and terminal. Idempotent on `request_id`.
operationId: unreferenced_refund_v1_transactions_refund_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UnreferencedRefundRequest'
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse_TransactionResponse_'
example:
status: ok
request_id: req_credit1006rf1
data:
id: 8293104c-5d26-4e85-f192-031425364758
request_id: credit-1006-refund-1
type: REFUND
status: CAPTURED
amount: 5000
currency: SGD
payment_method_type: card
order_reference: CREDIT-1006
response_code: '00'
parent_transaction_id: null
switch_request_id: sw-credit-1006-refund-1
created_at: '2026-09-14T11:10:00.000Z'
updated_at: '2026-09-14T11:10:01.000Z'
description: Successful Response
'400':
description: The request body failed validation.
x-docs-interim: true
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
'401':
content:
application/problem+json:
example:
detail: Missing or invalid Bearer token.
status: 401
title: Authentication Required
type: urn:radiumone:gateway:authentication-required
schema:
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
type: object
description: Missing or invalid Bearer token.
'403':
content:
application/problem+json:
example:
detail: Insufficient permissions for this operation.
status: 403
title: Permission Denied
type: urn:radiumone:gateway:permission-denied
schema:
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
type: object
description: Insufficient permissions for this operation.
'404':
content:
application/problem+json:
example:
detail: The requested resource does not exist.
status: 404
title: Not Found
type: urn:radiumone:gateway:not-found
schema:
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
type: object
description: The requested resource does not exist.
'409':
content:
application/problem+json:
example:
detail: A resource with that identifier already exists.
status: 409
title: Conflict
type: urn:radiumone:gateway:conflict
schema:
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
type: object
description: A resource with that identifier already exists.
'410':
content:
application/problem+json:
example:
detail: >-
The payment token has expired or its card data is no longer
available.
status: 410
title: Gone
type: urn:radiumone:gateway:gone
schema:
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
type: object
description: >-
The payment token has expired or its card data is no longer
available.
'422':
description: >-
This acquirer channel or device does not have standalone
(unreferenced) refunds enabled.
x-docs-interim: true
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
examples:
operation-not-supported:
value:
type: urn:radiumone:device:operation-not-supported
title: Operation Not Supported For Device
status: 422
detail: >-
Pinned/selected device has the requested operation
disabled (per-device toggle).
'500':
content:
application/problem+json:
example:
detail: An unexpected error occurred.
status: 500
title: Internal Server Error
type: urn:radiumone:gateway:internal-server-error
schema:
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
type: object
description: An unexpected error occurred.
'503':
content:
application/problem+json:
example:
detail: >-
A downstream dependency is unavailable or did not respond in
time.
status: 503
title: Service Unavailable
type: urn:radiumone:gateway:service-unavailable
schema:
properties:
detail:
type: string
status:
type: integer
title:
type: string
type:
type: string
type: object
description: A downstream dependency is unavailable or did not respond in time.
x-codeSamples:
- lang: bash
label: cURL
source: >
#!/usr/bin/env bash
# High-risk. Standalone ("open") refund — credits a card with NO
original
# RadiumOne transaction bounding the amount. Requires the
# transaction-refund-unreferenced scope PLUS acquirer/terminal
enablement
# (see resources/support#request-enablement). Least-privilege keys
only.
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 with the transaction-refund-unreferenced scope}"
curl -sS -X POST "$API_BASE/v1/transactions/refund" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
-d @request.json
- lang: javascript
label: Node.js
source: >
#!/usr/bin/env node
// High-risk. Standalone ("open") refund — credits a card with NO
original
// RadiumOne transaction bounding the amount. Requires the
// transaction-refund-unreferenced scope PLUS acquirer/terminal
enablement
// (see resources/support#request-enablement). Least-privilege keys
only.
// 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)));
// 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 createStandaloneRefund(maxAttempts = 3) {
for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
let res;
try {
res = await fetch(`${API_BASE}/v1/transactions/refund`, {
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) {
// 403 auth:insufficient-scope, or a routing 409/422 if not yet enabled.
throw new Error(`open refund failed: ${payload.type ?? payload.code} (${res.status})`);
}
return payload;
}
throw new Error("unreachable");
}
createStandaloneRefund().then((r) => console.log(JSON.stringify(r,
null, 2)));
- lang: python
label: Python
source: >
#!/usr/bin/env python3
"""High-risk. Standalone ("open") refund — credits a card with NO
original
RadiumOne transaction bounding the amount. Requires the
transaction-refund-unreferenced scope PLUS acquirer/terminal
enablement (see
resources/support#request-enablement). Least-privilege keys only.
"""
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_standalone_refund(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/refund", 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:
# 403 auth:insufficient-scope, or a routing 409/422 if not yet enabled.
code = payload.get("type") or payload.get("code")
raise RuntimeError(f"open refund failed: {code} ({resp.status_code})")
return payload
raise RuntimeError("unreachable")
if __name__ == "__main__":
print(json.dumps(create_standalone_refund(), indent=2))
components:
schemas:
UnreferencedRefundRequest:
description: >-
Request body for POST /v1/transactions/refund -- credit a card with no
original sale.
Use this to credit a card when there is no earlier transaction to refund
against.
It is shaped like a sale and is routed and settled the same way, only in
the
opposite direction. Because it is not tied to an original transaction
there is no
amount limit, no time window and no card check, so the ability to send
one must be
enabled for your account, your acquirer and the device -- all of which
are off by
default.
example:
amount:
currency: SGD
value: '000000005000'
card:
token: '9999001234567890'
channel: CARD_PRESENT
reason: Goodwill credit, no original sale
request_id: open-refund-20260528-001
properties:
amount:
$ref: '#/components/schemas/MoneyAmount'
description: Refund amount as a {currency, value} money object.
card:
$ref: '#/components/schemas/CardToken'
description: >-
Card group carrying the network token to credit (no raw PAN).
Required: with no original to derive the card from, the caller must
name it.
channel:
description: >-
Transaction channel -- the source or manner of the payment, used to
route the refund. The acquirer must have standalone refunds enabled
on this channel.
enum:
- CARD_PRESENT
- ECOMMERCE
- MOTO
- PAYMENT_LINK
- IN_APP
- RECURRING
title: Channel
type: string
metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
description: Optional merchant-supplied metadata (max 10 KB, max 5 depth levels).
title: Metadata
order_reference:
anyOf:
- maxLength: 128
type: string
- type: 'null'
description: >-
Merchant's own reference for this credit. Stored, searchable, and
forwarded to the acquirer for reconciliation. Acquirers impose their
own limits and character rules (commonly 20 characters,
alphanumeric) and will shorten the value to fit, so prefer short
references using letters, digits, '-', '.' and '_', and put the
varying part LAST -- values are shortened from the front.
title: Order Reference
reason:
anyOf:
- maxLength: 200
type: string
- type: 'null'
description: Optional human-readable reason for the refund.
title: Reason
request_id:
description: Merchant idempotency key for the refund transaction.
maxLength: 64
minLength: 8
title: Request Id
type: string
required:
- request_id
- amount
- card
- channel
title: UnreferencedRefundRequest
type: object
SuccessResponse_TransactionResponse_:
description: >-
Standard success envelope. Every successful response has this shape,
with the operation's own payload under `data`.
properties:
data:
anyOf:
- $ref: '#/components/schemas/TransactionResponse'
- type: 'null'
description: >-
The operation's result. Its shape is documented per operation;
omitted on responses that carry no payload.
message:
anyOf:
- type: string
- type: 'null'
description: >-
Optional human-readable note. Omitted from the response when not
set, which is the case for every payment operation today. Never
parse it.
title: Message
request_id:
anyOf:
- type: string
- type: 'null'
description: >-
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.
title: Request Id
status:
default: ok
description: >-
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.
title: Status
type: string
title: SuccessResponse[TransactionResponse]
type: object
Problem:
type: object
x-docs-interim: true
description: >-
RFC 9457 problem details. Returned with `Content-Type:
application/problem+json`. Interim: not yet a named component in the
gateway team's published contract — every response there inlines its own
smaller ad-hoc object; this shape reflects what our error pages and
error-catalog.json actually document.
properties:
type:
type: string
format: uri
description: >-
A URN identifying the error condition, e.g.
`urn:radiumone:gateway:validation-error`.
title:
type: string
description: Short
human-readable summary of the error type.: null
status:
type: integer
description: The HTTP status code
repeated in the body for convenience.: null
detail:
type: string
description: Human-readable explanation specific to this occurrence.
instance:
type: string
description: The request path that produced this error.
request_id:
type: string
description: >-
Correlation ID for this request (see the envelope `request_id` note
above). Include it when contacting support.
code:
type: string
description: Optional short machine-readable code
distinct from `type`.: null
retry_allowed:
type: boolean
description: >-
When present, whether it's safe to retry with the same idempotency
key.
errors:
type: array
description: >-
Present on most `urn:radiumone:gateway:validation-error` (400)
responses — one entry per invalid field. Some 400s of this type are
raised by checks that run after validation and have no `errors`
array; always handle it being absent. Rely on `pointer`/`parameter`
and `code`, not the wording of `detail`, which can change.
items:
type: object
properties:
pointer:
type: string
description: >-
JSON Pointer to the invalid field in the request body, e.g.
`/amount/currency` or `/items/0/name`. An empty string means
the whole request (e.g. the body isn't valid JSON).
parameter:
type: string
description: >-
Name of the invalid query or path parameter. Set instead of
`pointer` when the failing value came from the URL, not the
body.
code:
type: string
description: >-
Machine-readable error type for this field, e.g. `missing` or
`string_too_long`.
detail:
type: string
description: Human-readable explanation for this field.
required:
- type
- title
- status
- detail
MoneyAmount:
description: >-
A money value: an ISO 4217 currency plus the amount in that currency's
minor units.
`value` is a numeric string in minor units -- the decimal point is
implied by
the currency (2 places for most currencies, so `"1050"` means 10.50). Up
to 12
digits; leading zeros are optional.
properties:
currency:
description: ISO 4217 currency code (e.g. SGD, USD).
maxLength: 3
minLength: 3
title: Currency
type: string
value:
description: >-
Amount in minor units as a numeric string (e.g. '1050' or
'000000001050' = 10.50). Zero-padding optional; up to 12 digits.
maxLength: 12
minLength: 1
pattern: ^\d{1,12}$
title: Value
type: string
required:
- currency
- value
title: MoneyAmount
type: object
CardToken:
description: >-
The card to charge, identified by its payment token.
Send only the payment token issued for the card -- never the card number
or
expiry. The token stands in for both.
properties:
token:
description: >-
The card's payment token (digits only). Treat it as opaque -- it is
not a card number.
maxLength: 128
minLength: 8
title: Token
type: string
required:
- token
title: CardToken
type: object
TransactionResponse:
description: >-
A single transaction and its current outcome.
`group_id` links the card and loyalty parts of a sale that used both,
and
`loyalty` carries the loyalty outcome when the purchase redeemed points.
properties:
amount:
description: Amount in smallest currency unit.
title: Amount
type: integer
created_at:
description: ISO 8601 creation timestamp (UTC).
title: Created At
type: string
currency:
description: ISO 4217 currency code.
title: Currency
type: string
group_id:
anyOf:
- type: string
- type: 'null'
description: >-
Transaction group UUID shared by payment and loyalty legs in a split
sale.
title: Group Id
id:
description: Transaction UUID.
title: Id
type: string
loyalty:
anyOf:
- $ref: '#/components/schemas/LoyaltyOutcomeComponent'
- type: 'null'
description: >-
Loyalty leg outcome (present only when purchase included a
redemption component).
order_reference:
anyOf:
- type: string
- type: 'null'
description: Merchant order/cart reference supplied at auth/purchase (ecommerce).
title: Order Reference
parent_transaction_id:
anyOf:
- type: string
- type: 'null'
description: UUID of parent authorization (for capture/void/refund).
title: Parent Transaction Id
payment_method_type:
description: Payment instrument category.
title: Payment Method Type
type: string
request_id:
description: Merchant-supplied idempotency key.
title: Request Id
type: string
response_code:
default: ''
description: >-
Verbatim acquirer response code, for display and reconciliation
only. DO NOT derive success from it: an operator can classify a
non-'00' code as APPROVED for an acquirer (or for one operation), in
which case this field still shows the host's non-'00' value while
the transaction is approved. Key on `status` instead. The gateway
never rewrites this value, so it always matches what the acquirer's
own statement will show.
title: Response Code
type: string
status:
description: >-
Current transaction lifecycle status, and THE field to key the
outcome on. Approved = the operation's success status (AUTHORIZE ->
AUTHORIZED; PURCHASE/CAPTURE/REFUND -> CAPTURED; VOID -> VOIDED).
DECLINED = the issuer declined (hard decline). FAILED = a
system/network error, which is NOT a statement about the card.
Derived from the resolved decline classification, not from
response_code alone.
title: Status
type: string
switch_request_id:
anyOf:
- type: string
- type: 'null'
description: >-
The upstream processor's own reference for this transaction. Quote
it when raising an issue with us about a specific transaction.
title: Switch Request Id
type:
description: 'Transaction type: AUTHORIZE, CAPTURE, VOID, or REFUND.'
title: Type
type: string
updated_at:
description: ISO 8601 last-updated timestamp (UTC).
title: Updated At
type: string
required:
- id
- request_id
- type
- status
- amount
- currency
- payment_method_type
- created_at
- updated_at
title: TransactionResponse
type: object
LoyaltyOutcomeComponent:
description: >-
What happened to the loyalty part of a sale.
Present when the purchase included a loyalty redemption. It reports only
the
loyalty side, which can succeed or fail independently of the card
payment, so read
it alongside the transaction's own status rather than treating either as
the whole
result.
properties:
leg_status:
anyOf:
- type: string
- type: 'null'
description: >-
Loyalty leg transaction status (CAPTURED, FAILED, PENDING, etc.) --
key the leg outcome on this, not on response_code. A sale can
approve on the card leg and decline on the loyalty leg; the two are
independent.
title: Leg Status
pools:
anyOf:
- items:
$ref: '#/components/schemas/LoyaltyPool'
type: array
- type: 'null'
description: Post-redemption pool balances (returned by some hosts).
title: Pools
redeemed_amount:
anyOf:
- type: integer
- type: 'null'
description: Points redeemed in minor currency units (host-confirmed).
title: Redeemed Amount
response_code:
anyOf:
- type: string
- type: 'null'
description: >-
Verbatim acquirer response code from the loyalty leg, for display
and reconciliation only. Not an outcome signal -- see leg_status.
title: Response Code
switch_request_id:
anyOf:
- type: string
- type: 'null'
description: >-
The upstream processor's own reference for the loyalty part of this
sale. Quote it when raising an issue with us about the redemption.
title: Switch Request Id
vouchers:
anyOf:
- items:
$ref: '#/components/schemas/LoyaltyVoucher'
type: array
- type: 'null'
description: Vouchers consumed in this redemption.
title: Vouchers
title: LoyaltyOutcomeComponent
type: object
LoyaltyPool:
description: A loyalty point pool balance returned by a loyalty balance inquiry.
properties:
account_indicator:
anyOf:
- type: string
- type: 'null'
description: Account type indicator from the host.
title: Account Indicator
balance_sign:
anyOf:
- type: string
- type: 'null'
description: >-
Sign of the balance: '0' = positive, '1' = negative. This is the
authoritative sign -- prefer it over the sign of `point_balance`. It
reports the sign only and does not say whether the pool can be
redeemed.
title: Balance Sign
club_code:
description: Loyalty club code (e.g. 'UNI').
title: Club Code
type: string
expiry_date:
anyOf:
- type: string
- type: 'null'
description: >-
Point expiry date as DDMMYYYY, passed through as the loyalty
programme returned it. '00000000' means the points do not expire.
Expired pools are not filtered out, so hide them yourself if you
don't want to show them. In sandbox, test cards return fixed
profiles, so expiry dates there are not realistic.
title: Expiry Date
point_balance:
description: >-
Current pool balance as a signed decimal (2 decimal places).
Fractional for monetary pools (e.g. a 'UNI$' cash-back pool returns
4534.56); whole for point pools. The sign always agrees with
`balance_sign`, except at exactly zero, where the number carries no
sign -- read `balance_sign` instead.
title: Point Balance
type: number
pool_id:
description: Pool identifier within the club.
title: Pool Id
type: string
pool_name:
description: Human-readable pool label (e.g. 'UNI$').
title: Pool Name
type: string
required:
- club_code
- pool_id
- pool_name
- point_balance
title: LoyaltyPool
type: object
LoyaltyVoucher:
description: A redeemable voucher offered against a loyalty pool.
properties:
description:
description: Human-readable voucher label.
title: Description
type: string
max_redeemable:
description: Maximum vouchers redeemable in one order.
title: Max Redeemable
type: integer
points_price:
description: >-
Points required to redeem one voucher. Fractional for monetary pools
(e.g. a 'UNI$' cash-back voucher priced at 15.50); whole for point
pools. Host-supplied, so accept both to avoid dropping decimals.
title: Points Price
type: number
pool_name:
description: Pool the voucher redeems against (e.g. 'UNI$').
title: Pool Name
type: string
redeem_value:
description: >-
Monetary value of the voucher in currency major units (e.g. 10.0 =
$10.00).
title: Redeem Value
type: number
voucher_code:
description: Voucher identifier used to redeem.
title: Voucher Code
type: string
required:
- voucher_code
- description
- pool_name
- points_price
- redeem_value
- max_redeemable
title: LoyaltyVoucher
type: object
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
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.
x-docs-interim: true
````