Skip to main content
These conventions cover both of RadiumOne’s APIs. Where they diverge, this page says so inline — for the full detail on a Checkout-API-specific point, it links to Hosted checkout instead of repeating it.

Response envelope

Every Payments API response wraps its payload the same way:
The Checkout API uses a simpler { "status": "ok", "data": { } } envelope with no request_id.
The envelope’s request_id is an HTTP correlation ID — quote it when contacting support about a specific call. It is not the idempotency key you send in a transaction request body (confusingly also named request_id there, under data.request_id on a transaction response) — the two are unrelated and don’t need to match. Set your own correlation ID by sending an X-Request-Id request header (letters, digits, and hyphens, up to 36 characters — other characters are stripped); the gateway echoes it back as the envelope request_id, or generates one if you don’t send it.

Errors

Both APIs return errors as application/problem+json bodies (RFC 9457):
Some errors add extension members: How to handle an error:
  • Payments API and Elements: branch on retry_allowed (retryAllowed in Elements) when present, never on the HTTP status or detail. Checkout API problem bodies have no such field: follow the Retry? column on Checkout API errors — 429 and 5xx retry, 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 type you don’t recognise as not retryable, unless retry_allowed is true (Checkout API: unless it’s a 429 or 5xx).
On the Payments API, a suggested wait time comes back as the 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.
Purchase, authorize, and refund amounts additionally use a money object rather than a bare integer: { "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.
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.
On the Checkout API, 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 optional metadata 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 no channel 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 hitting 429 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.
Last modified on October 25, 2026