Money in Mishka Pay is ex_money's Money: a Decimal
amount and an ISO 4217 currency, with every currency's decimal places, cash rounding and
formatting in any language from CLDR (Money.to_string(money, locale: :de)).
Only English locale data ships with localize. A project that formats money in other languages
downloads their data once at build time, for example mix localize.download_locales de fr, and
names them in config :localize, supported_locales: [:en, :de, :fr]. Without that,
Money.to_string/2 answers in English, with no error.
This module is the check Mishka Pay puts around it before money reaches a provider:
the amount is a
Decimal, an integer or a string; a float is refused, since0.1 + 0.2is not0.3;the amount is zero or more: a refund is its own record with a positive amount;
the amount has at most twenty digits before the decimal point;
the amount has no more decimal places than its currency (two for USD, none for JPY, three for KWD), and is kept with exactly those places, so
5and"5.00"dollars are equal;the currency is a known ISO 4217 code, in any case and with spaces trimmed.
MishkaPay.Money.new("19.99", "usd") #=> {:ok, Money.new(:USD, "19.99")}
Providers count in the smallest unit (cents): from_minor/2 and to_minor/1 convert. Every
error is an :invalid class MishkaPay.Errors error naming :amount or :currency.
Summary
Functions
A guarded_struct field validator for a currency code alone: validator: {MishkaPay.Money, :currency_field}. It takes "usd", "USD" or :USD and keeps the ISO 4217 atom (:USD).
Whether money fits in digits decimal places, such as whole units for 0.
Money from an amount in the currency's smallest unit, as a provider gives it:
from_minor(1999, "USD") is 19.99 dollars.
Like from_minor/2, for a provider that counts currency in digits places rather than its
ISO 4217 ones: Stripe sends 500 for 5 Icelandic krónur (from_minor(500, "ISK", 2)).
Checked money of amount in currency.
Like from_minor/2, for an amount that may be below zero (an invoice's credit line); a
negative one keeps its sign. Payments and prices never take this.
The amount in the currency's smallest unit, as a provider takes it: 19.99 dollars is 1999.
The amount in digits places of its unit, for a provider that counts the currency other than
ISO 4217 does: 5 Icelandic krónur is 500 at Stripe (to_minor(money, 2)). The amount has no
more places than digits; a checked call refuses it before (fits?/2).
Functions
A guarded_struct field validator for a currency code alone: validator: {MishkaPay.Money, :currency_field}. It takes "usd", "USD" or :USD and keeps the ISO 4217 atom (:USD).
A guarded_struct field validator for money: validator: {MishkaPay.Money, :field}. It takes a
Money struct or a map with amount and currency (atom or string keys, as JSON gives them),
checks it with new/2 and keeps the checked Money.
@spec fits?(Money.t(), non_neg_integer()) :: boolean()
Whether money fits in digits decimal places, such as whole units for 0.
@spec from_minor(integer(), String.t() | atom()) :: {:ok, Money.t()} | {:error, Splode.Error.t()}
Money from an amount in the currency's smallest unit, as a provider gives it:
from_minor(1999, "USD") is 19.99 dollars.
@spec from_minor(integer(), String.t() | atom(), non_neg_integer()) :: {:ok, Money.t()} | {:error, Splode.Error.t()}
Like from_minor/2, for a provider that counts currency in digits places rather than its
ISO 4217 ones: Stripe sends 500 for 5 Icelandic krónur (from_minor(500, "ISK", 2)).
@spec new(Decimal.t() | integer() | String.t(), String.t() | atom()) :: {:ok, Money.t()} | {:error, Splode.Error.t()}
Checked money of amount in currency.
Like field/2, for money that may be below zero: an invoice line that credits time not used,
or credit given to a customer. The amount, in a Money or a map, is checked as its size and
keeps its sign.
@spec signed_from_minor(integer(), String.t() | atom()) :: {:ok, Money.t()} | {:error, Splode.Error.t()}
Like from_minor/2, for an amount that may be below zero (an invoice's credit line); a
negative one keeps its sign. Payments and prices never take this.
The amount in the currency's smallest unit, as a provider takes it: 19.99 dollars is 1999.
@spec to_minor(Money.t(), non_neg_integer()) :: integer()
The amount in digits places of its unit, for a provider that counts the currency other than
ISO 4217 does: 5 Icelandic krónur is 500 at Stripe (to_minor(money, 2)). The amount has no
more places than digits; a checked call refuses it before (fits?/2).