ExMtnMomo.Collection (ExMtnMomo v0.1.0)
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.
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 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_pay_transaction_status(reference_id, token)
{:ok, %{
"amount" => "1000",
"currency" => "EUR",
"financialTransactionId" => "23503452",
"externalId" => "123456789",
"payer" => %{
"partyIdType" => "MSISDN",
"partyId" => "256771234567"
},
"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", ...}}