How to use currencies
1
List the currencies your outlet accepts
At setup, or when you build a checkout, call
GET /v1/merchant/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.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 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.
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.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.6
Treat currency refusals as permanent
422 currency:unknown-currency
and 422 currency:minor-units-not-supported
both carry retry_allowed: false. Fix the currency; don’t retry the same
request. See What is refused.Request shapes
Response fields
- Transactions, sessions, and balance inquiries return integer amounts in
minor units with
currencyandcurrency_minor_units. - Session create also returns
allowed_currency_details: one{code, minor_units}entry per currency inallowed_currencies, in the same order. Use it to format and parse amounts. - Settlement batches carry two currencies, so they return
presented_currency_minor_unitsandsettlement_currency_minor_units. See Retrieve a settlement batch. - 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. - Webhooks state amounts as
{currency, value, minor_units}, withvaluea minor-units numeric string:{"currency": "SGD", "value": "12000", "minor_units": 2}is SGD 120.00. See Webhook event types.
Read the currency lists
Both lists use the standard success envelope. Each entry indata.items has
the same shape:
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_idisnullwhen 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
403auth:outlet-binding-violationfor any other outlet. An outlet that doesn’t exist returns404checkout:outlet-not-found. - Reading it needs the
payment-gateway:merchant-config-readscope. - A currency that RadiumOne can’t process is left out of the list, because every request in it would be refused.
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
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. - Not an active ISO 4217 currency (an unknown, fund, or withdrawn code):
422, see Unknown currency. - Valid ISO 4217 currency whose minor units aren’t 2, for example
JPYorKWD:422, see Minor units not supported. - Supported currency that isn’t enabled for your merchant account or outlet:
422, see Currency not supported and Currency not allowed. Use a currency fromGET /v1/merchant/currencies, or contact support to enable it.
Next steps
Charge or authorize a payment
Send your first amount in minor units.
List your enabled currencies
The full API reference for
GET /v1/merchant/currencies.