# Currencies & amount format

Supported currencies, minor units, zero-decimal rules, min/max.

# Currencies & amount format

All `amount` fields in the Southbill API are **integers in the smallest currency unit** (minor units), following the ISO 4217 exponent for that currency.

## Amount format

| Currency type | Example | 10.00 → integer |
|---|---|---|
| 2-decimal (most currencies) | EUR, USD, GBP, CHF, CAD, AUD, SEK, NOK, DKK, PLN, CZK, RON, BGN | `1000` |
| 0-decimal (zero-decimal) | JPY, KRW, VND, CLP, ISK, HUF | `10` |
| 3-decimal | BHD, JOD, KWD, OMR, TND | `1000` = 1.000 |

Send integers only. `10.5` or `"10.00"` are rejected with `invalid_request`.

## Supported currencies

Currencies accepted on `POST /v1/checkout/sessions`:

`eur`, `usd`, `gbp`, `chf`, `sek`, `nok`, `dkk`, `pln`, `czk`, `ron`, `bgn`, `huf`, `cad`, `aud`, `nzd`, `jpy`, `sgd`, `hkd`.

Always lowercase 3-letter ISO. Currencies outside this list return `400 invalid_request` (`currency_unsupported`).

### Payment method coverage

Not every method supports every currency. Southbill automatically hides methods at checkout that the currency does not support (e.g. Klarna is EU-only, iDEAL is EUR-only, Bancontact is EUR-only).

## Minimum and maximum

- **Minimum**: 2.50 EUR equivalent (e.g. `250` in EUR/USD/CHF, `300` in JPY). Below this: `400 amount_too_small`.
- **Maximum per charge**: 999,999.99 in the transaction currency. Above this: `400 amount_too_large`.

See **Fees, currency & minimum amounts** for the reasoning behind the minimum.

## Payout currency

Merchants are paid out in their onboarding currency (usually EUR or CHF). Charges in other currencies are converted at the daily FX rate with a +2.00% FX surcharge.