MishkaPay.Money (Mishka Pay v0.0.1)

Copy Markdown View Source

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, since 0.1 + 0.2 is not 0.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 5 and "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).

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.

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 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.

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

currency_field(name, code)

@spec currency_field(atom(), term()) ::
  {:ok, atom(), atom() | nil} | {:error, atom(), String.t()}

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).

field(name, map)

@spec field(atom(), term()) :: {:ok, atom(), Money.t()} | {:error, atom(), String.t()}

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.

fits?(money, digits)

@spec fits?(Money.t(), non_neg_integer()) :: boolean()

Whether money fits in digits decimal places, such as whole units for 0.

from_minor(minor, currency)

@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.

from_minor(minor, currency, digits)

@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)).

new(amount, currency)

@spec new(Decimal.t() | integer() | String.t(), String.t() | atom()) ::
  {:ok, Money.t()} | {:error, Splode.Error.t()}

Checked money of amount in currency.

signed_field(name, money)

@spec signed_field(atom(), term()) ::
  {:ok, atom(), Money.t()} | {:error, atom(), String.t()}

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.

signed_from_minor(minor, currency)

@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.

to_minor(money)

@spec to_minor(Money.t()) :: integer()

The amount in the currency's smallest unit, as a provider takes it: 19.99 dollars is 1999.

to_minor(money, digits)

@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).