Skip to main content
A handful of ideas show up in nearly every Payments API call. This page is the map — each one gets a short explanation and a link to the guide that covers it in full. For where the gateway itself sits, see Architecture.

​
How they fit together

Setting up a charge (1–5): environments and keys, sessions, idempotency, amounts, and the choice between authorize, capture, and purchase. Tracking the result (6–10): transactions and their statuses, void vs. refund, settlement batches, webhooks, and telling an error apart from a decline.

​
1. Environments and keys

Sandbox and production are fully separate: different hosts, different keys, no shared state. A _test_ key only ever works against sandbox; a _prod_ key only against production. Sandbox and production use separate credentials, hosts and webhook endpoints — see Sandbox and API keys. See Sandbox and API keys for key types, scopes, and how to get credentials.

​
2. Sessions

A payment session, created through the Payments API, ties RadiumOne Elements card fields on your page to a specific charge before you call purchase or authorize. It’s distinct from a checkout session, which is created through the separate Checkout API for Hosted checkout. See Accept a card payment for how a payment session is created and consumed.

​
3. Idempotency with request IDs

Every create-type request carries an idempotency key, scoped to your merchant account (not per outlet, not global): request_id for purchase, authorize, refunds, and the balance inquiry; operation_id for capture and void.
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.
request_id and operation_id behave differently on a replay — a changed amount is rejected for one and silently accepted for the other. See Resolve idempotent replays and conflicts for the full decision flow, or Prevent duplicate payments for the cross-product guide.

​
4. Amounts in minor units

Amounts are always integers in the currency’s minor unit. For example, 5000 for SGD means SGD 50.00.
This applies everywhere an amount appears — requests, transaction responses, and webhook payloads — though the webhook shape is slightly different ({currency, value, minor_units}, where minor_units is the currency’s decimal-place exponent). See Webhook event types for the exact payload shape.

​
5. Authorize vs. capture vs. purchase

Authorize reserves funds without taking them; capture takes funds from an existing authorization; purchase does both in one call. Use authorize + capture when you need to confirm stock or finalize an order before charging, and purchase when you charge immediately. See Charge or authorize a payment and Capture an authorization.

​
6. Transaction types and statuses

Every purchase, authorization, capture, void, and refund is a transaction with its own status — PENDING, AUTHORIZED, CAPTURED, DECLINED, and more, through settlement and any automatic reversal. See Payment lifecycle for the full state diagram and status table.

​
7. Void vs. refund

Void while the settlement batch is OPEN. Refund once it’s CLOSED. You can’t do either the other way around:
  • Voiding a transaction whose batch has already closed returns 409 urn:radiumone:tx:void-on-non-open-batch.
  • Refunding a transaction whose batch is still open returns 409 urn:radiumone:tx:refund-on-open-batch.
The boundary is the settlement batch closing, not the card network settling with the issuer. Check GET /v1/transactions/{id}/status or a settlement.* webhook if you’re unsure which state you’re in. See Resolve void and refund conflicts if you hit either error.

​
8. Settlement batches

Captured funds move through a settlement batch per terminal/outlet before they reach your acquirer account. Batch state is what gates whether a transaction can still be voided or must instead be refunded (see above). See Settlement and reconciliation for batch webhooks and reconciliation tips.

​
9. Webhooks are the source of truth

A synchronous API response can be PENDING, or can time out entirely. Webhooks are how RadiumOne reports the eventual outcome regardless — treat them as authoritative for reconciliation, not just a convenience notification. Dedupe on the event id (deliveries are at-least-once) and verify the signature before trusting the payload.

​
10. Errors vs. declines

A decline is a normal 2xx response with data.status: "DECLINED" — the request succeeded, the card didn’t. An error is a non-2xx response with a problem+json body identifying a urn:radiumone:... code — the request itself couldn’t be completed. See Problem format and retries for the error shape and status guide, and Handle declined payments for what to do with a decline.

​
Next steps

Architecture

Where the gateway sits between your systems and the payment network.

Payment lifecycle

Every status a transaction can reach, end to end.

Webhooks

Build a handler that verifies, dedupes, and processes events safely.

Problem format and retries

The problem+json shape, retry rules, and the full URN catalog.
Last modified on September 15, 2026