Put currency and scale in the API contract

Choose the representation by domain

Use integer cents for a final AUD amount when every allowed value is a whole cent. Use an exact decimal representation for rates and intermediate calculations that need smaller fractions. Validate finite values, permitted precision and range at the boundary.

Do not let a database decimal become an ordinary binary floating-point number unnoticed in the application layer. Inspect the driver and serialisation behaviour and choose a decimal library or string-based contract that preserves the intended value.

This example uses a string for minor units so the wire representation does not depend on a consumer's integer range. An API using JSON numbers instead must define and enforce its supported range.

{
  "currency": "AUD",
  "amountMinor": "12345",
  "minorUnitExponent": 2,
  "calculationPolicy": "invoice-example-v3"
}

The example represents AUD 123.45. Do not accept contradictory scale metadata from an untrusted client. The server's currency model determines the supported representation.

Parse input before formatting it

Accept a clearly defined input syntax and show actionable errors for ambiguous separators. Avoid removing every non-digit character, which can turn a negative amount or decimal value into a different positive integer.

Keep a user's partially typed value in form state without prematurely treating it as an accepted monetary amount. Convert it only after validation, and let the authoritative server calculation determine final charges.

Centralise calculation policy

Implement the approved order of operations and rounding boundary in one domain module. Pass the policy version with persisted calculation evidence when reproducibility requires it.

For an illustrative equal split of 1,000 cents across three lines, allocate 333 cents to each and assign the remaining cent under a stable rule. Test that changing input order does not unexpectedly change the chosen recipient.

Adapt and reconcile at the provider boundary

Write an adapter with names that reveal units, such as payableMinorUnits. Test it against the provider's documented currency rules rather than multiplying every currency by 100.

Persist the exact amount and currency sent alongside the provider reference. Reconciliation can then compare equivalent units and distinguish a fee, conversion or partial payment from a scale defect.