Money
The SDK moves every monetary value in minor units, as integers: 1999 is R$ 19.99 (a currency with 2 decimal places). There is never a number with decimal places in the API, so balances and limits add up with no floating-point error. The operator's currency (with decimalPlaces) comes from config.get().
What is validated in the response
Monetary fields coming from the gateway (in the core and in the product packages) go through a strict check:
- the value is a safe integer (up to
Number.MAX_SAFE_INTEGER), as a number or as text; a value from 2^53 upward never arrives rounded; - the currency is an ISO code of three uppercase letters (
/^[A-Z]{3}$/); decimalPlacesis an integer from 0 to 8.
A field outside that rejects the entire response with VALIDATION_ERROR, even in validation: 'warn' (the default): this also applies to items inside lists, maps and unions, and to the balance that arrives through realtime. In 'warn' the remaining fields stay tolerant (a new enum becomes onValidationIssue), but wrong money is never delivered to the app. A gateway out of contract shows up as an error, not as a wrong balance. Product packages reuse the same checks through money, moneyText, currencyCode and decimalPlaces from @getenginex/sdk/extension.
Not everything is money. Price, quantity and percentage are not validated as money: Predictions prices and quantities, fees in basis points (bps), loyalty points and mission progress follow the common validation. The Predictions market aggregates and limits (volume_24h, total_volume, min_order_size, max_position) are left out of the strict check by decision (market aggregates and limits, in cents) and also follow the common validation.
An empty currency ('') is accepted only where the gateway omits it because the amount is zero: in bonus campaign values, in the currency of loyalty redemption and in the settlement_currency of Predictions. In any other monetary field, '' rejects the response. The config.currencies list is free text and does not go through this check.
Conversion helpers
Three helpers convert to and from what the user sees and types:
import { formatMoney, fromMinorUnits, toMinorUnits } from '@getenginex/sdk'
const { currency } = await enginex.config.get() // { code: 'BRL', symbol: 'R$', decimalPlaces: 2, ... }
formatMoney(123456, currency, 'pt-BR') // 'R$ 1.234,56'
toMinorUnits('1.234,56', currency) // 123456
toMinorUnits(19.99, currency) // 1999 (19.99 * 100 would give 1998.9999999999998)
fromMinorUnits(1999, currency) // 19.99formatMoney(amountMinor, currency, locale?)
Uses Intl.NumberFormat with the currency's ISO code and the decimalPlaces places. Accepts negatives (statements). Without locale, the runtime's applies; in SSR (Next.js, Nuxt), pass the same locale on the server and in the browser to avoid a hydration mismatch.
toMinorUnits(value, currency)
Converts the text of a field ('12,50', '1.234,56', '1,234.56') or a number into minor units. The text is read digit by digit, without multiplying a number, and:
- with more decimal places than the currency has, it rounds half up on the given value (
'1.0050'becomes101); - with
.and,together, the last one is the decimal separator ('1.234,56'); a single separator that appears once is the decimal ('1.5','12,50'); repeated, it is a thousands separator ('1.234.567'); - a single separator followed by exactly 3 digits (
'1.000','1,000','10.500') is ambiguous and throwsRangeError, except in a 3-decimal currency (there it is a decimal); - it rejects negatives, empty or non-numeric text,
NaN, infinity and values above the largest safe integer, throwingRangeError.
Values like '1.000' are refused
In pt-BR 1.000 is one thousand and in en-US it is one: converting silently could undervalue by a factor of 1000. That is why the SDK throws instead of guessing. Pass a number, or an unambiguous string: with both separators ('1.000,00') or without thousands ('1000'). If the app reads a text field, normalize it (or use a numeric input) before calling toMinorUnits.
A number is never ambiguous, but it only carries what JavaScript can represent.
fromMinorUnits(amountMinor, currency)
Returns the major unit as a number (1999 becomes 19.99), useful for filling in an edit field. To show money to the user, use formatMoney. Since it is a number, beyond ~15 significant digits the decimal places are no longer representable.
All three throw RangeError on out-of-contract input (a non-integer value in minor units or an invalid decimalPlaces).