Skip to content
Enjoy complimentary data migration when switching from your existing bookkeeper or CPA to Institution.

Bookkeeping & finance

A payment amount is off by 100 times: check the API currency unit

Verify the relationship between a payment API's integer amount, currency and operation before converting it into a ledger value or requesting a payout.

By Institution3 minute readPublished View sources
In this guide

Trace the value through each representation

If a payment becomes one hundredth of its expected amount in the ledger, inspect the original API value before changing an exchange rate. Record the currency code, endpoint, operation, raw amount and displayed business amount. Follow the same transaction through the connector, staging data and final posting to locate the conversion step.

An integer without its unit is ambiguous. The number 1250 might represent 12.50 units of one currency or 1,250 units of another. A column heading such as amount does not settle that question. Preserve the raw response and the interpretation rule together so a reviewer can reconstruct the conversion.

Read the provider's currency and operation rules

Stripe documents amounts in the currency's minor unit. Its ordinary USD charges use cents, while JPY charges use whole yen. Stripe also documents special cases: ISK retains a two-decimal representation despite disallowing fractional charges, and HUF and TWD have payout restrictions that differ from their charge behavior. Check the specific endpoint and currency rather than applying a universal division by 100.

For illustration, a Stripe USD charge amount of 1250 represents $12.50. A JPY charge amount of 1250 represents ¥1,250. Those examples describe representation, with no currency conversion between them. An exchange-rate calculation is a separate operation with its own source and accounting policy.

References: Stripe: Currencies and API amount units

Give the conversion rule an explicit owner

Ask the integration owner where currency-unit rules are maintained and how provider changes reach that configuration. The rule should distinguish currency, API operation and any documented exception. Finance should approve the intended business amount; the developer should demonstrate the exact transformation that produces it.

Reject unsupported or unknown combinations into a visible exception queue. Quietly assuming two decimals can create a plausible-looking but wrong amount. Likewise, decide how invalid fractional requests are handled before a payout is attempted. Do not round an amount silently merely to satisfy the destination's input format.

Keep arithmetic precision separate from display formatting. A currency symbol and two decimal places can make a value look right without correcting its underlying unit. Have the implementer explain where decimal arithmetic, rounding and integer conversion occur, and retain the approved rounding rule with the mapping.

Test the actual currencies the business uses

Create approved nonproduction cases for an ordinary two-decimal charge, a supported zero-decimal charge, a refund and any payout exception relevant to the business. Define the raw API value and expected ledger amount before running the connector. Include an amount near a permitted rounding boundary and an unsupported combination that must be rejected.

Inspect the complete route in both directions where applicable. A connector may correctly import a payment while constructing an outgoing refund in the wrong unit. Verify each operation separately and avoid making a live payment merely to test a numeric transformation.

Identify the affected records before correcting history

Once the faulty rule is known, identify the currencies, endpoints and deployment dates that used it. Compare original provider amounts with posted amounts for that bounded population. A consistent factor-of-100 difference is a useful clue, but it is not sufficient evidence to multiply every historical balance.

Have the accounting owner approve corrections and any customer-facing follow-up. Retain the raw amounts, repaired mapping version and record-level differences. Release the change when the expected units survive the full route and the previously affected population has an explained disposition.

Sources

Requirements and product details can change. Check the linked guidance for the facts that apply to your situation.

Related reading

Need help with this work?

General information, not personalized accounting, tax, legal, or investment advice. Have the appropriate qualified professional review decisions that depend on your circumstances.