ISO 4217 Currency Code Validator

ISO 4217: the international currency code standard

ISO 4217 is the international standard that assigns three-letter and three-digit codes to every currency recognized by central banks, including precious metals, supranational currencies and historical units. It is maintained by SIX Interbank Clearing on behalf of ISO and updated whenever a country issues a new currency, redenominates an existing one, or joins a monetary union like the Eurozone. Every payment gateway, FX feed and accounting ERP keys on ISO 4217.

The format mirrors ISO 3166-1: a three-letter alphabetic code (e.g. BRL, USD, EUR, JPY, GBP, CNY) where the first two letters usually match the country's ISO 3166-1 alpha-2, plus a three-digit numeric code (986 BRL, 840 USD, 978 EUR, 392 JPY) used in EDI, SWIFT messages and banking systems that prefer numeric identifiers.

The minor unit: decimal places vary by currency

A critical detail ISO 4217 publishes for every currency is the number of decimal places (minor units):

• 2 decimals (the norm): USD, EUR, BRL, GBP, CAD. 1.00 USD = 100 cents.
• 0 decimals: JPY (Japanese yen) has no sub-units. 1 JPY = smallest amount. KRW, CLP, VND follow the same rule.
• 3 decimals: BHD (Bahraini dinar, 1000 fils), KWD (Kuwaiti dinar), OMR (Omani rial), TND (Tunisian dinar). 1 BHD = 1000 fils.
• 4 decimals (rare): CLF (Unidad de Fomento, indexed unit in Chile).

Hard-coding "100 cents" everywhere is the most common bug in international billing. Stripe, Adyen and Mercado Pago all expose currency-aware minor unit helpers — use them. In Java, java.util.Currency.getDefaultFractionDigits() returns the correct value.

Historic and deprecated codes

ISO 4217 keeps an active list and a separate historic list. Codes you still see in legacy systems:

• DEM Deutsche Mark — replaced by EUR in 2002.
• FRF French franc — replaced by EUR in 2002.
• ITL Italian lira — replaced by EUR in 2002.
• SUR Soviet ruble — extinct with the USSR in 1991.
• TRL old Turkish lira — replaced by TRY in 2005 (six zeros dropped).
• CRZ Brazilian cruzeiro — succeeded by BRL in 1994 (Plano Real).
• ZWD, ZWN, ZWR, ZWL — successive Zimbabwean dollars, each a re-denomination after hyperinflation.

Cryptocurrencies and the X- prefix

ISO 4217 reserves codes starting with X for supranational and non-country units: XAU (gold), XAG (silver), XPT (platinum), XDR (IMF special drawing rights), XOF / XAF (CFA francs). Bitcoin is not in ISO 4217. An informal proposal of XBT circulated and Kraken, Bitstamp and some Bloomberg feeds adopted it, but BTC remains the de-facto market ticker. Ethereum, USDT, USDC etc. are entirely outside ISO 4217 — never assume an FX library will recognize them.

Formatting currency with Intl.NumberFormat

Modern browsers and Node ship the ECMAScript Intl API that handles ISO 4217 formatting natively:

new Intl.NumberFormat('pt-BR', { style: 'currency', currency: 'BRL' })
  .format(1234.56) // "R$ 1.234,56"
new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' })
  .format(1234.56) // "$1,234.56"
new Intl.NumberFormat('ja-JP', { style: 'currency', currency: 'JPY' })
  .format(1234.56) // "¥1,235" (no decimals)
new Intl.NumberFormat('ar-BH', { style: 'currency', currency: 'BHD' })
  .format(1234.567) // "BHD 1,234.567" (3 decimals)

Why you should always store the ISO code, never the symbol

The dollar sign $ is ambiguous: it stands for USD, CAD, AUD, NZD, SGD, HKD, MXN, ARS and dozens of others. kr covers SEK, NOK, DKK and ISK. £ covers GBP, EGP, SYP and others. Always persist the ISO 4217 code in your database and render the symbol via Intl.

Brazilian Real (BRL): a short history

The BRL (numeric 986, "Real") was introduced on 1 July 1994 by the Plano Real, the stabilization plan that ended decades of hyperinflation. It replaced the CRZ (Cruzeiro) at a parity built through the URV (Unidade Real de Valor). Predecessors include CRB (Cruzeiro novo), CRZ and earlier units that had successive zeros dropped during the 1980s. Brazilian display convention uses comma as decimal separator and dot as thousand separator: R$ 1.234,56.

Libraries and FX data providers

• JavaScript: currency-codes, iso-4217, dinero.js.
• Python: pycountry, money, iso4217.
• Java: java.util.Currency.
• FX data: Open Exchange Rates, Fixer.io, currencylayer, ExchangeRate-API — all keyed on ISO 4217.
• Brazil-specific: PTAX from the Banco Central do Brasil exposes BRL crosses against the main currencies.

FAQ

Does Bitcoin have an ISO 4217 code?

No. Bitcoin is not recognized as a sovereign currency by ISO 4217. The XBT code has been proposed and a few exchanges adopted it but it is not standardized. Most trading systems still use the non-ISO BTC.

How many decimals does the Japanese yen have?

Zero. JPY has no sub-units, so 1 JPY is the smallest amount. Storing yen amounts with decimals is a frequent bug in cross-currency systems. Korean won (KRW), Vietnamese dong (VND) and Chilean peso (CLP) behave the same way.

When does a currency code change?

Most commonly during hyperinflation redenominations (Turkish TRL -> TRY, Brazilian CRZ -> BRL, multiple Zimbabwean cycles), monetary unions (twelve Eurozone codes retired in 2002) or political changes (USSR dissolution dropped SUR).

Is the dollar sign safe to display alone?

Not in multi-currency contexts. $ can mean USD, CAD, AUD, MXN and many others. Always store the ISO 4217 code and let Intl.NumberFormat render the correct symbol for the user's locale.