Documentation
¶
Overview ¶
Package money provides the shared cents <-> display-string conversions used by every payment-channel adapter (waffo, stripe, paypal). Channels carry amounts as display strings ("9.90"; zero-decimal currencies such as JPY carry "4500"), and every adapter needs the same two conversions — this package replaces the per-adapter private formatAmount/parseAmount copies (plan docs/plan-billing-channel-framework-2026-10-23.md §BC-3).
ParseAmount returns the zero value instead of an error for untrusted input. Amount fields inside webhook payloads cannot be trusted to be well-formed; the existing amountMismatch semantics in billing/app treat event.AmountCents <= 0 as "no amount to reconcile" and route the event down the ignore path rather than failing it. Mapping malformed amounts to 0 keeps that contract: garbage amounts degrade to "not reconcilable" instead of breaking event processing.
Index ¶
- func CheckMinorUnit(currency string) error
- func FormatCents(cents int, currency string) string
- func FormatCentsChecked(cents int, currency string) (string, error)
- func ParseAmount(display string) int
- func ParseAmountForCurrency(display, currency string) int
- func ValidateCurrency(currency string) error
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CheckMinorUnit ¶
CheckMinorUnit reports whether the framework can correctly convert between minor units and display strings for this currency: ISO 4217 shape, minor unit exponent 0 (JPY) or 2. Three-decimal currencies (KWD, BHD, …) return an error instead of being approximated — wire this into plan/price validation so they are rejected at the edge, never at the cashier.
func FormatCents ¶
FormatCents converts a minor-unit integer to the channel display string. Zero-decimal currencies (JPY) carry no decimal point; all others use two decimal places: 1900/"USD" -> "19.00", 4500/"JPY" -> "4500", 990/"USD" -> "9.90". Currency matching is case-insensitive; an empty or unknown currency formats as two-decimal.
func FormatCentsChecked ¶
FormatCentsChecked is FormatCents for untrusted currency input: it refuses three-decimal minor units instead of formatting them wrong. Callers that build channel-side prices from a plan currency must use this and surface the error; FormatCents stays for already-validated currencies.
func ParseAmount ¶
ParseAmount converts a display string to a minor-unit integer: "9.90" -> 990, "4500" -> 4500, "9.9" -> 990 (1 or 2 fraction digits are both accepted), "-19.00" -> -1900. Surrounding whitespace is trimmed; a lone dot with digits on one side is accepted (".50" -> 50, "19." -> 1900).
Anything that is not a plain (optionally signed) decimal with at most two fraction digits — empty string, non-digits, more than one dot, three or more fraction digits, integer overflow — yields 0, not an error: amount fields in event payloads are untrusted, and the amountMismatch semantics treat an amount of 0 as "not reconcilable" and ignore it.
func ParseAmountForCurrency ¶
ParseAmountForCurrency parses a display string according to the currency's minor-unit exponent. For zero-decimal currencies (JPY) it additionally normalizes the "4500.00" echo form some gateways send back: an all-zero fraction is stripped ("4500.00" → 4500, "4500." → 4500), while any nonzero fraction is not convertible to a whole minor unit and yields 0 (the established "not reconcilable" convention). Every other currency parses exactly like ParseAmount.
func ValidateCurrency ¶
ValidateCurrency reports whether currency has the ISO 4217 shape: exactly three ASCII letters, judged after case normalization ("USD", "usd" and "UsD" are all valid; "US", "USDD", "US1" and "" are not).
Types ¶
This section is empty.