> ## 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.

# Capture a payment - Payments API

> Capture the full amount of a prior authorization within your account's capture window, and handle retries and errors safely.

Capture converts a reserved authorization into captured funds. In this version of the API, capture is **all-or-nothing**: the amount you send must equal the original authorized amount.

<Info>
  This request requires a valid access token. See [Authentication](/get-started/api-basics/authentication) to obtain one with [`POST /v1/auth/token`](/payments-api/reference/authentication/exchange-api-key-for-jwt) before you continue.
</Info>

## Full-capture rule

`amount` in the capture request must equal the `amount` on the `AUTHORIZED` transaction exactly. Partial capture isn't supported — if you need to charge less than the authorization, capture the full amount and [refund](/payments-api/refund) the difference once the batch closes, or void the authorization and create a new one for the correct amount.

`amount.currency` must also match the authorization's currency — a capture naming a different currency is refused with `422 urn:radiumone:tx:currency-mismatch`.

## The capture window

Capture within your account's capture window, which **defaults to 7 days** from authorization and can be configured shorter or longer per acquirer. Capturing after the window closes fails with `422 urn:radiumone:tx:capture-window-expired`, and the transaction moves to `AUTH_EXPIRED` — see [Payment lifecycle](/payments-api/payment-lifecycle#authorization-expiry). Contact [support](/resources/support) to confirm your account's configured window.

## Steps

<Steps>
  <Step title="Capture the authorization">
    Send the transaction's `id` and the same `amount` it was authorized for. [API reference](/payments-api/reference/payments/capture-an-authorised-transaction).

    <CodeGroup>
      ```bash cURL theme={null}
      #!/usr/bin/env bash
      # Capture a prior authorization (must equal the authorized amount in v1). Any
      # 2xx is a response — branch on data.status. On a timeout/5xx, retry with the
      # SAME operation_id; never mint a new one for the same capture attempt.
      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}"
      : "${RADIUMONE_TRANSACTION_ID:?set RADIUMONE_TRANSACTION_ID to the id of the AUTHORIZED transaction}"

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

      ```javascript Node.js theme={null}
      #!/usr/bin/env node
      // Capture a prior authorization (must equal the authorized amount in v1).
      // Node 18+ ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_TRANSACTION_ID,
      // RADIUMONE_API_BASE (optional override).
      //
      // Shared result pattern: any 2xx is a response you branch on `data.status`.
      // On a network timeout or 5xx, retry with the SAME operation_id — never mint
      // a new one for the same capture attempt.
      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 transactionId = process.env.RADIUMONE_TRANSACTION_ID;
      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 captureAuthorization(maxAttempts = 3) {
        for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
          let res;
          try {
            res = await fetch(`${API_BASE}/v1/transactions/${transactionId}/capture`, {
              method: "POST",
              headers: {
                "Content-Type": "application/json",
                Authorization: `Bearer ${accessToken}`,
              },
              body: JSON.stringify(body), // same operation_id every attempt
            });
          } catch (networkErr) {
            if (attempt === maxAttempts) throw networkErr;
            await new Promise((r) => setTimeout(r, backoffMs(attempt)));
            continue;
          }

          if (res.status >= 500) {
            if (attempt === maxAttempts) throw new Error(`server error ${res.status} after ${attempt} attempts`);
            await new Promise((r) => setTimeout(r, backoffMs(attempt)));
            continue;
          }

          const payload = await res.json();
          if (!res.ok) {
            // 422 tx:capture-window-expired if the capture window has passed.
            throw new Error(`capture failed: ${payload.type ?? payload.code} (${res.status})`);
          }
          return payload; // branch on data.status
        }
        throw new Error("unreachable");
      }

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

      ```python Python theme={null}
      #!/usr/bin/env python3
      """Capture a prior authorization (must equal the authorized amount in v1).

      Shared result pattern: any 2xx is a response you branch on ``status``. On a
      network timeout or 5xx, retry with the SAME operation_id — never mint a new
      one for the same capture attempt.
      """
      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 capture_authorization(max_attempts: int = 3) -> dict:
          body = json.loads((Path(__file__).parent / "request.json").read_text())
          transaction_id = os.environ["RADIUMONE_TRANSACTION_ID"]
          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/{transaction_id}/capture", json=body, headers=headers, timeout=30
                  )
              except requests.exceptions.Timeout:
                  if attempt == max_attempts:
                      raise
                  time.sleep(backoff_seconds(attempt))
                  continue

              if resp.status_code >= 500:
                  if attempt == max_attempts:
                      raise RuntimeError(f"server error {resp.status_code} after {attempt} attempts")
                  time.sleep(backoff_seconds(attempt))
                  continue

              payload = resp.json()
              if not resp.ok:
                  # 422 tx:capture-window-expired if the capture window has passed.
                  code = payload.get("type") or payload.get("code")
                  raise RuntimeError(f"capture failed: {code} ({resp.status_code})")
              return payload  # branch on data.status

          raise RuntimeError("unreachable")


      if __name__ == "__main__":
          print(json.dumps(capture_authorization(), indent=2))
      ```
    </CodeGroup>

    If the call times out, see [Handle timeouts and unknown outcomes](/payments-api/handle-failures/timeouts-and-unknown-outcomes). If it fails with a window, amount, or expiry error, see [Handle capture failures](/payments-api/handle-failures/capture-failures).
  </Step>
</Steps>

## 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).

| Status | Meaning | What to do |
| - | - | - |
| `AUTHORIZED` | Funds reserved (authorize only) | Capture within the capture window, or void to release |
| `CAPTURED` | Funds captured (purchase, capture, or refund) | Fulfil the order (or process the refund) |
| `VOIDED` | Authorization released | No funds moved |
| `DECLINED` | Issuer or acquirer declined | Final for this attempt — don't retry the same card without a new attempt from the shopper |
| `FAILED` | The transaction didn't complete — the acquirer returned a non-decline error code, or the gateway couldn't place the request. **Not a guarantee that no funds moved** — `VOIDED` and `REVERSED` are the only statuses that positively assert that. | Confirm via `GET /v1/transactions/{id}/status` before retrying, then retry (a genuinely new attempt, not a replay of the same `request_id`) with a **new** `request_id` |
| `PENDING` | Outcome not yet known (async) | Wait for a webhook, or poll `GET /v1/transactions/{id}/status` |
| `AUTH_EXPIRED` | Authorization lapsed before capture | Create a new authorization |
| `REVERSAL_PENDING` / `REVERSED` | Automatic compensating reversal after an upstream timeout left the outcome genuinely unknown (never left `FAILED` in this case) | No merchant action; webhook confirms the final state |

| Key | Used by | On replay |
| - | - | - |
| `request_id` | Purchase, authorize, standalone and referenced refunds | Same body, same operation type → the original transaction, whatever its status — including `PENDING`, `DECLINED`, or `FAILED`. Changed body, or the same key reused for a different operation type → [`transaction:idempotency-body-mismatch`](/payments-api/errors/payment-operation-errors#transaction-idempotency-body-mismatch). Purchase/authorize/standalone-refund compare `amount`, `currency`, `payment_method_type`, `channel`, the card's `pan_prefix` (first 8 digits — not the full token), `metadata`, and `order_reference`; a **referenced refund** compares only the original transaction and `amount` (`reason` isn't compared) and its replay check runs before the refund gates, so it always replays, even a `DECLINED`/`FAILED` one — mint a **new** `request_id` to retry after a decline. None of these compare `three_ds` or `loyalty`, so changing either on a retry replays the original silently instead of failing. |
| `operation_id` | Capture, void | Same operation type on the same transaction → the original result (body is never compared, so a changed amount is silently ignored). A different operation type reusing the key → [`tx:duplicate-operation`](/payments-api/errors/payment-operation-errors#tx-duplicate-operation). |

<Warning>
  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`.
</Warning>

<Tip>
  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](/get-started/api-basics/prevent-duplicate-payments).
</Tip>

`PENDING` means the outcome isn't known yet — most often after a processor timeout. Don't assume success or failure. Recover it one of two ways:

1. **Wait for a webhook** (`payment.*`, `authorization.*`, `refund.*` — see [Webhook event types](/payments-api/webhooks/event-types)).
2. **Call `GET /v1/transactions/{id}/status`** for a live inquiry against the acquirer.

If you don't have the transaction `id` yet — a client-side timeout before the first response arrived — replay the same request with the same `request_id` and body. The replay returns the stored transaction and its `id`, whatever status it's reached. Never re-submit with a **new** idempotency key just because the first attempt is slow — that risks a second charge for the same order.

Capture responses are `200`, including retries — a replayed capture with the same `operation_id` returns the same `200` result as the first attempt. On a network timeout or `5xx`, retry with the **same** `operation_id`; never mint a new one for the same capture attempt.

<Note>
  `operation_id` replays never compare the request body. A retry with the same `operation_id` returns the original captured result **even if the `amount` you sent this time is different** — the original amount wins, silently. Use a new `operation_id` for a genuinely new operation. Reusing a capture's `operation_id` for a void on the same transaction is rejected with `409 urn:radiumone:tx:duplicate-operation`, not treated as a replay.
</Note>

## Errors

Full HTTP status and meaning for each of these is defined once on [Problem format and retries](/payments-api/errors/problem-format-and-retries) — this list is only the capture-specific nuance:

* [`tx:capture-window-expired`](/payments-api/errors/payment-operation-errors#tx-capture-window-expired) — the authorization moves to `AUTH_EXPIRED`
* [`tx:capture-amount-mismatch`](/payments-api/errors/payment-operation-errors#tx-capture-amount-mismatch) — must equal the authorized amount exactly (see [Full-capture rule](#full-capture-rule))
* [`tx:currency-mismatch`](/payments-api/errors/payment-operation-errors#tx-currency-mismatch)
* [`gateway:validation-error`](/payments-api/errors/payment-operation-errors#gateway-validation-error)
* [`tx:duplicate-operation`](/payments-api/errors/payment-operation-errors#tx-duplicate-operation) — the same `operation_id` reused for a different operation on this transaction (e.g. a void)

## Webhook

A successful capture emits `payment.captured`. A capture that fails at the acquirer emits `authorization.capture_declined` or `authorization.capture_failed` — see [Webhook event types](/payments-api/webhooks/event-types).

## Test your integration

See [Test your integration](/resources/test-your-integration#capture) for capture-window and decline scenarios.

## Go-live notes

* Capture as soon as you can fulfil — don't hold authorizations open longer than necessary.
* Retry a timed-out capture with the same `operation_id`; check `GET /v1/transactions/{id}/status` if you're unsure whether it went through.
* Review the full [go-live checklist](/resources/go-live-checklist).

## Next steps

<Columns cols={2}>
  <Card title="Payment lifecycle" icon="repeat" href="/payments-api/payment-lifecycle">
    See how capture fits into the full transaction lifecycle.
  </Card>

  <Card title="Void a payment" icon="rotate-ccw" href="/payments-api/void">
    Release funds instead of capturing them.
  </Card>
</Columns>