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

# Settlement - Payments API

> How captured funds move through a settlement batch, the webhooks that report it, and how to reconcile against your own records.

Captured funds don't settle instantly — they're grouped into a settlement **batch** per terminal/outlet, sent to the acquirer, and settled as a group. Batch state is also what gates whether you [void or refund](/payments-api/void) a transaction.

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

## Batches

A batch moves through the same settlement stages a transaction reports: queued (`SUBMITTED`), in progress at the acquirer (`SETTLING`), and settled (`SETTLED`). While a batch is **open**, its transactions can still be voided; once it **closes**, only a referenced or standalone refund can return funds. See [Payment lifecycle](/payments-api/payment-lifecycle#settlement-stages) for the full state diagram.

## Settlement webhooks

Subscribe to `settlement.settled`, `settlement.rejected`, and `settlement.discarded` to track batch outcomes without polling. Each event's `data.batch` identifies the batch; correlate it with your transactions' own status changes. See [Webhook event types](/payments-api/webhooks/event-types) for the full payload shape.

## Retrieve a settlement batch

Look up a batch's status and totals by its reference when you need an authoritative read (for example, to reconcile a `settlement.rejected` event). This lookup is documented in the [API reference](/payments-api/reference/settlement/retrieve-settlement-batch).

<CodeGroup>
  ```bash cURL theme={null}
  #!/usr/bin/env bash
  # Beta. Fetch a settlement batch's status and totals by reference.
  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 with the settlement-read scope}"
  : "${RADIUMONE_SETTLEMENT_REFERENCE:?set RADIUMONE_SETTLEMENT_REFERENCE to the batch reference}"

  curl -sS "$API_BASE/v1/settlement/$RADIUMONE_SETTLEMENT_REFERENCE" \
    -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  #!/usr/bin/env node
  // Beta. Fetch a settlement batch's status and totals by reference. Node 18+
  // ESM fetch. Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_SETTLEMENT_REFERENCE, RADIUMONE_API_BASE.
  const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
  const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;
  const reference = process.env.RADIUMONE_SETTLEMENT_REFERENCE;

  async function retrieveSettlementBatch() {
    const res = await fetch(`${API_BASE}/v1/settlement/${reference}`, {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
    const payload = await res.json();
    if (!res.ok) {
      throw new Error(`settlement fetch failed: ${payload.type ?? payload.code} (${res.status})`);
    }
    return payload;
  }

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

  ```python Python theme={null}
  #!/usr/bin/env python3
  """Beta. Fetch a settlement batch's status and totals by reference."""
  import json
  import os

  import requests

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


  def retrieve_settlement_batch() -> dict:
      reference = os.environ["RADIUMONE_SETTLEMENT_REFERENCE"]
      resp = requests.get(
          f"{API_BASE}/v1/settlement/{reference}",
          headers={"Authorization": f"Bearer {os.environ.get('RADIUMONE_ACCESS_TOKEN', '')}"},
          timeout=30,
      )
      payload = resp.json()
      if not resp.ok:
          code = payload.get("type") or payload.get("code")
          raise RuntimeError(f"settlement fetch failed: {code} ({resp.status_code})")
      return payload


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

## Reconciliation tips

* Reconcile by **batch reference**, not by settlement date alone — a batch can span or shift across calendar days depending on cutoff timing.
* Treat `settlement.rejected` and `settlement.discarded` as exceptions requiring investigation, not just log entries — funds you expected to settle didn't.
* Cross-check your own transaction totals against the batch totals returned above; a mismatch is worth investigating before you close your books for the period.
* Remember that a transaction's `amount` on a loyalty-split sale reflects only the card residual, not the gross order total — reconcile against the right figure.

## Go-live notes

* Register a webhook endpoint before you go live so settlement outcomes reach you without polling.
* Build an alert for `settlement.rejected`/`settlement.discarded` — these need a human, not just a log line.
* Review the full [go-live checklist](/resources/go-live-checklist).

## Next steps

<Columns cols={2}>
  <Card title="Retrieve a settlement batch" icon="landmark" href="/payments-api/reference/settlement/retrieve-settlement-batch">
    Full reference for the batch-status lookup.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/payments-api/webhooks/overview">
    Set up your endpoint and verify signatures.
  </Card>
</Columns>