gabrielmahia/mpesa-python

MPesa Python — Lightweight Python client for Safaricom M-Pesa Daraja API. STK push, B2C, C2B, and query endpoints. # daraja-v3 > Formerly `mpesa-python` — renamed to `daraja-v3` on PyPI (the original name was taken). **Production Python SDK for Safaricom M-Pesa Daraja v3.** Zero external dependencies. Type-annotated. Stripe-quality error handling. ```python from mpesa import MpesaClient client = MpesaClient( consumer_key="your_key", consumer_secret="your_secret", shortcode="174379", passkey="your_lnm_passkey", sandbox=True, # flip to False when you go live ) # Prompt customer phone to enter PIN result = client.stk_push( phone="0712345678", # any Kenyan format — normalised automatically amount=500, reference="Order-001", callback_url="yourapp.com", ) print(result.checkout_request_id) ``` --- ## Why this exists Every Kenya fintech project needs M-Pesa. Most of them roll their own wrapper — usually a 200-line `mpesa_utils.py` with no tests, swallowed exceptions, and phone number bugs. This is the library those teams should be importing instead. **Design goals (borrowed from Stripe's Python SDK):** - Fail before the network call when possible — `ValidationError` catches bad inputs locally - Typed results — no `response["Body"]["stkCallback"]["CallbackMetadata"]["Item"][0]["Value"]` - Token caching — never burn a request on an expired token - Composable exceptions — catch `MpesaError` broadly or specific subclasses narrowly - Zero dependencies — drop into any environment without conflicts --- ## Installation ```bash pip install daraja-v3 ``` Or from source: ```bash git clone github.com cd mpesa-python pip install -e ".[dev]" ``` --- ## Supported APIs | API | Method | What it does | |-----|--------|--------------| | STK Push | `client.stk_push()` | Prompt customer phone to pay | | STK Query | `client.stk_query()` | Check STK push status | | B2C | `client.b2c()` | Send money to customer wallet | | C2B Register | `client.c2b_register_urls()` | Register payment notification URLs | | Account Balan …