money

package
v0.14.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 3 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func CheckMinorUnit

func CheckMinorUnit(currency string) error

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

func FormatCents(cents int, currency string) string

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

func FormatCentsChecked(cents int, currency string) (string, error)

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

func ParseAmount(display string) int

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

func ParseAmountForCurrency(display, currency string) int

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

func ValidateCurrency(currency string) error

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL