Countries & fiat currencies

BOSPay supports more than ZAR. Set fiatCurrency on each invoice or checkout session to price an order in the merchant's chosen currency. The customer still pays the selected on-chain asset, and the merchant receives that asset. Quoting EUR or USD does not create a bank payout or a fiat balance.

Countries by continent

Use the tables below to find local currency codes such as ZAR for South Africa, USD for the United States and EUR for euro-area countries. Shared currencies appear beside every relevant country or territory. You can quote a listed currency without limiting your checkout to the place shown.

Discover support

Call GET /currencies to populate your currency selector. The catalogue combines CoinMarketCap's fiat support with active ISO 4217 monetary codes and the precision BOSPay can represent. Precious metals, withdrawn codes and fund units with unsupported precision are excluded. Do not hard-code a country list or assume every currency is available.

const response = await fetch(`${process.env.BOSPAY_API_BASE}/currencies`, {
  method: "GET",
  headers: {
    "Content-Type": "application/json",
    "BOSPay-Version": "2026-09-23",
    "X-API-Key": process.env.BOSPAY_API_KEY,
  }
});
if (!response.ok) {
  throw new Error(`BOSPay request failed: ${response.status}`);
}
const data = await response.json();

Amounts and precision

Send fiatAmount as a JSON number between 0.01 and 1,000,000,000, respecting data[].decimals. BOSPay stores and calculates amounts using exact decimal arithmetic. Network and token availability remain separate: use GET /networks and registered receiving destinations to choose the payment asset.

curl -X POST "$BOSPAY_API_BASE/checkout-sessions" \
  -H "X-API-Key: $BOSPAY_SECRET_KEY" \
  -H "BOSPay-Version: 2026-09-23" \
  -H "Content-Type: application/json" \
  -d '{"fiatAmount":50.25,"fiatCurrency":"EUR","restrictNetworks":["sepolia"],"reference":"order-eur-1048"}'

Availability and freshness

The catalogue refreshes every six hours per API instance. During an outage a last-known-good catalogue can be used for up to 24 hours; cached will be true after the normal refresh interval. New active ISO currencies returned by CoinMarketCap are included on refresh. Newly introduced ISO codes require a reviewed snapshot update.

Market quotes cache for up to 60 seconds, and provider timestamps older than five minutes are rejected. A fresh cached price can bridge a provider outage only within that limit. A currency being listed does not guarantee every asset has a usable quote at that moment. BOSPay returns 503 when it cannot quote safely, rather than creating an invoice using an expired rate. Existing invoices retain their original quote.

Unsupported fiatCurrency returns 400 validation_error with field fiatCurrency before a new invoice or session is created. Use a currency returned by the catalogue. Catalogue or pricing outages return 503; retry with backoff and the same Idempotency-Key where the endpoint supports it. Do not create a second order to work around a timeout.

GET /currencies accepts secret, restricted and publishable keys with read:currencies. Existing keys with read:networks or read:invoices also retain discovery access. Keep secret keys on your server.

Currencies endpoint →