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.Tell RadiumOne which payment method the shopper chose
Sendselected_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.
- Recommended, not yet enforced. A request without it still works today,
but it will become required; the date isn’t set yet.
Once RadiumOne switches enforcement on, omitting it returns
422urn:radiumone:payment-gateway:checkout:payment-method-required— so send it now. - A method that isn’t offered for this outlet, channel, and currency is
already refused with
422urn:radiumone:payment-gateway:checkout:payment-method-not-offered. - It’s part of the idempotency key only when you send it, and it isn’t echoed on the response.
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
tokenorpan+expiry(+cvv), never both.tokenwithpan,panwithoutexpiry,expiryorcvvwithoutpan, or neither form is rejected with400urn:radiumone:payment-gateway:validation-error, and theerrors[]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
409urn:radiumone:payment-gateway:routing:raw-card-not-permittedbefore 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.panwiththree_ds.refis rejected with400(pointer/three_ds/ref). You can still send card details withthree_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_idwith a different card returns409. Thecvvisn’t, so a retry with a differentcvvreplays the original.
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.
- A key bound to one outlet can’t transact on another: sending a different
outlet_idreturns403urn:radiumone:payment-gateway:auth:outlet-binding-violation. - A disabled outlet returns
403urn:radiumone:payment-gateway:merchant:outlet-disabled. outlet_idis part of the idempotency key only when you send it: retrying arequest_idwith a differentoutlet_idreturns409.
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 onstatus — 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:
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.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:
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
PENDINGby pollingGET /v1/transactions/{id}/statusor waiting for a webhook — never by guessing. - If you fulfil from webhooks, fulfil a purchase on
payment.capturedonly — see Final events for a one-shot sale. - Never mint a new
request_idto “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.