ronaldgosso/pyairtel

Python client for Airtel Money Tanzania — Collection & Disbursement APIs. # pyairtel > Python client for **Airtel Money Tanzania** — Collection & Disbursement APIs. 📖 **Full documentation & examples → ronaldgosso.github.io --- ## Features - 🔐 **OAuth2 authentication** with automatic token refresh - 📲 **Collection** — USSD push payments (request money from subscribers) - ✅ **Transaction status** polling - 💸 **Disbursement** — transfer money to Airtel Money wallets - ↩️ **Refunds** — reverse completed transactions by `airtel_money_id` - 🔒 **RSA PIN encryption** for disbursement security - 📞 **Phone number normalisation** (handles `+255…`, `0…`, `255…` formats) - ⚠️ **ESB error decoding** — all 9 Airtel Tanzania error codes mapped to human-readable messages - 🧪 **Sandbox & Production** environments --- ## Installation ```bash pip install pyairtel ``` For disbursement with PIN encryption, install the encryption extra: ```bash pip install "pyairtel[encryption]" ``` --- ## Quick Start ### 1. Get credentials Create an account at developers.airtel.co.tz, create an application, and add **Collection** and **Disbursement** APIs. Copy your `client_id` and `client_secret` from **Key Management**. ### 2. Collect money from a subscriber ```python from dotenv import load_dotenv import os from pyairtel import AirtelMoney load_dotenv() airtel = AirtelMoney( client_id=os.environ["AIRTEL_CLIENT_ID"], client_secret=os.environ["AIRTEL_CLIENT_SECRET"], sandbox=os.getenv("AIRTEL_SANDBOX", "true").lower() == "true", # set False for production ) response = airtel.collect( phone="+255681219610", amount=5000, reference="invoice-42", ) print(response.transaction_id) # TXN-20240101120000123456-AB12CD34 print(response.is_initiated) # True ``` ### 3. Check transaction status ```python import time time.sleep(15) # give the subscriber time to approve status = airtel.get_collection_status(response.transaction_id) if status.is_successful: print("Payment confirmed!", status.airtel_money_id) elif status.is_pending: print( …