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

# Currencies and amounts - Payments API

> Find which currencies your outlet accepts, send amounts as integers in minor units, and format them using the minor units RadiumOne returns.

Every amount you send to or receive from the Payments API is an integer count
of the currency's minor units. This page shows you how to find which
currencies your outlet accepts, how to state amounts, and how to read a
currency's minor units from RadiumOne instead of keeping your own table.

> [!WARNING]
>
> **Only currencies with 2 minor units are supported today.** A valid ISO 4217
> currency with 0 or 3 minor units (for example `JPY` or `KWD`) is refused
> with `422`
> [`urn:radiumone:payment-gateway:currency:minor-units-not-supported`](https://docs.radiumone.io/payments-api/errors/payment-operation-errors#currency-minor-units-not-supported).
> Don't hard-code which currencies or scales are accepted — read them from the
> API as described below, so your integration keeps working when support
> widens.

## How to use currencies

**1. List the currencies your outlet accepts**

At setup, or when you build a checkout, call
[`GET /v1/merchant/currencies`](https://docs.radiumone.io/payments-api/reference/currencies/list-your-enabled-currencies)
with your access token. Pass `outlet_id` to ask about a specific outlet;
omit it to use your default outlet. Offer your shoppers only the
currencies in this list.

```bash cURL theme={null}
#!/usr/bin/env bash
# List the currencies enabled for your outlet (default outlet when outlet_id is
# omitted), default currency first, each with its minor units.
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 "$API_BASE/v1/merchant/currencies" \
  -H "Authorization: Bearer $RADIUMONE_ACCESS_TOKEN"
```

```javascript Node.js theme={null}
#!/usr/bin/env node
// List the currencies enabled for your outlet (default outlet when outlet_id is
// omitted), default currency first, each with its minor units. Node 18+ ESM fetch.
// Env: RADIUMONE_ACCESS_TOKEN, RADIUMONE_API_BASE.
const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;

async function listMerchantCurrencies(outletId) {
  const query = outletId ? `?${new URLSearchParams({ outlet_id: outletId })}` : "";
  const res = await fetch(`${API_BASE}/v1/merchant/currencies${query}`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const payload = await res.json();
  if (!res.ok) {
    throw new Error(`merchant currencies failed: ${payload.type ?? payload.code} (${res.status})`);
  }
  return payload;
}

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

```python Python theme={null}
#!/usr/bin/env python3
"""List the currencies enabled for your outlet (default outlet when outlet_id is
omitted), default currency first, each with its minor units.
"""
import json
import os
from typing import Optional

import requests

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


def list_merchant_currencies(outlet_id: Optional[str] = None) -> dict:
    resp = requests.get(
        f"{API_BASE}/v1/merchant/currencies",
        params={"outlet_id": outlet_id} if outlet_id else None,
        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"merchant currencies failed: {code} ({resp.status_code})")
    return payload


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

**2. Send every amount as an integer in minor units**

`SGD` has 2 minor units, so SGD 10.50 is `1050`. Never send a decimal.
See [Request shapes](#request-shapes) for where the amount goes on each
call.

**3. Format amounts for display from the response**

Transaction, session, balance inquiry and settlement responses carry
`currency_minor_units` beside `currency` (payment method discovery
responses don't). Divide the amount by 10 to the power of
`currency_minor_units` to get the major-unit value: `1050` with
`currency_minor_units: 2` displays as `10.50`.

**4. Validate codes against the public list**

To validate a currency code or build a currency picker, call
[`GET /v1/currencies`](https://docs.radiumone.io/payments-api/reference/currencies/list-supported-currencies).
It needs no access token and lists every currency RadiumOne supports. It
doesn't tell you which currencies **your** outlet accepts — use
`GET /v1/merchant/currencies` for that.

```bash cURL theme={null}
#!/usr/bin/env bash
# List every currency RadiumOne supports, with its ISO 4217 minor units.
# Public: no access token needed. Send the ETag back in If-None-Match to get 304.
set -euo pipefail

API_BASE="${RADIUMONE_API_BASE:-https://api-sandbox.radiumone.io/gateway}"

curl -sS "$API_BASE/v1/currencies"
```

```javascript Node.js theme={null}
#!/usr/bin/env node
// List every currency RadiumOne supports, with its ISO 4217 minor units.
// Public: no access token needed. Node 18+ ESM fetch.
// Env: RADIUMONE_API_BASE.
const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";

async function listCurrencies() {
  const res = await fetch(`${API_BASE}/v1/currencies`);
  const payload = await res.json();
  if (!res.ok) {
    throw new Error(`currencies failed: ${payload.type ?? payload.code} (${res.status})`);
  }
  return payload;
}

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

```python Python theme={null}
#!/usr/bin/env python3
"""List every currency RadiumOne supports, with its ISO 4217 minor units.
Public: no access token needed.
"""
import json
import os

import requests

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


def list_currencies() -> dict:
    resp = requests.get(f"{API_BASE}/v1/currencies", timeout=30)
    payload = resp.json()
    if not resp.ok:
        code = payload.get("type") or payload.get("code")
        raise RuntimeError(f"currencies failed: {code} ({resp.status_code})")
    return payload


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

**5. Cache both lists with their ETag**

Store the `ETag` from each response and send it back in an
`If-None-Match` header. An unchanged list answers `304 Not Modified` with
no body. See [Cache the currency lists](#cache-the-currency-lists).

**6. Treat currency refusals as permanent**

`422` [`currency:unknown-currency`](https://docs.radiumone.io/payments-api/errors/payment-operation-errors#currency-unknown-currency)
and `422` [`currency:minor-units-not-supported`](https://docs.radiumone.io/payments-api/errors/payment-operation-errors#currency-minor-units-not-supported)
both carry `retry_allowed: false`. Fix the currency; don't retry the same
request. See [What is refused](#what-is-refused).

## Request shapes

| Call | Where the amount goes |
| - | - |
| [`POST /v1/sessions`](https://docs.radiumone.io/payments-api/reference/sessions/create-tokenization-session), [`PATCH /v1/sessions/{session_id}`](https://docs.radiumone.io/payments-api/reference/sessions/update-session-amount) | `amount` / `net_payable_amount` as a JSON integer in minor units, beside a top-level `currency` |
| [Purchase](https://docs.radiumone.io/payments-api/reference/payments/purchase.md), authorize, [standalone refund](https://docs.radiumone.io/payments-api/reference/refunds/standalone-refund.md) | Money object `amount: {currency, value}`, where `value` is a minor-units numeric **string** of up to 12 digits (`"1050"`, or zero-padded `"000000001050"`) |
| Capture, referenced refund | Same money object; `currency` must match the original transaction's currency |
| `POST /v1/3ds/authenticate` | No amount — the session's `net_payable_amount` and `currency` are what gets authenticated |

## Response fields

* **Transactions, sessions, and balance inquiries** return integer amounts in
  minor units with `currency` and `currency_minor_units`.
* **Session create** also returns `allowed_currency_details`: one
  `{code, minor_units}` entry per currency in `allowed_currencies`, in the
  same order. Use it to format and parse amounts.
* **Settlement batches** carry two currencies, so they return
  `presented_currency_minor_units` and `settlement_currency_minor_units`. See
  [Retrieve a settlement batch](https://docs.radiumone.io/payments-api/reference/settlement/retrieve-settlement-batch.md).
* **UOB Rewards vouchers** return `redeem_value_minor`, an integer in the sale
  currency's minor units. `redeem_value` (a decimal) is **deprecated** — see
  [Check a rewards balance](https://docs.radiumone.io/payments-api/payment-methods/uob-rewards/check-balance.md).
* **Webhooks** state amounts as `{currency, value, minor_units}`, with
  `value` a minor-units numeric string:
  `{"currency": "SGD", "value": "12000", "minor_units": 2}` is SGD 120.00. See
  [Webhook event types](https://docs.radiumone.io/payments-api/webhooks/event-types.md).

## Read the currency lists

Both lists use the standard success envelope. Each entry in `data.items` has
the same shape:

| Field | Type | Meaning |
| - | - | - |
| `code` | string | ISO 4217 alphabetic code, for example `SGD` |
| `numeric_code` | string | ISO 4217 numeric code as a 3-character string, leading zeros kept (`702`) |
| `minor_units` | integer | The currency's decimal places. Every amount is an integer count of these units |

### Your enabled currencies

`GET /v1/merchant/currencies` returns the currencies enabled for one of your
outlets, default currency first, plus the `outlet_id` the list applies to.
It's exactly the list that new sessions and sales accept for that outlet.
Follow-up calls such as capture and refund always use the original
transaction's currency.

* `outlet_id` is `null` when you have no default outlet and didn't name one;
  the list then applies to your merchant account as a whole.
* A key bound to an outlet gets `403`
  [`auth:outlet-binding-violation`](https://docs.radiumone.io/payments-api/errors/payment-operation-errors#auth-outlet-binding-violation)
  for any other outlet. An outlet that doesn't exist returns `404`
  [`checkout:outlet-not-found`](https://docs.radiumone.io/payments-api/errors/payment-method-errors#checkout-outlet-not-found).
* Reading it needs the `payment-gateway:merchant-config-read` scope.
* A currency that RadiumOne can't process is left out of the list, because
  every request in it would be refused.

> [!TIP]
>
> `data.items[0]` is your outlet's default currency — a sensible preselected
> value for a currency picker.

### Every supported currency

`GET /v1/currencies` is public: no access token, sorted by `code`. It's a
static reference list that changes only with a RadiumOne release. Use it to
validate a code before you send it, not to decide what your outlet accepts.

## Cache the currency lists

| List | `Cache-Control` | How to cache it |
| - | - | - |
| `GET /v1/currencies` | `public, max-age=3600, stale-while-revalidate=86400` | Cache it once for your whole application. A change reaches every cache within the hour |
| `GET /v1/merchant/currencies` | `private, max-age=300` (with `Vary: Authorization`) | Key your cache by credential — the list belongs to the merchant whose token asked |

Both responses carry a weak `ETag` (`W/"..."`). Send it back in
`If-None-Match`; when the list hasn't changed, you get `304` with no body and
the same `ETag` and `Cache-Control` headers.

## What is refused

None of these refusals is worth retrying unchanged. Fix the currency first:

* **Malformed code** (not 3 letters): `400`, see [Validation error](https://docs.radiumone.io/payments-api/errors/payment-operation-errors.md#gateway-validation-error).
* **Not an active ISO 4217 currency** (an unknown, fund, or withdrawn code): `422`, see [Unknown currency](https://docs.radiumone.io/payments-api/errors/payment-operation-errors.md#currency-unknown-currency).
* **Valid ISO 4217 currency whose minor units aren't 2**, for example `JPY` or `KWD`: `422`, see [Minor units not supported](https://docs.radiumone.io/payments-api/errors/payment-operation-errors.md#currency-minor-units-not-supported).
* **Supported currency that isn't enabled for your merchant account or outlet**: `422`, see [Currency not supported](https://docs.radiumone.io/payments-api/errors/payment-method-errors.md#checkout-currency-not-supported) and [Currency not allowed](https://docs.radiumone.io/payments-api/errors/payment-operation-errors.md#routing-currency-not-allowed). Use a currency from `GET /v1/merchant/currencies`, or [contact support](https://docs.radiumone.io/resources/support.md) to enable it.

## Next steps

> [card] [Charge or authorize a payment](https://docs.radiumone.io/payments-api/charge-or-authorize.md)
>
> Send your first amount in minor units.

> [card] [List your enabled currencies](https://docs.radiumone.io/payments-api/reference/currencies/list-your-enabled-currencies.md)
>
> The full API reference for `GET /v1/merchant/currencies`.


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