Minor Units Format

Amount Format

Acme maintains a consistent format for amount values across all Acme APIs. All amount values provided in the API must be represented in their smallest currency unit as an integer.

The number of minor units per major unit follows the ISO 4217 standard.

• Most currencies have 2 decimal places. amount is in cents, so multiply the major amount by 100.
• Some currencies have no minor unit (0 decimal places). amount equals the major amount.
• A small set of currencies have 3 decimal places. amount is in thousandths, so multiply the major amount by 1000.

Examples

Currency	Decimal Places	Example Amount	Smallest Unit (ISO 4217 standard)	API Value
SGD	2	$10.00	cents	1000
USD	2	$10.00	cents	1000
EUR	2	€10.00	cents	1000
JPY	0	¥10	yen	10
VND	0	₫10	dong	10
KWD	3	KD 10.000	fils	10000

Currencies with no minor unit (0 decimal places)

For these currencies, send amount as the whole major amount. Do not multiply by 100.

For example, send 1000 for JPY ¥1,000.

Code	Currency
BIF	Burundian Franc
CLP	Chilean Peso
DJF	Djiboutian Franc
GNF	Guinean Franc
ISK	Icelandic Króna
JPY	Japanese Yen
KMF	Comorian Franc
KRW	South Korean Won
PYG	Paraguayan Guaraní
RWF	Rwandan Franc
UGX	Ugandan Shilling
VND	Vietnamese Dong
VUV	Vanuatu Vatu
XAF	Central African CFA Franc
XOF	West African CFA Franc
XPF	CFP Franc

Currencies with 3 decimal places

For these currencies, send amount in thousandths. Multiply the major amount by 1000.

For example, send 10500 for KWD 10.500.

Code	Currency
BHD	Bahraini Dinar
IQD	Iraqi Dinar
JOD	Jordanian Dinar
KWD	Kuwaiti Dinar
LYD	Libyan Dinar
OMR	Omani Rial
TND	Tunisian Dinar

All other currencies use 2 decimal places. Send amount in cents by multiplying the major amount by 100.

Decimal places follow the ISO 4217 scale

The number of decimal places is set by the ISO 4217 standard, not by the smallest physical coin or note in circulation.

For example, the smallest New Taiwan Dollar (TWD) coin is NT$1, but ISO 4217 assigns TWD 2 decimal places. So TWD is a 2 decimal place currency for the API.

• Send 1000 for NT$10.00.
• Send 1050 for NT$10.50.

Important

• You must convert major currency units to the smallest unit before sending to Acme (e.g. send 1050 for SGD $10.50).
• All amounts will be returned in the smallest unit. Your system must convert these back to major units if needed for display.
• Amounts must not include decimal points. Submissions with decimal points (e.g. 10.50) will be rejected.

{
  "amount": 1050,
  "currency": "SGD"
}