ExMtnMomo.Disbursements (ExMtnMomo v0.1.0)
View SourceProvides functions for working with the MTN Mobile Money Disbursements API.
The Disbursements module allows developers to:
- Create access tokens for authentication
- Send money to users (deposits)
- Process refunds
- Transfer money between accounts
- Retrieve account balances
- Check the status of transactions
This module is used for sending payments to customers through the MTN Mobile Money platform.
Examples
# Get an access token for disbursements
{:ok, %{"access_token" => token}} = ExMtnMomo.Disbursements.create_access_token()
# Initiate a deposit
deposit_details = %{
"amount" => "1000",
"currency" => "EUR",
"externalId" => "123456789",
"payee" => %{
"partyIdType" => "MSISDN",
"partyId" => "256771234567"
},
"payerMessage" => "Salary payment",
"payeeNote" => "Salary received"
}
reference_id = UUID.uuid4()
{:ok, _} = ExMtnMomo.Disbursements.deposit_v2(deposit_details, reference_id)
# Check deposit status
{:ok, status} = ExMtnMomo.Disbursements.get_deposit_status(reference_id, token)
Summary
Functions
Authorizes a BC request.
Creates an access token for disbursement operations.
Creates an OAuth 2.0 token for disbursement operations.
Initiates a deposit using API version 1.0.
Initiates a deposit using API version 2.0.
Retrieves the account balance for disbursements.
Retrieves the account balance for a specific currency for disbursements.
Retrieves the status of a deposit.
Retrieves the status of a refund.
Retrieves the status of a transfer.
Retrieves user information with consent for disbursements.
Initiates a refund using API version 1.0.
Initiates a refund using API version 2.0.
Initiates a transfer.
Functions
Authorizes a BC request.
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:x_target_environment
- Override the target environment
Returns
{:ok, authorization_details}
on success{:error, reason}
on failure
Examples
iex> ExMtnMomo.Disbursements.bc_authorize()
{:ok, %{...}}
Creates an access token for disbursement 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.Disbursements.create_access_token()
{:ok, %{"access_token" => "eyJ0eXAi...", "expires_in" => 3600, "token_type" => "Bearer"}}
Creates an OAuth 2.0 token for disbursement 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:x_target_environment
- Override the target environment
Returns
{:ok, token_details}
on success{:error, reason}
on failure
Examples
iex> ExMtnMomo.Disbursements.create_oauth_2_token()
{:ok, %{"access_token" => "eyJ0eXAi...", "expires_in" => 3600, "token_type" => "Bearer"}}
Initiates a deposit using API version 1.0.
Parameters
attrs
- A map containing deposit detailsuuid4
- A UUID v4 string as the reference IDoptions
- Additional configuration options (optional)
Deposit Details
The attrs
map should include the following keys:
"amount"
- The deposit amount"currency"
- The currency code (e.g., "EUR", "USD")"externalId"
- Your system's transaction ID"payee"
- A map containing payee information:"partyIdType"
- The type of identifier (usually "MSISDN")"partyId"
- The mobile number of the payee
"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
Returns
{:ok, response}
on success{:error, reason}
on failure
Examples
iex> deposit_details = %{
...> "amount" => "1000",
...> "currency" => "EUR",
...> "externalId" => "123456789",
...> "payee" => %{
...> "partyIdType" => "MSISDN",
...> "partyId" => "256771234567"
...> },
...> "payerMessage" => "Salary payment",
...> "payeeNote" => "Salary received"
...> }
iex> reference_id = UUID.uuid4()
iex> ExMtnMomo.Disbursements.deposit_v1(deposit_details, reference_id)
{:ok, %{}}
Initiates a deposit using API version 2.0.
Parameters
attrs
- A map containing deposit detailsuuid4
- A UUID v4 string as the reference IDoptions
- Additional configuration options (optional)
Deposit Details
The attrs
map should include the following keys:
"amount"
- The deposit amount"currency"
- The currency code (e.g., "EUR", "USD")"externalId"
- Your system's transaction ID"payee"
- A map containing payee information:"partyIdType"
- The type of identifier (usually "MSISDN")"partyId"
- The mobile number of the payee
"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
Returns
{:ok, response}
on success{:error, reason}
on failure
Examples
iex> deposit_details = %{
...> "amount" => "1000",
...> "currency" => "EUR",
...> "externalId" => "123456789",
...> "payee" => %{
...> "partyIdType" => "MSISDN",
...> "partyId" => "256771234567"
...> },
...> "payerMessage" => "Salary payment",
...> "payeeNote" => "Salary received"
...> }
iex> reference_id = UUID.uuid4()
iex> ExMtnMomo.Disbursements.deposit_v2(deposit_details, reference_id)
{:ok, %{}}
Retrieves the account balance for disbursements.
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.Disbursements.get_account_balance(token)
{:ok, %{"availableBalance" => "15000", "currency" => "EUR"}}
Retrieves the account balance for a specific currency for disbursements.
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.Disbursements.get_account_balance_in_specific_currency("EUR", token)
{:ok, %{"availableBalance" => "15000", "currency" => "EUR"}}
Retrieves the status of a deposit.
Parameters
reference_id
- The reference ID of the depositaccess_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.get_deposit_status(reference_id, token)
{:ok, %{"status" => "SUCCESSFUL", ...}}
Retrieves the status of a refund.
Parameters
reference_id
- The reference ID of the refundaccess_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.get_refund_status(reference_id, token)
{:ok, %{"status" => "SUCCESSFUL", ...}}
Retrieves the status of a transfer.
Parameters
reference_id
- The reference ID of the transferaccess_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.get_transfer_status(reference_id, token)
{:ok, %{"status" => "SUCCESSFUL", ...}}
Retrieves user information with consent for disbursements.
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.Disbursements.get_user_info_with_consent(token)
{:ok, %{"name" => "John Doe", "email" => "john.doe@example.com", ...}}
Initiates a refund using API version 1.0.
Parameters
attrs
- A map containing refund detailsuuid4
- A UUID v4 string as the reference IDoptions
- 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, response}
on success{:error, reason}
on failure
Examples
iex> refund_details = %{
...> "amount" => "1000",
...> "currency" => "EUR",
...> "externalId" => "123456789",
...> "payerMessage" => "Refund for order cancellation",
...> "payeeNote" => "Refund processed"
...> }
iex> reference_id = UUID.uuid4()
iex> ExMtnMomo.Disbursements.refund_v1(refund_details, reference_id)
{:ok, %{}}
Initiates a refund using API version 2.0.
Parameters
attrs
- A map containing refund detailsuuid4
- A UUID v4 string as the reference IDoptions
- 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, response}
on success{:error, reason}
on failure
Examples
iex> refund_details = %{
...> "amount" => "1000",
...> "currency" => "EUR",
...> "externalId" => "123456789",
...> "payerMessage" => "Refund for order cancellation",
...> "payeeNote" => "Refund processed"
...> }
iex> reference_id = UUID.uuid4()
iex> ExMtnMomo.Disbursements.refund_v2(refund_details, reference_id)
{:ok, %{}}
Initiates a transfer.
Parameters
attrs
- A map containing transfer detailsuuid4
- A UUID v4 string as the reference IDoptions
- 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, response}
on success{:error, reason}
on failure
Examples
iex> transfer_details = %{
...> "amount" => "1000",
...> "currency" => "EUR",
...> "externalId" => "123456789",
...> "payee" => %{
...> "partyIdType" => "MSISDN",
...> "partyId" => "256771234567"
...> },
...> "payerMessage" => "Transfer payment",
...> "payeeNote" => "Transfer received"
...> }
iex> reference_id = UUID.uuid4()
iex> ExMtnMomo.Disbursements.transfer(transfer_details, reference_id)
{:ok, %{}}