Amounts and precision

Money in FlowPayra is never a floating-point number, a JSON number, or a language-native decimal. If your integration parses an amount into a float somewhere, it will eventually be wrong by a fraction of a unit, and that fraction will not reconcile.

Three representations

API decimal string — what you send and receive: "125.00". Always a string in JSON. It carries the merchant-facing presentation, including trailing zeros.

Deployment raw integer — the on-chain base unit for one token on one chain: "125000000" for 125 USDC at 6 decimals. Up to 78 digits. This is what the buyer’s wallet actually transfers, and what the chain scanner matches against.

Currency canonical integer — the ledger’s internal scale, up to 156 digits. You will not normally see this; it exists so that the same currency across chains with different decimals stays comparable inside one ledger.

Rules that will save you a bug

• Compare and add as strings or big integers. Never parseFloat. In JavaScript, BigInt over the raw integer is exact; Number is not, and a USDC amount above 9,007,199,254,740,991 base units silently loses precision.
• Do not restore trailing zeros by rounding. When you derive a display amount from a raw integer, pad the fraction to the quote’s precision. Rounding a payment amount is never correct.
• Quote explicitly. quotes maps a currency id to an amount and, optionally, the chains you will accept it on. FlowPayra performs no USD conversion and never adds a currency you did not list. If you want the buyer to be able to pay in USDC on Base and USDT on Tron, say both.
• The amount you display is the amount that must arrive. The hosted checkout enforces this: the largest number on the page is always the amount to send right now, after any balance credit. If you build your own payment surface, keep that property.

Underpayment

If the chain delivers less than the quoted amount, the payment moves to underpaid and the remaining balance stays payable to the same address. The checkout shows how much arrived, how much is outstanding, and keeps the asset and network visible so the buyer tops up on the right chain.