ElixirMpesa.Transactions (ElixirMpesa v0.1.0)

View Source

Handles transaction operations for the M-Pesa OpenAPI.

This module provides functions for various M-Pesa transaction types, including:

  • Customer to Business (C2B) payments
  • Business to Customer (B2C) payments
  • Business to Business (B2B) payments
  • Transaction status queries
  • Direct debit operations
  • Beneficiary name queries

All functions require an encrypted session key that must be generated first using the ElixirMpesa.GenerateSessionKey module.

Example Usage

# First, encrypt the API key and get a session key
{:ok, encrypted_api_key} = ElixirMpesa.encrypt_api_key()
{:ok, session_data} = ElixirMpesa.generate_session_key(encrypted_api_key)
session_key = session_data["output_SessionID"]
{:ok, encrypted_session_key} = ElixirMpesa.encrypt_session_key(session_key)

# Then, perform a C2B transaction
payment_data = %{
  "input_Amount" => 10.0,
  "input_Country" => "LES",
  "input_Currency" => "LSL",
  "input_CustomerMSISDN" => "26675000000",
  "input_ServiceProviderCode" => "00000",
  "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
  "input_TransactionReference" => "T12344C",
  "input_PurchasedItemsDesc" => "Test purchase"
}

{:ok, result} = ElixirMpesa.Transactions.c2b_single_stage(payment_data, encrypted_session_key)

Summary

Functions

Performs a Business to Business (B2B) single-stage payment.

Performs a Business to Customer (B2C) single-stage payment.

Performs a Customer to Business (C2B) single-stage payment.

Queries a beneficiary's name based on their mobile number.

Queries the status of a direct debit mandate.

Queries the status of a transaction.

Functions

b2b_single_stage(attrs, encrypt_api_key, options \\ [])

Performs a Business to Business (B2B) single-stage payment.

This function allows businesses to pay other businesses.

Parameters

  • attrs - Map containing the transaction details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_Amount" - The transaction amount
  • "input_Country" - The country code (e.g., "LES")
  • "input_Currency" - The currency code (e.g., "LSL")
  • "input_PrimaryPartyCode" - The primary party code (your business)
  • "input_ReceiverPartyCode" - The receiver party code (recipient business)
  • "input_ThirdPartyConversationID" - A unique ID for this transaction
  • "input_TransactionReference" - Your reference for this transaction
  • "input_PurchasedItemsDesc" - Description of the payment

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> payment_data = %{
...>   "input_Amount" => 1000.0,
...>   "input_Country" => "LES",
...>   "input_Currency" => "LSL",
...>   "input_PrimaryPartyCode" => "12345",
...>   "input_ReceiverPartyCode" => "54321",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_TransactionReference" => "T12344C",
...>   "input_PurchasedItemsDesc" => "Invoice payment"
...> }
iex> ElixirMpesa.Transactions.b2b_single_stage(payment_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}

b2c_single_stage(attrs, encrypt_api_key, options \\ [])

Performs a Business to Customer (B2C) single-stage payment.

This function allows businesses to pay customers, such as for disbursements, refunds, or salary payments.

Parameters

  • attrs - Map containing the transaction details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_Amount" - The transaction amount
  • "input_Country" - The country code (e.g., "LES")
  • "input_Currency" - The currency code (e.g., "LSL")
  • "input_CustomerMSISDN" - The recipient's phone number
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this transaction
  • "input_TransactionReference" - Your reference for this transaction
  • "input_PaymentItemsDesc" - Description of the payment

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> payment_data = %{
...>   "input_Amount" => 10.0,
...>   "input_Country" => "LES",
...>   "input_Currency" => "LSL",
...>   "input_CustomerMSISDN" => "26675000000",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_TransactionReference" => "T12344C",
...>   "input_PaymentItemsDesc" => "Salary payment"
...> }
iex> ElixirMpesa.Transactions.b2c_single_stage(payment_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}

c2b_single_stage(attrs, encrypt_api_key, options \\ [])

Performs a Customer to Business (C2B) single-stage payment.

This function allows customers to pay businesses for goods or services.

Parameters

  • attrs - Map containing the transaction details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_Amount" - The transaction amount
  • "input_Country" - The country code (e.g., "LES")
  • "input_Currency" - The currency code (e.g., "LSL")
  • "input_CustomerMSISDN" - The customer's phone number
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this transaction
  • "input_TransactionReference" - Your reference for this transaction
  • "input_PurchasedItemsDesc" - Description of the purchase

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> payment_data = %{
...>   "input_Amount" => 10.0,
...>   "input_Country" => "LES",
...>   "input_Currency" => "LSL",
...>   "input_CustomerMSISDN" => "26675000000",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_TransactionReference" => "T12344C",
...>   "input_PurchasedItemsDesc" => "Test purchase"
...> }
iex> ElixirMpesa.Transactions.c2b_single_stage(payment_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}

direct_debit_cancel(attrs, encrypt_api_key, options \\ [])

Cancels a direct debit mandate.

Parameters

  • attrs - Map containing the cancellation details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_CustomerMSISDN" - The customer's phone number
  • "input_Country" - The country code (e.g., "LES")
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this cancellation
  • "input_ThirdPartyReference" - The original mandate reference

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> cancel_data = %{
...>   "input_CustomerMSISDN" => "26675000000",
...>   "input_Country" => "LES",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_ThirdPartyReference" => "3333"
...> }
iex> ElixirMpesa.Transactions.direct_debit_cancel(cancel_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}

direct_debit_creation(attrs, encrypt_api_key, options \\ [])

Creates a direct debit mandate.

Parameters

  • attrs - Map containing the direct debit details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_AgreedTC" - Whether the customer has agreed to terms and conditions (boolean)
  • "input_Country" - The country code (e.g., "LES")
  • "input_CustomerMSISDN" - The customer's phone number
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this transaction
  • "input_ThirdPartyReference" - Your reference for this mandate

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> direct_debit_data = %{
...>   "input_AgreedTC" => true,
...>   "input_Country" => "LES",
...>   "input_CustomerMSISDN" => "26675000000",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_ThirdPartyReference" => "3333"
...> }
iex> ElixirMpesa.Transactions.direct_debit_creation(direct_debit_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}

direct_debit_payment(attrs, encrypt_api_key, options \\ [])

Processes a direct debit payment.

Parameters

  • attrs - Map containing the payment details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_Amount" - The transaction amount
  • "input_Country" - The country code (e.g., "LES")
  • "input_Currency" - The currency code (e.g., "LSL")
  • "input_CustomerMSISDN" - The customer's phone number
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this transaction
  • "input_ThirdPartyReference" - Your reference for this payment

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> payment_data = %{
...>   "input_Amount" => 10.0,
...>   "input_Country" => "LES",
...>   "input_Currency" => "LSL",
...>   "input_CustomerMSISDN" => "26675000000",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_ThirdPartyReference" => "3333"
...> }
iex> ElixirMpesa.Transactions.direct_debit_payment(payment_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}

query_beneficiary_name(attrs, encrypt_api_key, options \\ [])

Queries a beneficiary's name based on their mobile number.

Parameters

  • attrs - Map containing the query details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_CustomerMSISDN" - The customer's phone number
  • "input_Country" - The country code (e.g., "LES")
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this query

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> query_data = %{
...>   "input_CustomerMSISDN" => "26675000000",
...>   "input_Country" => "LES",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761"
...> }
iex> ElixirMpesa.Transactions.query_beneficiary_name(query_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", "output_CustomerFirstName" => "John", "output_CustomerLastName" => "Doe"}}

query_direct_debit(attrs, encrypt_api_key, options \\ [])

Queries the status of a direct debit mandate.

Parameters

  • attrs - Map containing the query details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_CustomerMSISDN" - The customer's phone number
  • "input_Country" - The country code (e.g., "LES")
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this query
  • "input_ThirdPartyReference" - The original mandate reference

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> query_data = %{
...>   "input_CustomerMSISDN" => "26675000000",
...>   "input_Country" => "LES",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_ThirdPartyReference" => "3333"
...> }
iex> ElixirMpesa.Transactions.query_direct_debit(query_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}

query_status(attrs, encrypt_api_key, options \\ [])

Queries the status of a transaction.

Parameters

  • attrs - Map containing the query details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_QueryReference" - The original transaction reference
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this query
  • "input_Country" - The country code (e.g., "LES")

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> query_data = %{
...>   "input_QueryReference" => "T12344C",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_Country" => "LES"
...> }
iex> ElixirMpesa.Transactions.query_status(query_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}

reversal(attrs, encrypt_api_key, options \\ [])

Reverses a transaction.

Parameters

  • attrs - Map containing the reversal details
  • encrypt_api_key - The encrypted session key
  • options - A keyword list of options (see below)

Options

  • :api_type - Override the configured API type ("sandbox" or "openapi")
  • :url_context - Override the configured URL context

Required Attributes

  • "input_ReversalAmount" - The amount to reverse
  • "input_Country" - The country code (e.g., "LES")
  • "input_ServiceProviderCode" - The service provider code
  • "input_ThirdPartyConversationID" - A unique ID for this reversal
  • "input_TransactionID" - The original transaction ID

Returns

  • {:ok, response} - The API response on success
  • {:error, reason} - If the API call fails

Examples

iex> reversal_data = %{
...>   "input_ReversalAmount" => 10.0,
...>   "input_Country" => "LES",
...>   "input_ServiceProviderCode" => "00000",
...>   "input_ThirdPartyConversationID" => "asv02e5958774f7ba228d83d0d689761",
...>   "input_TransactionID" => "12345678"
...> }
iex> ElixirMpesa.Transactions.reversal(reversal_data, encrypted_session_key)
{:ok, %{"output_ResponseCode" => "INS-0", "output_ResponseDesc" => "Request processed successfully", ...}}