# `MishkaPay.Money`
[🔗](https://github.com/mishka-group/mishka_pay/blob/v0.0.1/lib/mishka_pay/money.ex#L5)

Money in Mishka Pay is [ex_money](https://hex.pm/packages/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`.

# `currency_field`

```elixir
@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`

```elixir
@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?`

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

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

# `from_minor`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

```elixir
@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`

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

---

*Consult [api-reference.md](api-reference.md) for complete listing*
