umojasdk 0.1.1

One SDK. Every African payment. Python SDK for M-Pesa, Airtel Money, and more.

umojasdk

One SDK. Every African payment.

UmojaSDK is the unified Python SDK for African mobile money integrations — M-Pesa (Safaricom Daraja 3.0), Airtel Money, and more.

Built by Synapse Softwares.

Installation

pip install umojasdk

Quickstart — M-Pesa STK Push

from umojasdk import UmojaMpesa, MpesaConfig, STKPushRequest

mpesa = UmojaMpesa(MpesaConfig(
    consumer_key="your_key",
    consumer_secret="your_secret",
    shortcode="174379",
    passkey="your_passkey",
    callback_url="https://yourapp.com/mpesa/callback",
    env="sandbox"
))

result = mpesa.stk_push(STKPushRequest(
    phone="0712345678",   # accepts 07XX, +2547XX, 2547XX — auto-normalized
    amount=1500,
    reference="ORDER-001"
))

print(result.checkout_request_id)

# Parse incoming Daraja callback
from umojasdk import parse_stk_callback

payment = parse_stk_callback(request_body)

if payment["success"]:
    print(payment["mpesa_receipt_number"])
    print(payment["amount"])

# CRITICAL: Always return 200 to stop Daraja retries
return {"ResultCode": 0, "ResultDesc": "Accepted"}

Quickstart — Airtel Money

from umojasdk import UmojaAirtel, AirtelConfig, AirtelCollectionRequest

airtel = UmojaAirtel(AirtelConfig(
    client_id="your_client_id",
    client_secret="your_client_secret",
    env="sandbox"
))

result = airtel.request_to_pay(AirtelCollectionRequest(
    phone="0733123456",
    amount=500,
    reference="ORDER-002"
))

Async Support

from umojasdk import AsyncUmojaMpesa, MpesaConfig, STKPushRequest

mpesa = AsyncUmojaMpesa(MpesaConfig(...))

result = await mpesa.stk_push(STKPushRequest(
    phone="0712345678",
    amount=1500,
    reference="ORDER-001"
))

Features

Feature	Status
STK Push (Lipa Na M-Pesa)	✓
STK Push status query	✓
C2B URL registration & callbacks	✓
B2C disbursements	✓
Transaction status query	✓
Transaction reversal	✓
SIM Swap detection (Daraja 3.0)	✓
Tax remittance to KRA (Daraja 3.0)	✓
Airtel Money collections	✓
Airtel Money disbursements	✓
Webhook parsing	✓
Phone number normalization	✓
Automatic token refresh	✓
Typed errors	✓
Async client	✓

Error Handling

from umojasdk.core.errors import UmojaAuthError, UmojaValidationError, UmojaApiError

try:
    result = mpesa.stk_push(req)
except UmojaAuthError:
    pass  # bad credentials
except UmojaValidationError as e:
    pass  # bad input — str(e) is human-readable
except UmojaApiError as e:
    pass  # Daraja error — e.raw has full response

Environment Variables

MPESA_CONSUMER_KEY=
MPESA_CONSUMER_SECRET=
MPESA_SHORTCODE=174379
MPESA_PASSKEY=
MPESA_CALLBACK_URL=
MPESA_ENV=sandbox         # "sandbox" | "production"

AIRTEL_CLIENT_ID=
AIRTEL_CLIENT_SECRET=
AIRTEL_ENV=sandbox

Related

• TypeScript SDK: npm install umojasdk
• CLI: npx @umojasdk/cli init
• Docs: umojasdk.dev

License

MIT — github.com/Knelso/Umoja_SDK

Built with precision in Nairobi, Kenya. For Africa, by Africa.