Response envelope
Every Payments API response wraps its payload the same way:{ "status": "ok", "data": { } } envelope
with no request_id.
Errors
Both APIs return errors asapplication/problem+json bodies
(RFC 9457):
How to handle an error:
- Payments API and Elements: branch on
retry_allowed(retryAllowedin Elements) when present, never on the HTTP status ordetail. Checkout API problem bodies have no such field: follow the Retry? column on Checkout API errors —429and5xxretry, as do the types it marks retryable; everything else doesn’t. - Match the whole
type— never a prefix, and never just the text after the last:. The same slug can appear under different namespaces. - Treat a
typeyou don’t recognise as not retryable, unlessretry_allowedistrue(Checkout API: unless it’s a429or5xx).
Retry-After
HTTP response header (seconds) — not as a retry_after member of the
problem body.
See Problem format and retries
for the response shape and status guide, and
Decline codes for acquirer response codes.
If a request comes back as a 5xx you should retry, see Retry when the
service is unavailable.
A 5xx with retry_allowed: false — such as
503 urn:radiumone:payment-gateway:switch-timeout, or
503 urn:radiumone:payment-gateway:database-unavailable on a POST,
PATCH, or DELETE — means don’t send the operation again. For a payment
operation, a replay with the same request_id or operation_id is a lookup,
not a resend, so it’s how you recover the outcome (it can return PENDING or
REVERSAL_PENDING until the outcome settles). A capture, void, or referenced
refund whose outcome wasn’t recorded is checked with the card network before
anything is sent. Other
endpoints: see Database
unavailable.
For Checkout API errors, see Checkout API errors.
Money amounts
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.{ "currency": "SGD", "value": "5000" }, where
value is a minor-units numeric string (zero-padding optional, up to 12
digits, non-zero). Session and transaction-response amounts remain plain
integers.
Don’t keep your own table of currency scales. Transaction, session, balance inquiry and settlement
responses return currency_minor_units beside currency, and
GET /v1/merchant/currencies lists the currencies your outlet accepts with
their minor units — see Currencies and
amounts.
Idempotency and retries
The two APIs use different idempotency keys, at different levels. Payments API —request_id (purchase, authorize, refunds) or
operation_id (capture, void), set per transaction/operation:
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.order_reference is the idempotency key for
session creation — there’s no separate request_id/operation_id concept.
A create replayed with the same order_reference, amount, and currency,
within the session’s TTL, returns the original session as long as it’s still
payable (other fields are ignored); the same reference with a different
amount or currency on a still-payable session, or a genuinely concurrent
replay, both return 409 urn:radiumone:checkout-hpp:session-idempotency-conflict (with different
detail text). See Prevent duplicate sessions
and double payments
for the full replay table and Session
lifecycle for the
TTL/state model behind it.
For the full picture — replay vs. conflict, PENDING recovery, and what to
do after a timeout — see the visual guide.
Prevent duplicate payments
How RadiumOne deduplicates requests, and what your integration needs to do on its side.
Metadata
Most create operations accept an optionalmetadata object for your own
key/value data (typical limits: 10 KB, 5 levels deep for Payments API
operations; for Checkout API sessions, a JSON object of at most 4096 UTF-16
code units serialized as compact JSON, limit included — most characters,
including Chinese and Thai, count as 1 unit and emoji as 2). It’s stored
and returned on lookups, never interpreted by RadiumOne.
Channels
Payments API only — the Checkout API has nochannel field or concept.
channel on a payment operation is one of CARD_PRESENT, ECOMMERCE,
MOTO, PAYMENT_LINK, IN_APP, or RECURRING. It shapes which acquirer
routing candidates and operations (e.g. standalone refund) are available —
pick the one that matches how the transaction was actually initiated.
Rate limits
RadiumOne doesn’t publish specific rate-limit numbers for authenticated calls. If you’re consistently hitting429 responses, contact support
to discuss your integration’s traffic pattern. Both APIs send the
Retry-After HTTP header (seconds); the Checkout API additionally carries
the same value as details.retry_after in the problem body — see
Checkout API errors.
Checkout API limits use a sliding window. A Checkout API session GET
without X-Api-Key returns a reduced public view with its own published
limit (per client IP and checkout) — always send your secret key when you
retrieve a session; that page has the numbers.