mpesa-wrapper 1.0.0

Production-ready M-Pesa (Daraja API) SDK for Python

💳 mpesa-wrapper

Production-ready M-Pesa (Daraja API) SDK for Python.

A type-safe, robust, and modern wrapper for Safaricom's M-Pesa APIs, designed for both synchronous and asynchronous applications.

🚀 Features

• Stripe-level DX: Type-safe responses with Pydantic (full autocomplete).
• Production-First: Automatic phone number masking in logs, RSA security credential generation, and config protection.
• Resilient: Built-in exponential backoff retries for network and server errors.
• Idempotency: Automatic X-Idempotency-Key management for critical transactions.
• Async Support: Native AsyncMpesaClient for FastAPI and other async frameworks.
• Comprehensive: Supports STK Push, B2C, C2B, Reversal, Transaction Status, and Account Balance.

📦 Install

pip install mpesa-wrapper

For web-related features (FastAPI demo):

pip install "mpesa-wrapper[web]"

⚡ Quick Start

from mpesa_wrapper import MpesaClient

# Initialize from environment variables
client = MpesaClient.from_env()

# STK Push (Lipa Na M-PESA Online)
response = client.stk_push(
    phone_number="254712345678",
    amount=1,
    account_reference="Order123",
    transaction_desc="Payment for shoes"
)

# Type-safe access with autocomplete!
if response.response_code == "0":
    print(f"Success! CheckoutID: {response.checkout_request_id}")

🔐 Configuration

Create a .env file based on .env.example:

MPESA_CONSUMER_KEY=your_key
MPESA_CONSUMER_SECRET=your_secret
MPESA_SHORTCODE=174379
MPESA_PASSKEY=your_passkey
MPESA_ENV=sandbox

# Required for B2C, Reversal, Balance, Status
MPESA_INITIATOR_NAME=testapi
MPESA_INITIATOR_PASSWORD=your_password
MPESA_CERTIFICATE_PATH=./path/to/cert.cer
MPESA_RESULT_URL=https://your-domain.com/result
MPESA_TIMEOUT_URL=https://your-domain.com/timeout

🐳 Running the Demo (Docker)

docker build -t mpesa-demo .
docker run -p 8000:8000 --env-file .env mpesa-demo

📄 License

Distributed under the MIT License. See LICENSE for more information.