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.
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.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 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, value, minor_units}, where minor_units is the currency’s decimal-place exponent). See Webhook event types for the exact payload shape.
Transaction, session, balance inquiry and settlement responses return currency_minor_units beside currency — use that to format amounts for display. To find which currencies your outlet accepts, call GET /v1/merchant/currencies. See Currencies and amounts.
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:payment-gateway:tx:void-on-non-open-batch. - Refunding a transaction whose batch is still open returns
409 urn:radiumone:payment-gateway:tx:refund-on-open-batch.
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 bePENDING, 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 normal2xx 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.