Zero-Decimal Currency

How Stripe writes an amount

Stripe’s currencies page sets the rule for the whole API: “Currencies are two-decimal currencies unless otherwise specified. All API requests expect amount values in the currency’s minor unit.” Its two examples sit side by side: 1000 to charge 10 USD, and 10 to charge 10 JPY.

The Charge object repeats it in the field description, where amount is “A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency).” The same convention runs through the objects a bookkeeper actually reconciles from. On a balance transaction, Stripe describes amount as the “Gross amount of this transaction (in the smallest currency unit)”, and the fee and net fields use the same unit.

So the integer on its own tells you nothing. 5000 is 50.00 if the currency field says usd and 5,000 if it says jpy. Every conversion has to read the currency field on the same object before it decides what to divide by.

The full list, and the four special cases

Stripe’s zero-decimal list, as published on its currencies page, is: BIF (Burundian franc), CLP (Chilean peso), DJF (Djiboutian franc), GNF (Guinean franc), JPY (Japanese yen), KMF (Comorian franc), KRW (South Korean won), MGA (Malagasy ariary), PYG (Paraguayan guaraní), RWF (Rwandan franc), UGX (Ugandan shilling), VND (Vietnamese đồng), VUV (Vanuatu vatu), XAF (Central African CFA franc), XOF (West African CFA franc) and XPF (CFP franc). Stripe adds that the list “contains zero-decimal currencies that have general API support” and that some might not be available in your specific country.

Four currencies sit in a separate special cases table, and they are where hand-written converters usually go wrong.

Icelandic króna (ISK) and Ugandan shilling (UGX). Stripe’s entry for ISK says it “transitioned to a zero-decimal currency, but backward compatibility requires you to represent it as a two-decimal value, where the decimal amount is always 00,” and the UGX entry says the same. Stripe’s example: to charge 5 ISK, provide an amount value of 500. You cannot charge fractions of either. ISK is not on the zero-decimal list, so a converter that divides it by 100 gets the right answer. UGX appears both on the list and in this table, and the table is the more specific of the two. A converter that skips the division for every currency on the list will overstate UGX by 100 times, so build to the special-case rule and confirm it with a test-mode charge.

Hungarian forint (HUF) and New Taiwan dollar (TWD). These run the other way. Stripe “treats HUF as a zero-decimal currency for payouts, even though you can charge two-decimal amounts,” and says the same of TWD. When you create a manual payout in either, the amount must be an integer evenly divisible by 100. Stripe’s example: with an available balance of HUF 10.45 you can pay out HUF 10 by submitting 1000, but you cannot submit a payout for the full HUF 10.45, because 1045 is not evenly divisible by 100. The fractional part cannot leave in that payout, which is worth knowing before you expect a HUF balance to reconcile to zero.

Rounding: the one rule Stripe spells out

The rounding rule on Stripe’s currencies page is specific to UGX invoices. For invoices where the amount is fractional after prorations, coupons or taxes, Stripe “automatically rounds that amount to the nearest number evenly divisible by 100,” and adds: “We credit or debit any difference from rounding to the customer balance.”

That second sentence is the bookkeeping consequence. The invoice total no longer equals the sum of its lines to the last shilling, and the difference does not disappear. It sits on the Stripe customer balance. If you rebuild invoice totals from line items in a spreadsheet, a small persistent gap on UGX customers is this rule working as designed, not a sync error.

Where the 100x error comes from

Almost every zero-decimal problem is one of three mistakes.

The first is the blanket divisor. A script, an import template or a spreadsheet built from API values divides every amount by 100 because that is what worked for the first currency the business sold in. A ¥5,000 sale arrives as amount 5000 and is booked as ¥50. The same thing happens to every fee and refund in that currency, so the error is consistent and easy to miss on any one record.

The second runs in the charge direction. Code that multiplies every price by 100 before creating a PaymentIntent turns a ¥5,000 product into a ¥500,000 charge, because Stripe takes 500000 at face value for yen. That one shows up as a customer complaint rather than a reconciliation gap, but the refund and the corrected charge both land in your books.

The third is a cross-currency sale. If a customer pays ¥5,000 and your Stripe balance is in USD, the charge amount is in yen and the balance transaction amount, fee and net are in US cents. Stripe’s balance transaction documentation describes this conversion with an exchange_rate on the balance transaction. One sale, two objects, two different divisors. The divisor belongs to the currency field on each object, never to the account or the business.

The quick test for all three: pick one recent charge in each currency you sell in, and compare the amount shown on the payment in the Stripe Dashboard with the amount on the matching QuickBooks record. A difference of exactly 100 times is a unit conversion error. A difference of a few percent is an exchange rate question, which is a different problem.

What the error looks like in QuickBooks Online

With Multicurrency turned on, QuickBooks Online lets you enter a transaction in a foreign currency and converts it to your home currency for you. Intuit defines the exchange rate as the number of home currency units it takes to get to 1 foreign currency unit. A yen sale on a US dollar file therefore carries a small rate, and the home currency value is the yen amount times that rate.

That is why a 100x unit error survives conversion intact. If ¥5,000 is entered as ¥50, QuickBooks applies a correct rate to the wrong amount, and the home currency value is 100 times too small as well. The home currency figure understates the sale by 99 percent.

The payout side is where it surfaces. The payout reaches your bank as the real converted amount, so whichever account you use to hold Stripe money between sale and payout no longer clears. The leftover is roughly 99 percent of that period’s yen sales at the rate Stripe converted them at. A gap of that shape, concentrated in one currency, is the signature of a divisor problem. An exchange gain or loss is usually a small fraction of the sale, not almost all of it.

Setting up QuickBooks before the first yen sale

If you plan to record zero-decimal sales in their own currency, the QuickBooks decisions come first, because several of them are permanent according to Intuit.

Multicurrency itself cannot be turned off once it is on. Your home currency can only be changed while Multicurrency is not yet enabled. Each customer, vendor and most account types carry a single currency, so a customer you already bill in US dollars needs a separate customer record to be billed in yen, and once an account has a transaction posted to it, its currency can no longer be changed.

QuickBooks fills in exchange rates automatically and lets you enter your own on a transaction. Neither helps with a unit error, which is why the amount conversion from Stripe’s integer needs to be correct before anything reaches QuickBooks. A practical order of work: confirm the divisor for each currency against Stripe’s list and special cases, run one test transaction per currency through to QuickBooks, check the foreign amount and the home currency amount on the resulting record, and only then turn on live sales in that currency.