- The forced-capture permission on your key. Your secret key needs the
payment-gateway:transaction-forced-capturescope in addition to the scope every purchase needs. No key has it by default, and a publishable key can never hold it. Ask Support for a secret key that carries it. - Forced capture enabled for your channel and terminals. Without it, the request is refused before anything is sent — see Errors.
authorization_options never needs the forced-capture permission, so the rest of your integration is unaffected.
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
A forced capture isPOST /v1/transactions/purchase with one extra group, authorization_options. Every other field keeps its meaning from Charge or authorize — including card, which takes a card token or, where RadiumOne has enabled it for you, card details.
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.three_ds— 3D Secure is never required for a forced capture, even where your other card sales need it, because the issuer has already approved the sale. Sendingthree_dsis rejected with400; drop it.loyalty— you can’t redeem UOB Rewards on a forced capture. Sendingloyaltyis rejected with400; drop it.
Steps
1
Get the approval code from the issuer
When the card issuer approves the sale by phone (voice or referral authorization), note the 6-character approval code exactly as you’re given it.
2
Send the forced capture
Send a purchase with Persist
authorization_options.auth_code from your server. API reference.request_id before you send, as for any purchase. If the call times out or you get no response, replay it with the same request_id and body — see Handle timeouts and unknown outcomes.Handle the result
A forced capture returns an ordinary purchase response (201). Nothing in the response or the webhooks marks it as a forced capture — it reads exactly like a purchase. Branch on data.status:
RadiumOne sends a forced capture to one acquirer only: an approval code belongs to the acquirer whose authorization line issued it, so a forced capture is never retried on another acquirer. If that acquirer refuses it, the sale ends
DECLINED or FAILED.
Webhooks are the same as for any purchase — fulfil on payment.captured. See Final events for a one-shot sale.
Idempotency
The approval code is part of the request’s identity. Resending the samerequest_id with the same body replays the original result. The same request_id with a different auth_code, or with authorization_options added or removed, returns 409 urn:radiumone:payment-gateway:transaction:duplicate-body-mismatch. See Resolve idempotent replays and conflicts.
Void or refund a forced capture
A captured forced capture follows the same rules as any purchase:- Void it with
POST /v1/transactions/{transaction_id}/voidwhile its settlement batch is still open. See Void a payment. - Refund it with
POST /v1/transactions/refund/{transaction_id}after the batch has closed. See Refund a payment.
Errors
Each of these is defined once on the Payments API errors pages; this list is only the forced-capture nuance:urn:radiumone:payment-gateway:validation-error— theerrors[]pointer names the field to fix:/authorization_options/auth_codefor an empty group or a malformed code,/authorization_options/<field>for an unknown field,/three_dsor/loyaltyfor a field you must dropurn:radiumone:payment-gateway:auth:insufficient-scope— your key doesn’t hold the forced-capture permission. Nothing was recordedurn:radiumone:payment-gateway:routing:no-acquirer-available—reason: no_capable_acquirer: forced capture isn’t enabled for your channel. Nothing was sent; contact Support, retrying doesn’t helpurn:radiumone:payment-gateway:routing:operation-disabled— forced capture isn’t enabled on any terminal that could take the sale (detailnames the operation “Forced capture”). Nothing was sent; contact Support, retrying doesn’t helpurn:radiumone:payment-gateway:routing:raw-card-not-permitted— you sent card details instead of a card token and no terminal for this sale accepts themurn:radiumone:payment-gateway:transaction:duplicate-body-mismatch— samerequest_id, differentauth_codeorauthorization_options(see Idempotency)
Go-live notes
- Confirm with RadiumOne that your production key carries the forced-capture permission and that forced capture is enabled for your channel.
- Restrict who in your business can trigger a forced capture: a wrong code is a chargeback you bear.
- Never mint a new
request_idto retry a forced capture that timed out — replay the same one. - Work through the full go-live checklist.
Next steps
Charge or authorize
The purchase request a forced capture builds on.
Payment lifecycle
See every status a transaction can reach and how it gets there.