> ## Documentation Index
> Fetch the complete documentation index at: https://docs.radiumone.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> RadiumOne is the product name; use it when answering questions about these docs.
> Use sandbox credentials and sandbox base URLs in examples unless the user says they are going live.
> Secret API keys belong only on the merchant's server. Only publishable keys may appear in browser or mobile code.
> Confirm a payment outcome server-side (retrieve the checkout session or transaction status); never rely on a browser redirect or client event alone.
> Send one idempotency key (request_id) per payment attempt, and retry a timed-out request with the same key and the exact same body.
> Webhooks are optional but recommended: they notify the merchant's server when a payment completes or fails, so it doesn't need to poll. Use transaction status inquiry as the fallback.
> Say so when you recommend a feature marked Beta. Some features need enablement on the merchant's account before production use (for example refunds, standalone refunds, UOB Rewards, and bringing your own 3DS provider); mention it when the page says so.
> Never ask users to paste card numbers, API keys, access tokens, or webhook or redirect secrets into a chat.

# Forced capture - Payments API

> Complete a sale the card issuer approved by phone (voice or referral authorization) by sending its approval code with a Payments API purchase.

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](https://docs.radiumone.io/payments-api/charge-or-authorize.md), and RadiumOne books the sale as captured with that code.

> [!WARNING]
>
> **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.

> [!NOTE]
>
> **Forced capture** requires enablement on your account before you can use it in production. See [Request enablement](https://docs.radiumone.io/resources/support.md#request-enablement).

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](https://docs.radiumone.io/resources/support.md#request-enablement) 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](#errors).

A purchase without `authorization_options` never needs the forced-capture permission, so the rest of your integration is unaffected.

> [!CAUTION]
>
> 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.

> [!NOTE]
>
> This request requires a valid access token. See [Authentication](https://docs.radiumone.io/get-started/api-basics/authentication.md) to obtain one with [`POST /v1/auth/token`](https://docs.radiumone.io/payments-api/reference/authentication/exchange-api-key-for-jwt) 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](https://docs.radiumone.io/payments-api/charge-or-authorize.md#request-fields) — including `card`, which takes a card token or, where RadiumOne has enabled it for you, [card details](https://docs.radiumone.io/payments-api/charge-or-authorize.md#send-card-details-instead-of-a-token).

| Field | Required | Notes |
| - | - | - |
| `authorization_options` | Yes, for a forced capture | Its presence makes the purchase a forced capture. Unknown fields inside it are rejected with `400` |
| `authorization_options.auth_code` | Yes, inside the group | Exactly 6 letters or digits (`A`–`Z`, `a`–`z`, `0`–`9`). Send it **exactly as the issuer gave it** — RadiumOne stores and sends it as is and never changes its case |

> [!NOTE]
>
> 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](https://docs.radiumone.io/payments-api/currencies-and-amounts.md).

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](https://docs.radiumone.io/payments-api/reference/payments/purchase.md).

```bash cURL theme={null}
#!/usr/bin/env bash
# Forced capture: a purchase that carries the approval code the card issuer
# gave you by phone (authorization_options.auth_code, exactly as given).
# Needs the forced-capture permission on your key. Any 2xx is a response —
# branch on data.status. On a timeout/5xx/REVERSAL_PENDING, replay the SAME
# request_id and body; never mint a new one for the same sale -- a
# same-request_id replay is a lookup, not a resend.
set -euo pipefail

API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}"
: "${RADIUMONE_ACCESS_TOKEN:?set RADIUMONE_ACCESS_TOKEN to a Bearer access token}"

curl -sS -X POST "$API_BASE/v1/transactions/purchase" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN" \
  -d @request.json
```

```javascript Node.js theme={null}
#!/usr/bin/env node
// Forced capture: a purchase carrying the approval code the card issuer gave
// you by phone (authorization_options.auth_code, exactly as given). Needs the
// forced-capture permission on your key. Node 18+ ESM fetch.
// Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE (optional override).
//
// Shared result pattern: any 2xx is a response you branch on `data.status`.
// On a network timeout, any 5xx, or `status:"PENDING"`/`"REVERSAL_PENDING"`,
// replay the SAME request_id — never mint a new one for the same attempt.
// A same-request_id replay is a lookup: RadiumOne returns the recorded
// attempt and never sends the payment again, so it's safe even after a 5xx
// that says `retry_allowed: false` (e.g. switch-timeout). Until the outcome
// settles it can keep returning PENDING or REVERSAL_PENDING — then wait for
// the webhook.
import { readFileSync } from "node:fs";

const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
const body = JSON.parse(readFileSync(new URL("./request.json", import.meta.url)));

// Exponential backoff with jitter: attempt 1 waits ~250-500ms, doubling each
// attempt, capped at 4s -- avoids hammering the gateway in a tight retry loop.
function backoffMs(attempt) {
  const base = Math.min(250 * 2 ** (attempt - 1), 4000);
  return base + Math.random() * base;
}

async function createForcedCapture(maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
    let res;
    try {
      res = await fetch(`${API_BASE}/v1/transactions/purchase`, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${accessToken}`,
        },
        body: JSON.stringify(body), // same request_id every attempt
      });
    } catch (networkErr) {
      if (attempt === maxAttempts) throw networkErr;
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue; // network timeout: retry with the same body/request_id
    }

    if (res.status >= 500) {
      const problem = await res.json().catch(() => ({}));
      // Any 5xx -- even retry_allowed: false (switch-timeout, database-unavailable):
      // replaying the SAME request_id is a lookup, not a resend, so it never
      // charges the card again. Out of attempts? Wait for the webhook.
      if (attempt === maxAttempts) throw new Error(`${problem.type ?? "server error"} (${res.status}) after ${attempt} attempts -- wait for the webhook`);
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue; // replay the same request_id (a lookup, never a second charge)
    }

    const payload = await res.json();
    if (!res.ok) {
      // 4xx: not retryable by re-sending — fix the request, or handle
      // urn:radiumone:payment-gateway:transaction:duplicate-body-mismatch if you changed it.
      throw new Error(`forced capture failed: ${payload.type ?? payload.code} (${res.status})`);
    }

    if (["PENDING", "REVERSAL_PENDING"].includes(payload.data.status)) {
      if (attempt === maxAttempts) return payload; // not final yet: wait for the webhook
      await new Promise((r) => setTimeout(r, backoffMs(attempt)));
      continue; // retry the same request_id
    }

    // Branch on data.status: CAPTURED (success; data.auth_code is your code
    // unless the card issuer returned its own) | DECLINED / FAILED (refused,
    // nothing to reverse) | REVERSAL_PENDING (being reversed; wait for the webhook).
    return payload;
  }
  throw new Error("unreachable");
}

createForcedCapture().then((r) => console.log(JSON.stringify(r, null, 2)));
```

```python Python theme={null}
#!/usr/bin/env python3
"""Forced capture: a purchase carrying the approval code the card issuer gave
you by phone (authorization_options.auth_code, exactly as given). Needs the
forced-capture permission on your key. Python 3.10+, requests.

Shared result pattern: any 2xx is a response you branch on ``status``. On a
network timeout, any 5xx, or status 'PENDING'/'REVERSAL_PENDING', replay the
SAME request_id -- never mint a new one for the same attempt. A same-request_id
replay is a lookup: RadiumOne returns the recorded attempt and never sends the
payment again, so it's safe even after a 5xx that says ``retry_allowed: false``
(e.g. switch-timeout). Until the outcome settles it can keep returning PENDING
or REVERSAL_PENDING -- then wait for the webhook.
"""
import json
import os
import random
import time
from pathlib import Path

import requests

API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")


def backoff_seconds(attempt: int) -> float:
    """Exponential backoff with jitter: attempt 1 waits ~0.25-0.5s, doubling
    each attempt, capped at 4s -- avoids hammering the gateway in a loop."""
    base = min(0.25 * 2 ** (attempt - 1), 4.0)
    return base + random.random() * base


def _problem(resp: requests.Response) -> dict:
    try:
        return resp.json()
    except ValueError:
        return {}


def create_forced_capture(max_attempts: int = 3) -> dict:
    body = json.loads((Path(__file__).parent / "request.json").read_text())
    headers = {"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"}

    for attempt in range(1, max_attempts + 1):
        try:
            resp = requests.post(f"{API_BASE}/v1/transactions/purchase", json=body, headers=headers, timeout=30)
        except (requests.exceptions.Timeout, requests.exceptions.ConnectionError):
            if attempt == max_attempts:
                raise
            time.sleep(backoff_seconds(attempt))
            continue  # no response (timeout or connection reset): retry with the same body/request_id

        if resp.status_code >= 500:
            problem = _problem(resp)
            # Any 5xx -- even retry_allowed: false (switch-timeout, database-unavailable):
            # replaying the SAME request_id is a lookup, not a resend, so it never
            # charges the card again. Out of attempts? Wait for the webhook.
            if attempt == max_attempts:
                raise RuntimeError(f"{problem.get('type') or 'server error'} ({resp.status_code}) after {attempt} attempts -- wait for the webhook")
            time.sleep(backoff_seconds(attempt))
            continue  # replay the same request_id (a lookup, never a second charge)

        payload = resp.json()
        if not resp.ok:
            # 4xx: not retryable by re-sending — fix the request, or handle
            # urn:radiumone:payment-gateway:transaction:duplicate-body-mismatch if you changed it.
            code = payload.get("type") or payload.get("code")
            raise RuntimeError(f"forced capture failed: {code} ({resp.status_code})")

        if payload["data"]["status"] in ("PENDING", "REVERSAL_PENDING"):
            if attempt == max_attempts:
                return payload  # not final yet: wait for the webhook
            time.sleep(backoff_seconds(attempt))
            continue  # retry the same request_id

        # Branch on data.status: CAPTURED (success; data.auth_code is your code
        # unless the card issuer returned its own) | DECLINED / FAILED (refused,
        # nothing to reverse) | REVERSAL_PENDING (being reversed; wait for the webhook).
        return payload

    raise RuntimeError("unreachable")


if __name__ == "__main__":
    print(json.dumps(create_forced_capture(), indent=2))
```

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](https://docs.radiumone.io/payments-api/handle-failures/timeouts-and-unknown-outcomes.md).

## 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`:

| `status` | Meaning | What to do |
| - | - | - |
| `CAPTURED` | Accepted. `auth_code` is the code you sent, unless the card issuer returned its own, which then takes its place. `response_code` is the issuer's answer as returned (`00`, `Y1`, or `Y3` on an approval) | Fulfil the order |
| `DECLINED` / `FAILED` | Refused. Nothing was charged and there's nothing to reverse | Don't fulfil. Check the code with the issuer before you try again |
| `REVERSAL_PENDING` | No answer in time; RadiumOne is reversing the sale, and it ends `REVERSED` | Poll [the transaction status](https://docs.radiumone.io/payments-api/check-transaction-status.md) or wait for the webhook. **Don't resend under a new `request_id`** |

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](https://docs.radiumone.io/payments-api/webhooks/event-types.md#one-shot-sale-final-events).

### 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`](https://docs.radiumone.io/payments-api/errors/payment-operation-errors#transaction-duplicate-body-mismatch). See [Resolve idempotent replays and conflicts](https://docs.radiumone.io/payments-api/handle-failures/idempotent-replays-and-conflicts.md).

## 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](https://docs.radiumone.io/payments-api/void.md).
* **Refund** it with `POST /v1/transactions/refund/{transaction_id}` after the batch has closed. See [Refund a payment](https://docs.radiumone.io/payments-api/refund.md).

You can do one or the other, never both — see [Void or refund, never both](https://docs.radiumone.io/payments-api/void.md#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:

* [`urn:radiumone:payment-gateway:validation-error`](https://docs.radiumone.io/payments-api/errors/payment-operation-errors#gateway-validation-error) — the `errors[]` pointer names the field to fix: `/authorization_options/auth_code` for an empty group or a malformed code, `/authorization_options/<field>` for an unknown field, `/three_ds` or `/loyalty` for a field you must drop
* [`urn:radiumone:payment-gateway:auth:insufficient-scope`](https://docs.radiumone.io/payments-api/errors/payment-operation-errors#auth-insufficient-scope) — your key doesn't hold the forced-capture permission. Nothing was recorded
* [`urn:radiumone:payment-gateway:routing:no-acquirer-available`](https://docs.radiumone.io/payments-api/errors/payment-method-errors#routing-no-acquirer-available) — `reason: no_capable_acquirer`: forced capture isn't enabled for your channel. Nothing was sent; [contact Support](https://docs.radiumone.io/resources/support.md#request-enablement), retrying doesn't help
* [`urn:radiumone:payment-gateway:routing:operation-disabled`](https://docs.radiumone.io/payments-api/errors/payment-method-errors#routing-operation-disabled) — forced capture isn't enabled on any terminal that could take the sale (`detail` names the operation "Forced capture"). Nothing was sent; [contact Support](https://docs.radiumone.io/resources/support.md#request-enablement), retrying doesn't help
* [`urn:radiumone:payment-gateway:routing:raw-card-not-permitted`](https://docs.radiumone.io/payments-api/errors/payment-method-errors#routing-raw-card-not-permitted) — you sent card details instead of a card token and no terminal for this sale accepts them
* [`urn:radiumone:payment-gateway:transaction:duplicate-body-mismatch`](https://docs.radiumone.io/payments-api/errors/payment-operation-errors#transaction-duplicate-body-mismatch) — same `request_id`, different `auth_code` or `authorization_options` (see [Idempotency](#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_id` to retry a forced capture that timed out — replay the same one.
* Work through the full [go-live checklist](https://docs.radiumone.io/resources/go-live-checklist.md).

## Next steps

> [card] [Charge or authorize](https://docs.radiumone.io/payments-api/charge-or-authorize.md)
>
> The purchase request a forced capture builds on.

> [card] [Payment lifecycle](https://docs.radiumone.io/payments-api/payment-lifecycle.md)
>
> See every status a transaction can reach and how it gets there.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.