Metadata-Version: 2.4
Name: yourdudeken-mpesa-sdk
Version: 1.3.8
Summary: Production-grade Python SDK for Safaricom M-Pesa Daraja API
Project-URL: Homepage, https://github.com/yourdudeken/mpesa-sdk
Project-URL: Repository, https://github.com/yourdudeken/mpesa-sdk
Author: M-Pesa SDK Team
License: MIT
Keywords: daraja,mobile-money,mpesa,payment,safaricom
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: all
Requires-Dist: django>=4.2.0; extra == 'all'
Requires-Dist: fastapi>=0.100.0; extra == 'all'
Requires-Dist: flask>=2.3.0; extra == 'all'
Provides-Extra: django
Requires-Dist: django>=4.2.0; extra == 'django'
Provides-Extra: fastapi
Requires-Dist: fastapi>=0.100.0; extra == 'fastapi'
Provides-Extra: flask
Requires-Dist: flask>=2.3.0; extra == 'flask'
Description-Content-Type: text/markdown

# M-Pesa SDK — Python

Production-grade Python SDK for Safaricom M-Pesa Daraja API.

## Installation

```bash
pip install yourdudeken-mpesa-sdk
```

Requires Python 3.11+.

## Quick Start

```python
from mpesa import Mpesa

client = Mpesa({
    "consumer_key": "your_consumer_key",
    "consumer_secret": "your_consumer_secret",
    "environment": "sandbox",
    "passkey": "your_passkey",
})

response = client.stk_push({
    "BusinessShortCode": 174379,
    "TransactionType": "CustomerPayBillOnline",
    "Amount": 1,
    "PartyA": 254722000000,
    "PartyB": 174379,
    "PhoneNumber": 254722111111,
    "CallBackURL": "https://example.com/callback",
    "AccountReference": "INV-001",
    "TransactionDesc": "Payment",
})

print(f"Checkout ID: {response.CheckoutRequestID}")
```

## Features

- OAuth authentication with automatic token management
- STK Push (M-Pesa Express)
- STK Query
- C2B (Register URL & Simulate)
- B2C (Business to Customer)
- B2B (Business to Business)
- Transaction Reversal
- Transaction Status Query
- Account Balance Query
- Dynamic QR Generation
- Webhook handling with event-driven architecture
- Structured error hierarchy
- Retry with exponential backoff
- Pydantic v2 models for request/response validation

### Enterprise Features

- Circuit Breaker for automatic failure detection
- Rate Limiting (token bucket algorithm)
- Batch Requests for concurrent execution
- Webhook Retry & DLQ for reliable delivery
- OpenTelemetry Tracing and Prometheus Metrics

### Example: Resilience Configuration

```python
client = Mpesa({
    "consumer_key": "your_consumer_key",
    "consumer_secret": "your_consumer_secret",
    "environment": "sandbox",
    "passkey": "your_passkey",
    "resilience": {
        "circuit_breaker": {
            "failure_threshold": 5,
            "success_threshold": 2,
            "timeout": 60000,
        },
        "rate_limiter": {
            "capacity": 100,
            "refill_rate": 10,
            "refill_interval": 1000,
        },
        "batch": {
            "max_concurrent": 5,
            "timeout": 30000,
            "retry_failures": True,
        },
    },
})
```

## Documentation

Full documentation: [https://yourdudeken.github.io/mpesa-sdk](https://yourdudeken.github.io/mpesa-sdk)
