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

# Architecture - Payments API

> Where the Payments API sits between your server, the shopper's browser, and card networks, and the trust boundaries that protect keys and card data.

export const productionCheckoutHost = "https://checkout.radiumone.io";

export const sandboxCheckoutHost = "https://checkout-sandbox.radiumone.io";

export const productionApiBaseUrl = "https://api.radiumone.io/gateway";

export const sandboxApiBaseUrl = "https://api-sandbox.radiumone.io/gateway";

export const DataFlow = ({letter, from, to, twoWay, children}) => <div className="r1-flow" role="listitem">
    <span className="r1-flow__badge" aria-hidden="true">{letter}</span>
    <div className="r1-flow__content">
      <div className="r1-flow__title">
        <span className="r1-flow__sr-only">{`Flow ${letter}: `}</span>
        {from}
        <span className="r1-flow__arrow" aria-hidden="true">
          <Icon icon={twoWay ? "arrow-left-right" : "arrow-right"} size={14} />
        </span>
        <span className="r1-flow__sr-only">{twoWay ? " and back to " : " to "}</span>
        {to}
      </div>
      <div className="r1-flow__body">{children}</div>
    </div>
  </div>;

export const DataFlows = ({children}) => <div className="r1-flows" role="list">
    {children}
  </div>;

The Payments API is a single gateway your server calls to move money, and that
RadiumOne uses on your behalf to reach acquirers, card networks, issuers, and
the loyalty host. This page maps the pieces so the guides that follow make
sense in context — for the concepts inside a single request (transactions,
sessions, idempotency), see [Core concepts](/payments-api/core-concepts).

## How it works

### Components

* **Your server** — holds your secret key, exchanges it for an access token, calls the gateway.
* **Your webhook endpoint** — receives asynchronous outcome events.
* **Payments API gateway** — auth, sessions, transactions; the only thing your integration talks to directly.
* **RadiumOne Elements / Checkout** (optional) — browser surfaces that call the gateway with publishable-key-scoped tokens only.
* **Acquirer, network, issuer** — approve or decline the authorization (third parties).
* **UOB Rewards host** — checks a loyalty balance or redeems points.

### Data flows

The letters match the flow tags in the diagram.

<DataFlows>
  <DataFlow letter="A" from="Your server" to="Payments API gateway">
    Your server calls the Payments API with an access token, and sends a `request_id` with each payment so a retry never charges twice. See [Charge or authorize](/payments-api/charge-or-authorize).
  </DataFlow>

  <DataFlow letter="B" from="Shopper's browser" to="Payments API gateway">
    Elements or RadiumOne Checkout, running in the shopper's browser, tokenize the card or take the payment using a publishable key. See [Elements](/elements/overview) and [Hosted checkout](/hosted-checkout/overview).
  </DataFlow>

  <DataFlow letter="C" from="Payments API gateway" to="Acquirer">
    RadiumOne routes the authorization to the acquirer, which reaches the card network and the shopper's bank.
  </DataFlow>

  <DataFlow letter="D" from="Payments API gateway" to="UOB Rewards host">
    For UOB Rewards payments, RadiumOne checks the points balance or redeems points. See [UOB Rewards](/payments-api/payment-methods/uob-rewards/overview).
  </DataFlow>

  <DataFlow letter="E" from="Payments API gateway" to="Your webhook endpoint">
    RadiumOne sends a signed webhook for each outcome. Webhooks arrive asynchronously and at least once, so handle repeats. See [Webhooks](/payments-api/webhooks/overview).
  </DataFlow>
</DataFlows>

## Your server

Your server is the only place your secret key ever lives. It's responsible for:

* **Exchanging your secret key for an access token** before calling the gateway — see [Sandbox and API keys](/get-started/sandbox-and-api-keys#exchange-a-secret-key-for-an-access-token).
* **Generating a `request_id` or `operation_id`** for every create-type call, so a retry after a timeout never risks a duplicate charge — see [Idempotency with request IDs](/payments-api/core-concepts#3-idempotency-with-request-ids).
* **Hosting your webhook endpoint** — an HTTPS URL that receives asynchronous events and verifies their signature before trusting them — see [Webhooks](/payments-api/webhooks/overview).

<Danger>
  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.
</Danger>

## Optional browser components

Two RadiumOne surfaces run in the shopper's browser, and both call the
gateway on their own — you don't have to proxy their requests through your
server:

* **[RadiumOne Elements](/elements/overview)** renders secure card fields and tokenizes the card client-side, so raw card data never reaches your server.
* **[RadiumOne Checkout](/hosted-checkout/overview)** is a RadiumOne-hosted payment page (redirect or embedded) — the shopper enters their card there instead of on your site.

Either can be combined with [RadiumOne's built-in 3D Secure](/get-started/three-d-secure) or [your own 3DS provider](/payments-api/three-d-secure/use-your-own-provider). Both surfaces are scoped to publishable-key operations only (session creation and binding) — they can't create, capture, void, or refund a payment.

## What's inside the gateway

Every operation below is served from the same base URL:

| Environment | Payments API base URL | Checkout API host |
| - | - | - |
| Sandbox | <code>{sandboxApiBaseUrl}</code> | <code>{sandboxCheckoutHost}</code> |
| Production | <code>{productionApiBaseUrl}</code> | <code>{productionCheckoutHost}</code> |

| Capability | Guide |
| - | - |
| Auth and tokens — exchange, refresh, and revoke access tokens | [Authentication](/get-started/api-basics/authentication) |
| Sessions — tie a browser tokenization attempt to a specific charge | [Core concepts: sessions](/payments-api/core-concepts#2-sessions) |
| Transactions — purchase, authorize, capture, void, referenced refund, standalone refund | [Charge or authorize](/payments-api/charge-or-authorize) · [Capture](/payments-api/capture) · [Void](/payments-api/void) · [Refund](/payments-api/refund) · [Standalone refunds](/payments-api/standalone-refunds) |
| Payment methods — discover what an outlet can accept, check or redeem points | [Show payment methods at checkout](/payments-api/payment-methods/payment-method-discovery) · [UOB Rewards](/payments-api/payment-methods/uob-rewards/overview) |
| 3D Secure — RadiumOne's built-in 3DS through Elements, or your own provider (**Beta**, gated) instead | [3D Secure overview](/get-started/three-d-secure) · [Use your own provider](/payments-api/three-d-secure/use-your-own-provider) |
| Webhooks — asynchronous delivery, signing, and retries | [Webhooks](/payments-api/webhooks/overview) |
| Settlement batches — group captured funds and report batch status | [Settlement and reconciliation](/payments-api/settlement-and-reconciliation) |

## Acquirers, card networks, and issuers

The gateway routes each authorization to an acquirer, which in turn goes
through the relevant card network to the shopper's issuing bank. Acquirers,
networks, and issuers are third parties RadiumOne integrates with on your
behalf — your integration only ever talks to the gateway, and the gateway's
response (or the matching webhook) is the authoritative result. You never
call an acquirer or issuer directly.

## Loyalty host (UOB Rewards)

When a purchase includes a loyalty redemption, the gateway calls out to the
UOB Rewards loyalty host to check a points balance or redeem points against
the card residual. See [UOB Rewards overview](/payments-api/payment-methods/uob-rewards/overview) for the full flow, including [failures specific to redemption](/payments-api/handle-failures/rewards-redemption-failures).

## Trust boundaries

* **Secret keys never leave your server.** Every browser-facing surface (Elements, Checkout) uses a publishable key, which can only create and bind sessions — never charge, capture, void, or refund.
* **Card tokens, not raw card numbers.** Elements tokenizes the card in the browser; your server and RadiumOne's transaction records only ever see a token, not the PAN.
* **Webhook payloads are signed.** Verify `X-RadiumOne-Signature` against the raw request body before you trust anything in a webhook — see [Verify webhook signatures](/payments-api/webhooks/verify-signatures).

## Next steps

<Columns cols={2}>
  <Card title="Core concepts" icon="lightbulb" href="/payments-api/core-concepts">
    Transactions, sessions, idempotency, and the other ideas you'll use in every request.
  </Card>

  <Card title="Charge or authorize a payment" icon="credit-card" href="/payments-api/charge-or-authorize">
    Guides — start here to create your first purchase or authorization.
  </Card>

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

  <Card title="Security and PCI scope" icon="shield-check" href="/resources/security-and-pci">
    PCI scope per integration path.
  </Card>
</Columns>