Amounts and currencies
Monetary values are minor units, as a string of digits.
Every amount in the API is expressed in the currency's minor unit and sent as a string of digits. How many decimals a currency has determines what that string means.
| Currency | Decimals | String | Means |
|---|---|---|---|
| XAF | 0 | "11800" | 11,800 XAF |
| USD | 2 | "1200" | 12.00 USD |
Never send a float. No numeric JSON types, no locale separators. Monetary values are always integer strings.
Which fields the rule covers#
The rule applies to every monetary value in the API, not only to amount.value.
| Field | Minor units? |
|---|---|
amount.value | Yes |
charge.items[].unit_price, charge.items[].total | Yes |
charge.subtotal | Yes |
tax.amount | Yes |
Wallet available, pending, total_inward, total_outward | Yes |
Ledger amount, balance_before, balance_after | Yes |
tax.rate | No, a percentage |
One exception. tax.rate is a percentage, not money. It carries a decimal point, as in "18.00" for 18%. It is the only field on this page that does.
Why it works this way#
Floating point cannot represent most decimal money values exactly. Sending integer minor units as strings removes rounding differences between your system, ours and the provider's.
Currencies and wallets#
You hold one wallet per currency and balances are never mixed. See Wallets.
Maly Tech Ltd. This guide is provided for information. Where it differs from your signed agreement, the agreement applies.