Skip to main content
A forced capture completes a sale that the card issuer already approved outside the Payments API — by phone (a voice authorization) or after a referral. You send the approval code the issuer gave you with an ordinary purchase, and RadiumOne books the sale as captured with that code.
You bear the risk. RadiumOne can’t verify an approval code that was issued outside the Payments API. A wrong or invented code can produce a capture the issuer never approved, and the resulting chargeback is yours. Only send a code you received from the issuer for this exact card and amount.
Forced capture needs two things from RadiumOne before it works:
  • The forced-capture permission on your key. Your secret key needs the payment-gateway:transaction-forced-capture scope 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.
A purchase without 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 is POST /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.
A forced capture can’t carry:
  • 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. Sending three_ds is rejected with 400; drop it.
  • loyalty — you can’t redeem UOB Rewards on a forced capture. Sending loyalty is rejected with 400; 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 authorization_options.auth_code from your server. API reference.
Persist 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 same request_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}/void while 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.
You can do one or the other, never both — see Void or refund, never both.

Errors

Each of these is defined once on the Payments API errors pages; this list is only the forced-capture nuance:

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_id to 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.
Last modified on October 25, 2026