ElixirMpesa.Config (ElixirMpesa v0.2.0)

Resolves and validates configuration for a request.

Values are resolved in order of precedence:

Options passed to the function call
Application environment (config :elixir_mpesa, ...)
The market preset named by :market

Configuration

config :elixir_mpesa,
  api_type: "sandbox",
  market: :lesotho,
  service_provider_code: "000000",
  api_key: System.get_env("MPESA_API_KEY"),
  public_key: System.get_env("MPESA_PUBLIC_KEY")

Credentials belong in config/runtime.exs and should come from the environment. See Authentication.

Markets

Setting :market fills in url_context, country and currency together, so they can never drift out of sync:

`:market`	`url_context`	country	currency
`:tanzania`	`vodacomTZN`	`TZN`	`TZS`
`:lesotho`	`vodacomLES`	`LES`	`LSL`
`:ghana`	`vodafoneGHA`	`GHA`	`GHS`
`:drc`	`vodacomDRC`	`DRC`	`CDF`

Any of the three can still be overridden individually, and a market this library does not know about can be reached by setting url_context, country and currency directly. See Markets.

Summary

Types

market()

t()

Functions

base_url(config)

The base URL for a resolved configuration.

market(name)

Returns the preset for a known market.

markets()

Lists the markets this library ships presets for.

resolve(opts \\ [])

Resolves configuration from call options, application environment and market preset.

session_key(config)

The cache key identifying the session scope: one session per API type and market.

Types

market()

@type market() :: :tanzania | :lesotho | :ghana | :drc

t()

@type t() :: %ElixirMpesa.Config{
  api_key: String.t(),
  api_type: String.t(),
  country: String.t() | nil,
  currency: String.t() | nil,
  public_key: String.t(),
  req_options: keyword(),
  service_provider_code: String.t() | nil,
  session_ttl: pos_integer(),
  url_context: String.t()
}

Functions

base_url(config)

@spec base_url(t()) :: String.t()

The base URL for a resolved configuration.

Examples

iex> {:ok, config} = ElixirMpesa.Config.resolve(market: :ghana, api_key: "k", public_key: "p")
iex> ElixirMpesa.Config.base_url(config)
"https://openapi.m-pesa.com/sandbox/ipg/v2/vodafoneGHA"

market(name)

@spec market(market() | atom()) ::
  %{url_context: String.t(), country: String.t(), currency: String.t()} | nil

Returns the preset for a known market.

Examples

iex> ElixirMpesa.Config.market(:tanzania)
%{url_context: "vodacomTZN", country: "TZN", currency: "TZS"}

iex> ElixirMpesa.Config.market(:kenya)
nil

markets()

@spec markets() :: [market()]

Lists the markets this library ships presets for.

Examples

iex> ElixirMpesa.Config.markets()
[:drc, :ghana, :lesotho, :tanzania]

resolve(opts \\ [])

@spec resolve(keyword()) :: {:ok, t()} | {:error, ElixirMpesa.Error.t()}

Resolves configuration from call options, application environment and market preset.

Returns {:error, %ElixirMpesa.Error{}} naming the offending key rather than letting a nil reach a URL or a cipher.

Examples

iex> {:ok, config} = ElixirMpesa.Config.resolve(
...>   market: :tanzania, api_key: "k", public_key: "p"
...> )
iex> {config.url_context, config.currency, config.api_type}
{"vodacomTZN", "TZS", "sandbox"}

iex> {:error, error} = ElixirMpesa.Config.resolve(market: :atlantis)
iex> {error.reason, error.category}
{:unknown_market, :config}

iex> {:error, error} = ElixirMpesa.Config.resolve(url_context: "vodacomTZN", api_key: "k")
iex> error.reason
:missing_config

session_key(config)

@spec session_key(t()) :: {String.t(), String.t()}

The cache key identifying the session scope: one session per API type and market.

Examples

iex> {:ok, config} = ElixirMpesa.Config.resolve(market: :lesotho, api_key: "k", public_key: "p")
iex> ElixirMpesa.Config.session_key(config)
{"sandbox", "vodacomLES"}