View Source Gringotts.Money protocol (gringotts v1.1.1)
Money protocol used by the Gringotts API.
The amount argument required for some of Gringotts' API methods must
implement this protocol.
If your application is already using a supported Money library, just pass in the Money struct and things will work out of the box.
Otherwise, just wrap your amount with the currency together in a Map
like so,
price = %{value: Decimal.new("20.18"), currency: "USD"}and the API will accept it (as long as the currency is valid ISO 4217 currency code).
note-on-the-any-implementation
Note on the Any implementation
Both to_string/1 and to_integer/1 assume that the precision for the currency
is 2 digits after decimal.
Link to this section Summary
Functions
Returns the ISO 4217 compliant currency code associated with this sum of money.
Returns the ISO4217 currency code as string and value as an integer.
Returns a tuple of ISO4217 currency code and the value as strings.
Returns a Decimal.t representing the "worth" of this sum of money in the
associated currency.
Link to this section Types
@type t() :: t()
Link to this section Functions
Returns the ISO 4217 compliant currency code associated with this sum of money.
This must be an UPCASE string
@spec to_integer(Money.t()) :: {currency :: String.t(), value :: integer(), exponent :: neg_integer()}
Returns the ISO4217 currency code as string and value as an integer.
Useful for gateways that require amount as integer (like cents instead of dollars).
note
Note
Conversion from Decimal.t to integer is potentially lossy and the rounding
(if required) is performed (automatically) by the Money library defining the
type, or in the implementation of this protocol method.
If you want to implement this method for your custom type, please ensure that
the rounding strategy (if any rounding is applied) must be
half_even.
To keep things predictable and transparent, merchants should round the
amount themselves, perhaps by explicitly calling the relevant method of
the Money library in their application before passing it to Gringotts's
public API.
examples
Examples
# the money lib is aliased as "MoneyLib"
iex> usd_price = MoneyLib.new("4.1234", :USD)
#MoneyLib<4.1234, "USD">
iex> Gringotts.Money.to_integer(usd_price)
{"USD", 412, -2}
iex> bhd_price = MoneyLib.new("4.1234", :BHD)
#MoneyLib<4.1234, "BHD">
iex> Gringotts.Money.to_integer(bhd_price)
{"BHD", 4123, -3}
# the Bahraini dinar is divided into 1000 fils unlike the dollar which is
# divided in 100 centsReturns a tuple of ISO4217 currency code and the value as strings.
The stringified value must match this regex: ~r/-?\d+\.\d\d{n}/ where
n+1 should match the required precision for the currency. There should be
no place value separators except the decimal point (like commas).
Gringotts will not (and cannot) validate this of course.
note
Note
Conversion from Decimal.t to string is potentially lossy and the rounding
(if required) is performed (automatically) by the Money library defining the
type, or in the implementation of this protocol method.
If you want to implement this method for your custom type, please ensure that
the rounding strategy (if any rounding is applied) must be
half_even.
To keep things predictable and transparent, merchants should round the
amount themselves, perhaps by explicitly calling the relevant method of
the Money library in their application before passing it to Gringotts's
public API.
examples
Examples
# the money lib is aliased as "MoneyLib"
iex> usd_price = MoneyLib.new("4.1234", :USD)
#MoneyLib<4.1234, "USD">
iex> Gringotts.Money.to_string(usd_price)
{"USD", "4.12"}
iex> bhd_price = MoneyLib.new("4.1234", :BHD)
#MoneyLib<4.1234, "BHD">
iex> Gringotts.Money.to_string(bhd_price)
{"BHD", "4.123"}Returns a Decimal.t representing the "worth" of this sum of money in the
associated currency.