Skip to main content
Call the Payments API directly from your server when you’re using RadiumOne Elements (or your own card-on-file flow) instead of hosted checkout. Use purchase to charge a card in one step, or authorize to reserve funds and capture the amount later.

Purchase vs. authorize

An authorization must be captured within your account’s capture window or it lapses to AUTH_EXPIRED. You can’t void an uncaptured authorization: a hold you don’t capture is released when its window runs out. See Payment lifecycle for the full state diagram. If the card issuer already approved the sale by phone (a voice or referral authorization), send its approval code with a purchase instead — see Forced capture.
Never use a secret key (r1sk_…) in browser code, mobile apps, or anywhere a shopper can inspect it. Secret keys belong on your server only.
This request requires a valid access token. See Authentication to obtain one with POST /v1/auth/token before you continue.

Request fields

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.
order_reference accepts up to 128 characters, but issuer statements, receipts, and some reports display far fewer. Put the part a human needs to recognize — your own order number — in the first 20–30 characters.
Fields you don’t recognize in the request body are currently ignored rather than rejected — don’t rely on this; only send documented fields.

Tell RadiumOne which payment method the shopper chose

Send selected_payment_method on every purchase and authorization. Its value is the type of the payment method the shopper picked, taken from the payment_methods[] list that payment method discovery or your session-create response returned: card for a card sale (including instalments), or uob_irr for a UOB Rewards redemption.

Send card details instead of a token

Send the card token whenever you can. Card details are an alternative only for terminals RadiumOne has enabled to accept raw card data — contact Support if you need it.
  • Exactly one form. Send either token or pan + expiry (+ cvv), never both. token with pan, pan without expiry, expiry or cvv without pan, or neither form is rejected with 400 urn:radiumone:payment-gateway:validation-error, and the errors[] pointer names the field. Error responses never echo the card number, expiry, or security code.
  • Enabled terminals only. If no terminal that could take the payment is enabled for raw card data, the request is refused with 409 urn:radiumone:payment-gateway:routing:raw-card-not-permitted before anything is sent — nothing is charged. Send a card token instead.
  • No RadiumOne 3D Secure reference. RadiumOne 3D Secure authenticates a card token, so card.pan with three_ds.ref is rejected with 400 (pointer /three_ds/ref). You can still send card details with three_ds.mode: "unauthenticated" or with your own 3DS provider’s result.
  • Where it applies. Purchase, authorize, and standalone refund take card. Capture, void, and refund of an existing transaction don’t take a card: they use the original transaction’s card, so they keep working even if raw card data is later turned off for your terminals.
  • Idempotency. The card number and expiry are part of the request’s identity: retrying a request_id with a different card returns 409. The cvv isn’t, so a retry with a different cvv replays the original.
PCI DSS applies to you when you send card details. The card number, expiry, and security code pass through your systems, so those systems are in scope for PCI DSS — unlike a card token from Elements or hosted checkout. Never log or store the security code. See Security and PCI scope.

Choose the outlet

outlet_id is optional. When you omit it, RadiumOne uses the outlet your API key is bound to, or your account’s default outlet if the key isn’t bound to one. If you created a session for a specific outlet, send that same outlet_id, so the payment is routed the same way the session’s payment methods were discovered.

Steps

1

Charge the card immediately (purchase)

Use this when you can fulfil the order right away. API reference.
If the call times out or you get no response, see Handle timeouts and unknown outcomes — never mint a new request_id for the same attempt.
2

Or reserve funds for later (authorize)

Use this when you’ll capture a (possibly different, smaller) amount after the fact. API reference.
If the operation is disabled, a terminal is busy or settling, or no terminal or acquirer is available for your outlet, see Fix operations unavailable for your outlet.

Handle the result

Any 2xx response is a result you must branch on status — never on response_code (that’s the verbatim host/acquirer code; useful for support tickets, not for your app logic). A decline is still a successful HTTP call — 201 with data.status: "DECLINED" in the body, not an error response. Always branch on status, never on the HTTP status code alone:
Treat a decline as final for this attempt — don’t retry the same request_id hoping for a different outcome; ask the shopper for another card instead. See Handle declined payments for the full walkthrough.

The card token doesn’t match the 3D Secure reference

When you charge with a RadiumOne 3D Secure reference (three_ds.ref), the card.token must be the same token that 3D Secure authenticated. If the shopper re-entered their card after authentication finished, the purchase or authorization is refused with 422 urn:radiumone:payment-gateway:three-ds:card-token-mismatch (retry_allowed: false). No RadiumOne Elements method returns this error — it only comes from purchase and authorize. Don’t resend the same request: charge the token that was authenticated, or run 3D Secure again for the new token and charge with the new reference.

Idempotency and replay

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.
Persist request_id to your database before you send the first request, so a retry after a timeout reuses the same key and body instead of minting a new one:
See Resolve idempotent replays and conflicts for the full decision flow.

Test your integration

Use the approval, decline, and timeout scenarios in Test your integration before you go live.

Go-live notes

  • Confirm your integration handles PENDING by polling GET /v1/transactions/{id}/status or waiting for a webhook — never by guessing.
  • If you fulfil from webhooks, fulfil a purchase on payment.captured only — see Final events for a one-shot sale.
  • Never mint a new request_id to “retry faster” after a timeout; it risks a duplicate charge.
  • If you take 3D Secure evidence, verify it server-side per 3D Secure overview before charging.
  • Work through the full go-live checklist.

Next steps

Payment lifecycle

See every status a transaction can reach and how it gets there.

Capture an authorization

Capture a reserved amount within the capture window.

3D Secure overview

Add strong customer authentication to your charges.

Webhooks

Get notified asynchronously instead of polling.
Last modified on October 25, 2026