ExMtnMomo.Sandbox (ExMtnMomo v0.1.2)

View Source

Provides functions for working with the MTN Mobile Money Sandbox environment.

The Sandbox module allows developers to:

  • Generate UUIDs for reference IDs
  • Create API users in the sandbox environment
  • Retrieve information about created users
  • Generate API keys for users

This module is primarily used during development and testing to set up the necessary credentials for interacting with other MTN MoMo API endpoints.

Configuration Options

The Sandbox module uses the following configuration options:

  • :base_url - The base URL for the MTN Mobile Money API

    • Default: "https://sandbox.momodeveloper.mtn.com"
  • :sandbox_key - The API key for sandbox operations

    • This is typically your primary or secondary key provided by MTN
    • Required for all sandbox operations

These options can be set in your config.exs file:

config :ex_mtn_momo,
  base_url: "https://sandbox.momodeveloper.mtn.com",
  sandbox_key: "your_primary_or_secondary_key"

Runtime Options

Most functions in this module accept an options parameter that can be used to override configuration values at runtime. The following options are supported:

  • :base_url - Override the base URL for the API request
  • :sandbox_key - Override the sandbox key for authentication

Example:

# Override the sandbox key for a specific request
options = [sandbox_key: "alternative_sandbox_key"]

uuid = ExMtnMomo.Sandbox.get_uuid4()
ExMtnMomo.Sandbox.create_api_user(uuid, "https://webhook.site/callback", options)

Examples

# Generate a UUID for user creation
uuid = ExMtnMomo.Sandbox.get_uuid4()

# Create a user in the sandbox environment
{:ok, _} = ExMtnMomo.Sandbox.create_api_user(uuid)

# Get information about the created user
{:ok, user_info} = ExMtnMomo.Sandbox.get_created_user(uuid)

# Generate an API key for the user
{:ok, %{"apiKey" => api_key}} = ExMtnMomo.Sandbox.get_api_key(uuid)

Summary

Functions

Generates and retrieves an API key for a user.

Retrieves information about a previously created API user.

Generates a UUID v4 string.

Functions

create_api_user(uuid4, callback_url \\ "https://webhook.site/2b823c34-90d7-4bf7-bd69-0f0559efcf3a", options \\ [])

Creates an API user in the sandbox environment.

Parameters

  • uuid4 - A UUID v4 string to use as the reference ID for the user
  • callback_url - URL to receive API callbacks (optional)
  • options - Additional configuration options (optional)

Options

The options parameter can include the following keys:

  • :base_url - Override the base URL for the API request
  • :secondary_key - Override the secondary key to use for authentication

Returns

  • {:ok, "User Created"} on success
  • {:error, reason} on failure

Examples

iex> uuid = ExMtnMomo.Sandbox.get_uuid4()
iex> ExMtnMomo.Sandbox.create_api_user(uuid)
{:ok, "User Created"}

get_api_key(uuid4, options \\ [])

Generates and retrieves an API key for a user.

Parameters

  • uuid4 - The UUID of the user
  • options - Additional configuration options (optional)

Options

The options parameter can include the following keys:

  • :base_url - Override the base URL for the API request
  • :secondary_key - Override the secondary key to use for authentication

Returns

  • {:ok, %{"apiKey" => api_key}} on success
  • {:error, reason} on failure

Examples

iex> uuid = "f1bfc995-8dbe-4afb-aa82-a8c75a37edf6"
iex> ExMtnMomo.Sandbox.get_api_key(uuid)
{:ok, %{"apiKey" => "a94d865a12e047319c6e673a15b48776"}}

get_created_user(uuid4, options \\ [])

Retrieves information about a previously created API user.

Parameters

  • uuid4 - The UUID of the created user
  • options - Additional configuration options (optional)

Options

The options parameter can include the following keys:

  • :base_url - Override the base URL for the API request
  • :secondary_key - Override the secondary key to use for authentication

Returns

  • {:ok, user_details} on success
  • {:error, reason} on failure

Examples

iex> uuid = "f1bfc995-8dbe-4afb-aa82-a8c75a37edf6"
iex> ExMtnMomo.Sandbox.get_created_user(uuid)
{:ok, %{"providerCallbackHost" => "https://webhook.site/2b823c34-90d7-4bf7-bd69-0f0559efcf3a", ...}}

get_uuid4()

Generates a UUID v4 string.

This UUID can be used as a reference ID for API user creation and other operations.

Examples

iex> ExMtnMomo.Sandbox.get_uuid4()
"f1bfc995-8dbe-4afb-aa82-a8c75a37edf6"