airtelmoney-ug
Python client for the Airtel Money Uganda Open APIs — Collections, Disbursements,
KYC and Account — with built-in request signing (x-signature / x-key) and
PIN encryption, automatic OAuth2 token management and friendly error-code lookups.
Features
- OAuth2 client-credentials token handling with caching/auto-refresh.
- Automatic message signing for write APIs (AES-256-CBC payload + RSA-encrypted key/IV).
- Automatic RSA PIN encryption for disbursements.
- Encryption-key fetching and caching.
- Typed exceptions and a complete map of documented
response_codevalues. - Fully covered by offline unit tests.
Installation
pip install airtelmoney-ug
For local development:
pip install -e ".[dev]"
Quick start
from airtelmoney import AirtelMoney
client = AirtelMoney(
client_id="YOUR_CLIENT_ID",
client_secret="YOUR_CLIENT_SECRET",
environment="staging", # or "production"
)
# Or load credentials from a JSON file (airtel_client_id / airtel_client_secret):
client = AirtelMoney.from_credentials_file("airtel_credentials.json")
# Or load from environment variables / a .env file (recommended):
client = AirtelMoney.from_env()
Default base URLs are
https://openapiuat.airtel.ug(staging) andhttps://openapi.airtel.ug(production). Passbase_url=...to override, e.g. for the pan-African endpointshttps://openapi.airtel.africa.
Configuration via .env
Install the optional dependency and copy .env.example to .env:
pip install "airtelmoney-py[env]"
cp .env.example .env
| Variable | Description | Default |
|---|---|---|
AIRTEL_CLIENT_ID |
Application client id (required) | — |
AIRTEL_CLIENT_SECRET |
Application client secret (required) | — |
AIRTEL_ENVIRONMENT |
staging or production |
staging |
AIRTEL_BASE_URL |
Explicit base URL (overrides environment) | — |
AIRTEL_COUNTRY |
X-Country header |
UG |
AIRTEL_CURRENCY |
X-Currency header |
UGX |
from airtelmoney import AirtelMoney
client = AirtelMoney.from_env() # reads .env if python-dotenv is installed
Usage
Collections
# USSD push payment (payload signed automatically using the consumer RSA key)
res = client.collection.payment(
reference="Order #123",
msisdn="752604392",
amount=1000,
)
txn_id = res["data"]["transaction"]["id"]
# Transaction enquiry
client.collection.enquiry(txn_id)
# Refund a successful transaction
client.collection.refund("CI210104.1105.C00018")
Disbursements
# PIN is RSA-encrypted with the consumer public key automatically
res = client.disbursement.payment(
msisdn="752604392",
amount=500,
reference="payout-1",
pin="1234",
)
client.disbursement.enquiry(res["data"]["transaction"]["id"])
# Already have an encrypted PIN? Pass it directly:
client.disbursement.payment(
msisdn="752604392", amount=500, reference="p-2",
encrypted_pin="KYJExln8rZwb14G1K5UE5YF/lD7KheNUM171MUEG3/f/QD8nmNKRsa44",
)
KYC and Account
client.kyc.user_enquiry("256752604392")
client.account.balance()
Callbacks
Airtel posts transaction updates to your configured callback URL. For authenticated callbacks you can verify the signature:
# payload is the decoded JSON body Airtel POSTed to your callback URL
valid = client.collection.verify_callback_hash(payload, secret="YOUR_CLIENT_SECRET")
Manual signing / encryption
The signing primitives are exposed if you need them directly:
from airtelmoney import sign_payload, encrypt_pin
public_key = client.get_encryption_key() # base64 DER RSA public key
signed = sign_payload(public_key, {"reference": "1234", "transaction": {"id": "x"}})
# signed.payload -> exact JSON body you MUST send
# signed.x_signature -> x-signature header
# signed.x_key -> x-key header
enc_pin = encrypt_pin(public_key, "1234")
How signing works
- Generate a random 256-bit AES key and 128-bit IV.
- Base64-encode the key and IV.
- Fetch the consumer RSA public key (
client.get_encryption_key()). - Encrypt the JSON payload with
AES/CBC/PKCS5Padding→x-signatureheader. - Concatenate
key:iv(both base64) and RSA-encrypt with the public key →x-keyheader.
The server decrypts key:iv with its private RSA key, re-encrypts the received payload
and compares it against x-signature. A mismatch yields a Forbidden
(DP00800001026 / DP00900001016).
Error handling
from airtelmoney import AirtelAPIError, describe, is_success
try:
res = client.account.balance()
except AirtelAPIError as exc:
print(exc.status_code, exc.response_code, exc.message)
# Interpret any documented response code
info = describe("DP00800001007") # ResponseCode(code=..., reason='Not enough balance', ...)
is_success("DP00800001001") # True
Response codes
All documented codes are available via airtelmoney.RESPONSE_CODES and describe(),
covering encryption, collection (DP008...), disbursement (DP009...), user
enquiry (DP022...) and balance (DP021...).
Testing
pip install -e ".[dev]"
pytest
License
MIT
Metadata
Release files for airtelmoney-py 1.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| airtelmoney_py-1.0.6.tar.gz | 20.6 kB | With provenance | Details for airtelmoney_py-1.0.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| airtelmoney_py-1.0.6-py3-none-any.whl | Python 3 | none | any | Details for airtelmoney_py-1.0.6-py3-none-any.whl |
Total release size: 40.0 kB
Release files / airtelmoney_py-1.0.6.tar.gz
| Download URL | airtelmoney_py-1.0.6.tar.gz |
|---|---|
| Size | 20.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
983baa7e20c8e01c218b755f4408d53c0dbdb425552d7128058711e69626d46e
|
|
BLAKE2b-256 checksum How to use checksums |
c1b808538e2fd298d00b8f897501e94af4aaad226f4db5bdb81fae9a25334b64
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 29, 2026.
Transparency logRelease files / airtelmoney_py-1.0.6-py3-none-any.whl
| Download URL | airtelmoney_py-1.0.6-py3-none-any.whl |
|---|---|
| Size | 19.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e8e1f18b8470b5ac74e2a7c6753553d2434ab2ec2a4da7ffaf81bbd241695d55
|
|
BLAKE2b-256 checksum How to use checksums |
c5eb3ebc4d1cb5362995a7a8ffc590186f4031d9f6835fc23b3b805e4af08131
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 29, 2026.
Transparency logSecurity for airtelmoney-py 1.0.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for airtelmoney_py-1.0.6.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jun 29, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.