AirtelMoney (airtel_money v0.1.0)

Airtel Money SDK for Elixir.

Provides a clean interface for interacting with Airtel Money APIs including:

Collections (receiving payments)
Disbursements (sending payments)
Transaction status queries
Balance queries
Webhook verification

Configuration

Configure the SDK in your config/config.exs:

config :airtel_money,
  client_id: "your_client_id",
  client_secret: "your_client_secret",
  country: "CD",
  currency: "CDF",
  environment: :sandbox

Usage

Collect a payment

{:ok, result} = AirtelMoney.collect(%{
  amount: "1000",
  msisdn: "2439xxxxxxx",
  reference: "INV-001"
})

Disburse a payment

{:ok, result} = AirtelMoney.disburse(%{
  amount: "5000",
  msisdn: "2439xxxxxxx",
  reference: "PAY-001"
})

Query transaction status

{:ok, status} = AirtelMoney.transaction_status("TXN123")

Query balance

{:ok, balance} = AirtelMoney.balance()

Verify webhook

case AirtelMoney.verify_webhook(payload, signature) do
  :ok -> # Valid webhook
  {:error, :invalid_signature} -> # Invalid signature
end

Summary

Functions

balance()

Queries the account balance.

collect(params)

Collects a payment from a customer.

disburse(params)

Disburses a payment to a customer.

parse_webhook(payload)

Parses a webhook payload.

transaction_status(transaction_id)

Queries the status of a transaction.

verify_webhook(payload, signature)

Verifies a webhook signature.

Functions

balance()

@spec balance() :: {:ok, map()} | {:error, AirtelMoney.Error.t()}

Queries the account balance.

Returns

{:ok, map()} - Account balance
{:error, AirtelMoney.Error.t()} - Failed query

collect(params)

@spec collect(map()) :: {:ok, map()} | {:error, AirtelMoney.Error.t()}

Collects a payment from a customer.

Parameters

params - A map with:
- :amount - Amount to collect (string)
- :msisdn - Customer phone number (string)
- :reference - Transaction reference (string)
- :id_type - Optional ID type (default: "MSISDN")
- :id_number - Optional ID number
- :callback_url - Optional callback URL

Returns

{:ok, map()} - Successful collection
{:error, AirtelMoney.Error.t()} - Failed collection

disburse(params)

@spec disburse(map()) :: {:ok, map()} | {:error, AirtelMoney.Error.t()}

Disburses a payment to a customer.

Parameters

params - A map with:
- :amount - Amount to disburse (string)
- :msisdn - Recipient phone number (string)
- :reference - Transaction reference (string)
- :id_type - Optional ID type (default: "MSISDN")
- :id_number - Optional ID number
- :callback_url - Optional callback URL

Returns

{:ok, map()} - Successful disbursement
{:error, AirtelMoney.Error.t()} - Failed disbursement

parse_webhook(payload)

@spec parse_webhook(String.t()) :: {:ok, map()} | {:error, :invalid_json}

Parses a webhook payload.

Parameters

payload - The raw JSON payload (string)

Returns

{:ok, map()} - Parsed payload
{:error, :invalid_json} - Invalid JSON

transaction_status(transaction_id)

@spec transaction_status(String.t()) :: {:ok, map()} | {:error, AirtelMoney.Error.t()}

Queries the status of a transaction.

Parameters

transaction_id - The transaction ID to query

Returns

{:ok, map()} - Transaction status
{:error, AirtelMoney.Error.t()} - Failed query

verify_webhook(payload, signature)

@spec verify_webhook(String.t(), String.t()) :: :ok | {:error, :invalid_signature}

Verifies a webhook signature.

Parameters

payload - The raw webhook payload (string)
signature - The signature from the X-Airtel-Signature header

Returns

:ok - Valid signature
{:error, :invalid_signature} - Invalid signature