ExMtnMomo.Collection (ExMtnMomo v0.1.2)
View SourceProvides functions for working with the MTN Mobile Money Collection API.
The Collection module allows developers to:
- Create access tokens for authentication
- Request payments from customers
- Check the status of payment requests
- Retrieve account balances
- Get user information
This module is used for receiving payments from customers through the MTN Mobile Money platform.
Configuration Options
The Collection module uses the following configuration options:
Global Configuration
:base_url
- The base URL for the MTN Mobile Money API- Default for sandbox:
"https://sandbox.momodeveloper.mtn.com"
- Production: URL provided by MTN for your specific region
- Default for sandbox:
:x_target_environment
- The target environment for API requests- Options:
"sandbox"
for testing, or a specific production environment like"mtnzambia"
- Default:
"sandbox"
- Options:
Collection-Specific Configuration
Collection credentials are configured as a map under the :collection
key:
:collection.secondary_key
- Subscription key for the Collection API- Used in the
Ocp-Apim-Subscription-Key
header - Required for all Collection API operations
- Used in the
:collection.primary_key
- Alternative subscription key- Can be used as a backup if the secondary key fails
:collection.user_id
- User ID for authentication- Required for creating access tokens
- Used in the Basic Auth header
:collection.api_key
- API key for authentication- Required for creating access tokens
- Used in the Basic Auth header
These options should be set in your config.exs
file:
config :ex_mtn_momo,
base_url: "https://sandbox.momodeveloper.mtn.com",
x_target_environment: "sandbox",
collection: %{
secondary_key: "your_secondary_key",
primary_key: "your_primary_key",
user_id: "your_user_id",
api_key: "your_api_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:secondary_key
- Override the secondary key to use for authentication:primary_key
- Override the primary key to use for authentication:user_id
- Override the user ID for authentication:api_key
- Override the API key for authentication:x_target_environment
- Override the target environment
Example:
# Override the secondary key and target environment for a specific request
options = [
secondary_key: "alternative_secondary_key",
x_target_environment: "production"
]
{:ok, %{"access_token" => token}} = ExMtnMomo.Collection.create_access_token(options)
Examples
# Get an access token for collections
{:ok, %{"access_token" => token}} = ExMtnMomo.Collection.create_access_token()
# Initiate a payment request
payment_details = %{
"amount" => "1000",
"currency" => "EUR",
"externalId" => "123456789",
"payer" => %{
"partyIdType" => "MSISDN",
"partyId" => "256771234567"
},
"payerMessage" => "Payment for products",
"payeeNote" => "Payment received"
}
reference_id = UUID.uuid4()
{:ok, _} = ExMtnMomo.Collection.request_to_pay(payment_details, token, reference_id)
# Check payment status
{:ok, status} = ExMtnMomo.Collection.request_to_pay_transaction_status(reference_id, token)
Summary
Functions
Retrieves basic information about a user.
Creates an access token for collection operations.
Creates an OAuth 2.0 token for collection operations.
Retrieves the account balance.
Retrieves the account balance for a specific currency.
Retrieves the status of an invoice.
Retrieves the status of a payment.
Retrieves the status of a pre-approval.
Retrieves user information with consent.
Initiates a payment request to a customer.
Checks the status of a payment request.
Checks the status of a withdrawal request.
Functions
Retrieves basic information about a user.
Parameters
msisdn
- The mobile number of the useraccess_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, user_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> msisdn = "256771234567"
iex> ExMtnMomo.Collection.basic_user_info(msisdn, token)
{:ok, %{"name" => "John Doe", ...}}
Creates an access token for collection operations.
Parameters
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, token_details}
on success, wheretoken_details
includes the access_token{:error, reason}
on failure
Examples
iex> ExMtnMomo.Collection.create_access_token()
{:ok, %{"access_token" => "eyJ0eXAi...", "expires_in" => 3600, "token_type" => "Bearer"}}
Creates an OAuth 2.0 token for collection operations.
Parameters
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, token_details}
on success{:error, reason}
on failure
Examples
iex> ExMtnMomo.Collection.create_oauth_2_token()
{:ok, %{"access_token" => "eyJ0eXAi...", "expires_in" => 3600, "token_type" => "Bearer"}}
Retrieves the account balance.
Parameters
access_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, balance_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> ExMtnMomo.Collection.get_account_balance(token)
{:ok, %{"availableBalance" => "15000", "currency" => "EUR"}}
Retrieves the account balance for a specific currency.
Parameters
currency
- Currency code (e.g., "EUR", "USD")access_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, balance_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> ExMtnMomo.Collection.get_account_balance_in_specific_currency("EUR", token)
{:ok, %{"availableBalance" => "15000", "currency" => "EUR"}}
Retrieves the status of an invoice.
Parameters
x_reference_id
- The reference ID of the invoiceaccess_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, invoice_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> reference_id = "f1bfc995-8dbe-4afb-aa82-a8c75a37edf6"
iex> ExMtnMomo.Collection.get_invoice_status(reference_id, token)
{:ok, %{"status" => "PAID", ...}}
Retrieves the status of a payment.
Parameters
x_reference_id
- The reference ID of the paymentaccess_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, payment_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> reference_id = "f1bfc995-8dbe-4afb-aa82-a8c75a37edf6"
iex> ExMtnMomo.Collection.get_payment_status(reference_id, token)
{:ok, %{"status" => "SUCCESSFUL", ...}}
Retrieves the status of a pre-approval.
Parameters
reference_id
- The reference ID of the pre-approvalaccess_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, status_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> reference_id = "f1bfc995-8dbe-4afb-aa82-a8c75a37edf6"
iex> ExMtnMomo.Collection.get_pre_approval_status(reference_id, token)
{:ok, %{"status" => "APPROVED", ...}}
Retrieves user information with consent.
Parameters
access_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, user_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> ExMtnMomo.Collection.get_user_info_with_consent(token)
{:ok, %{"name" => "John Doe", "email" => "john.doe@example.com", ...}}
Initiates a payment request to a customer.
Parameters
attrs
- A map containing payment detailsaccess_token
- A valid access tokenuuid4
- A UUID v4 string as the reference ID (optional)options
- Additional configuration options (optional)
Payment Details
The attrs
map should include the following keys:
"amount"
- The payment amount"currency"
- The currency code (e.g., "EUR", "USD")"externalId"
- Your system's transaction ID"payer"
- A map containing payer information:"partyIdType"
- The type of identifier (usually "MSISDN")"partyId"
- The mobile number of the payer
"payerMessage"
- Message shown to the payer"payeeNote"
- Note for the payee's records
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:x_target_environment
- Override the target environment
Returns
{:ok, response}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> payment_details = %{
...> "amount" => "1000",
...> "currency" => "EUR",
...> "externalId" => "123456789",
...> "payer" => %{
...> "partyIdType" => "MSISDN",
...> "partyId" => "256771234567"
...> },
...> "payerMessage" => "Payment for products",
...> "payeeNote" => "Payment received"
...> }
iex> reference_id = UUID.uuid4()
iex> ExMtnMomo.Collection.request_to_pay(payment_details, token, reference_id)
{:ok, %{}}
Checks the status of a payment request.
Parameters
reference_id
- The reference ID of the payment request @spec get_account_balance_in_specific_currency(any(), any()) :: {:error, any()} | {:ok, any()}access_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, status_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> reference_id = "f1bfc995-8dbe-4afb-aa82-a8c75a37edf6"
iex> ExMtnMomo.Disbursements.request_to_pay_transaction_status(reference_id, token)
{:ok, %{"status" => "SUCCESSFUL", ...}}
Checks the status of a withdrawal request.
Parameters
reference_id
- The reference ID of the withdrawal requestaccess_token
- A valid access tokenoptions
- 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:x_target_environment
- Override the target environment
Returns
{:ok, status_details}
on success{:error, reason}
on failure
Examples
iex> token = "eyJ0eXAi..."
iex> reference_id = "f1bfc995-8dbe-4afb-aa82-a8c75a37edf6"
iex> ExMtnMomo.Collection.request_to_withdraw_transaction_status(reference_id, token)
{:ok, %{"status" => "SUCCESSFUL", ...}}