safcom 0.1.0__py3-none-any.whl

safcom/__init__.py

@@ -0,0 +1,4 @@
+from safcom.mpesa import Mpesa
+from safcom.exceptions import SafcomError, AuthError, APIError, ValidationError
+
+__all__ = ["Mpesa", "SafcomError", "AuthError", "APIError", "ValidationError"]

safcom/auth.py

@@ -0,0 +1,52 @@
+import datetime
+import httpx
+from safcom.exceptions import AuthError
+
+BASE_URLS = {
+    "sandbox": "https://sandbox.safaricom.co.ke",
+    "production": "https://api.safaricom.co.ke",
+}
+
+
+class Auth:
+    """Handles M-Pesa OAuth token generation with automatic refresh."""
+
+    def __init__(self, consumer_key: str, consumer_secret: str, env: str = "sandbox"):
+        self.consumer_key = consumer_key
+        self.consumer_secret = consumer_secret
+        self.base_url = BASE_URLS.get(env)
+        if not self.base_url:
+            raise ValueError(f"env must be 'sandbox' or 'production', got '{env}'")
+        self._token: str | None = None
+        self._expires_at: datetime.datetime | None = None
+
+    @property
+    def token(self) -> str:
+        """Get a valid token, refreshing automatically if expired."""
+        if self._token and self._expires_at and datetime.datetime.utcnow() < self._expires_at:
+            return self._token
+        return self._refresh()
+
+    def _refresh(self) -> str:
+        """Request a new OAuth token from the M-Pesa API."""
+        url = f"{self.base_url}/oauth/v1/generate?grant_type=client_credentials"
+        try:
+            resp = httpx.get(url, auth=(self.consumer_key, self.consumer_secret), timeout=10)
+            resp.raise_for_status()
+            data = resp.json()
+        except httpx.HTTPStatusError as e:
+            raise AuthError(f"Authentication failed: {e.response.status_code} {e.response.text}")
+        except httpx.RequestError as e:
+            raise AuthError(f"Could not reach M-Pesa API: {e}")
+
+        token = data.get("access_token")
+        if not token:
+            raise AuthError(f"Unexpected auth response: {data}")
+
+        # Token expires in 3600 seconds (1 hour) per M-Pesa docs
+        expires_in = data.get("expires_in", 3600)
+        self._token = token
+        self._expires_at = datetime.datetime.utcnow() + datetime.timedelta(
+            seconds=int(expires_in) - 60  # 60s buffer
+        )
+        return self._token

safcom/cli.py

@@ -0,0 +1,93 @@
+"""Command-line interface for safcom."""
+
+import argparse
+import os
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="safcom",
+        description="M-Pesa toolkit from the terminal",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # ── stkpush ──
+    stk = sub.add_parser("stkpush", help="Send an STK push to a phone")
+    stk.add_argument("phone", help="Phone number (e.g. 254712345678)")
+    stk.add_argument("amount", type=int, help="Amount to charge")
+    stk.add_argument("--ref", default="INV-001", help="Account reference")
+    stk.add_argument("--desc", help="Transaction description")
+    stk.add_argument("--callback", help="Callback URL")
+    stk.add_argument("--key", help="Consumer key (or SAFCOM_CONSUMER_KEY)")
+    stk.add_argument("--secret", help="Consumer secret (or SAFCOM_CONSUMER_SECRET)")
+    stk.add_argument("--passkey", help="Passkey (or SAFCOM_PASSKEY)")
+    stk.add_argument("--shortcode", help="Shortcode (or SAFCOM_SHORTCODE)")
+    stk.add_argument("--env", choices=["sandbox", "production"], default="sandbox")
+
+    # ── query ──
+    q = sub.add_parser("query", help="Query STK push status")
+    q.add_argument("checkout_id", help="CheckoutRequestID from stkpush")
+    q.add_argument("--key", help="Consumer key (or SAFCOM_CONSUMER_KEY)")
+    q.add_argument("--secret", help="Consumer secret (or SAFCOM_CONSUMER_SECRET)")
+    q.add_argument("--passkey", help="Passkey (or SAFCOM_PASSKEY)")
+    q.add_argument("--shortcode", help="Shortcode (or SAFCOM_SHORTCODE)")
+    q.add_argument("--env", choices=["sandbox", "production"], default="sandbox")
+
+    args = parser.parse_args()
+
+    # Credentials from args or env vars
+    consumer_key = args.key or os.environ.get("SAFCOM_CONSUMER_KEY")
+    consumer_secret = args.secret or os.environ.get("SAFCOM_CONSUMER_SECRET")
+    passkey = args.passkey or os.environ.get("SAFCOM_PASSKEY")
+    shortcode = args.shortcode or os.environ.get("SAFCOM_SHORTCODE")
+
+    missing = []
+    if not consumer_key:
+        missing.append("consumer key")
+    if not consumer_secret:
+        missing.append("consumer secret")
+    if not passkey:
+        missing.append("passkey")
+    if not shortcode:
+        missing.append("shortcode")
+    if missing:
+        print(f"Error: Missing {', '.join(missing)}. Provide via --flags or environment variables.")
+        sys.exit(1)
+
+    from safcom import Mpesa
+
+    mpesa = Mpesa(
+        consumer_key=consumer_key,
+        consumer_secret=consumer_secret,
+        passkey=passkey,
+        shortcode=shortcode,
+        env=args.env,
+    )
+
+    if args.command == "stkpush":
+        if args.callback:
+            mpesa.set_callback_url(args.callback)
+        resp = mpesa.stk_push(
+            phone=args.phone,
+            amount=args.amount,
+            account_ref=args.ref,
+            transaction_desc=args.desc,
+        )
+        print(f"✅ STK push sent!")
+        print(f"   CheckoutRequestID: {resp.checkout_request_id}")
+        print(f"   Message: {resp.customer_message}")
+
+    elif args.command == "query":
+        status = mpesa.stk_push_query(args.checkout_id)
+        print(f"Status: {'✅ Paid' if status.success else '❌ ' + (status.result_description or 'Pending')}")
+        if status.receipt:
+            print(f"   Receipt: {status.receipt}")
+        if status.amount:
+            print(f"   Amount: KES {status.amount}")
+        if status.phone:
+            print(f"   Phone: {status.phone}")
+
+
+if __name__ == "__main__":
+    main()

safcom/exceptions.py

@@ -0,0 +1,17 @@
+class SafcomError(Exception):
+    """Base exception for all safcom errors."""
+    pass
+
+class AuthError(SafcomError):
+    """Raised when M-Pesa authentication fails."""
+    pass
+
+class APIError(SafcomError):
+    """Raised when the M-Pesa API returns an error response."""
+    def __init__(self, message: str, response_code: str | None = None):
+        self.response_code = response_code
+        super().__init__(f"[{response_code}] {message}" if response_code else message)
+
+class ValidationError(SafcomError):
+    """Raised when input validation fails."""
+    pass

safcom/models.py

@@ -0,0 +1,54 @@
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional
+
+
+@dataclass
+class STKPushResponse:
+    """Response from an STK push request."""
+    merchant_request_id: str
+    checkout_request_id: str
+    response_code: str
+    response_description: str
+    customer_message: str
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class STKPushStatus:
+    """Status of a completed STK push transaction."""
+    response_code: str
+    response_description: str
+    merchant_request_id: str
+    checkout_request_id: str
+    result_code: str | None = None
+    result_description: str | None = None
+    amount: float | None = None
+    receipt: str | None = None
+    transaction_date: datetime | None = None
+    phone: str | None = None
+    raw: dict = field(default_factory=dict, repr=False)
+
+    @property
+    def success(self) -> bool:
+        return self.result_code == "0"
+
+
+@dataclass
+class B2CResponse:
+    """Response from a B2C (send money) request."""
+    conversation_id: str
+    originator_conversation_id: str
+    response_code: str
+    response_description: str
+    raw: dict = field(repr=False)
+
+
+@dataclass
+class AccountBalanceResponse:
+    """Response from an account balance request."""
+    conversation_id: str
+    originator_conversation_id: str
+    response_code: str
+    response_description: str
+    raw: dict = field(repr=False)

safcom/mpesa.py

@@ -0,0 +1,303 @@
+import base64
+import datetime
+import httpx
+from typing import Callable
+
+from safcom.auth import Auth, BASE_URLS
+from safcom.exceptions import APIError, ValidationError
+from safcom.models import (
+    STKPushResponse,
+    STKPushStatus,
+    B2CResponse,
+    AccountBalanceResponse,
+)
+
+
+class Mpesa:
+    """M-Pesa API client.
+
+    Usage:
+        from safcom import Mpesa
+
+        mpesa = Mpesa(
+            consumer_key="your_key",
+            consumer_secret="your_secret",
+            passkey="your_passkey",
+            shortcode="174379",
+            env="sandbox"
+        )
+
+        response = mpesa.stk_push(
+            phone="254712345678",
+            amount=100,
+            account_ref="INV-001",
+        )
+    """
+
+    def __init__(
+        self,
+        consumer_key: str,
+        consumer_secret: str,
+        passkey: str,
+        shortcode: str,
+        env: str = "sandbox",
+    ):
+        if env not in ("sandbox", "production"):
+            raise ValueError(f"env must be 'sandbox' or 'production', got '{env}'")
+
+        self.shortcode = shortcode
+        self.passkey = passkey
+        self.env = env
+        self.base_url = BASE_URLS[env]
+        self._auth = Auth(consumer_key, consumer_secret, env)
+        self._callback_url: str | None = None
+
+    @property
+    def _headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self._auth.token}",
+            "Content-Type": "application/json",
+        }
+
+    # ── Configuration ──────────────────────────────────────────────
+
+    def set_callback_url(self, url: str) -> None:
+        """Set the default callback URL for transaction notifications."""
+        self._callback_url = url
+
+    # ── STK Push (Lipa Na M-Pesa Online) ──────────────────────────
+
+    def stk_push(
+        self,
+        phone: str,
+        amount: float,
+        account_ref: str,
+        transaction_desc: str | None = None,
+        callback_url: str | None = None,
+    ) -> STKPushResponse:
+        """Initiate an STK push to a customer's phone.
+
+        Args:
+            phone: Customer phone number (e.g. 254712345678).
+            amount: Amount to charge.
+            account_ref: Account reference visible to the customer.
+            transaction_desc: Optional description (defaults to account_ref).
+            callback_url: Override the default callback URL for this request.
+
+        Returns:
+            STKPushResponse with checkout details.
+
+        Raises:
+            ValidationError: If input validation fails.
+            APIError: If the API returns an error.
+        """
+        phone = self._normalise_phone(phone)
+        if amount <= 0:
+            raise ValidationError("amount must be greater than 0")
+        if not account_ref or len(account_ref) > 12:
+            raise ValidationError("account_ref must be 1–12 characters")
+
+        timestamp = self._timestamp()
+        password = self._password(timestamp)
+        callback = callback_url or self._callback_url
+
+        payload = {
+            "BusinessShortCode": self.shortcode,
+            "Password": password,
+            "Timestamp": timestamp,
+            "TransactionType": "CustomerPayBillOnline",
+            "Amount": int(round(amount)),
+            "PartyA": phone,
+            "PartyB": self.shortcode,
+            "PhoneNumber": phone,
+            "CallBackURL": callback or "",
+            "AccountReference": account_ref,
+            "TransactionDesc": transaction_desc or account_ref,
+        }
+
+        resp = self._post("/mpesa/stkpush/v1/processrequest", payload)
+        return STKPushResponse(
+            merchant_request_id=resp.get("MerchantRequestID", ""),
+            checkout_request_id=resp.get("CheckoutRequestID", ""),
+            response_code=resp.get("ResponseCode", ""),
+            response_description=resp.get("ResponseDescription", ""),
+            customer_message=resp.get("CustomerMessage", ""),
+            raw=resp,
+        )
+
+    def stk_push_query(self, checkout_request_id: str) -> STKPushStatus:
+        """Query the status of an STK push transaction.
+
+        Args:
+            checkout_request_id: The CheckoutRequestID from stk_push().
+
+        Returns:
+            STKPushStatus with transaction details.
+        """
+        timestamp = self._timestamp()
+        password = self._password(timestamp)
+
+        payload = {
+            "BusinessShortCode": self.shortcode,
+            "Password": password,
+            "Timestamp": timestamp,
+            "CheckoutRequestID": checkout_request_id,
+        }
+
+        resp = self._post("/mpesa/stkpushquery/v1/query", payload)
+
+        date_str = resp.get("TransactionDate", "")
+        transaction_date = None
+        if date_str:
+            try:
+                transaction_date = datetime.datetime.strptime(str(date_str), "%Y%m%d%H%M%S")
+            except ValueError:
+                pass
+
+        return STKPushStatus(
+            response_code=resp.get("ResponseCode", ""),
+            response_description=resp.get("ResponseDescription", ""),
+            merchant_request_id=resp.get("MerchantRequestID", ""),
+            checkout_request_id=resp.get("CheckoutRequestID", ""),
+            result_code=resp.get("ResultCode"),
+            result_description=resp.get("ResultDesc"),
+            amount=float(resp["Amount"]) if resp.get("Amount") else None,
+            receipt=resp.get("MpesaReceiptNumber"),
+            transaction_date=transaction_date,
+            phone=resp.get("PhoneNumber"),
+            raw=resp,
+        )
+
+    # ── B2C (Send money to customer) ──────────────────────────────
+
+    def b2c(
+        self,
+        phone: str,
+        amount: float,
+        remarks: str = "payment",
+        initiator_name: str = "testapi",
+        security_credential: str = "",
+        occasion: str = "",
+    ) -> B2CResponse:
+        """Send money to a customer (B2C payment).
+
+        Args:
+            phone: Recipient phone number (e.g. 254712345678).
+            amount: Amount to send.
+            remarks: Optional remark.
+            initiator_name: API initiator name (configured in M-Pesa portal).
+            security_credential: Encrypted security credential.
+            occasion: Optional occasion field.
+
+        Returns:
+            B2CResponse with conversation details.
+        """
+        phone = self._normalise_phone(phone)
+        if amount <= 0:
+            raise ValidationError("amount must be greater than 0")
+
+        payload = {
+            "InitiatorName": initiator_name,
+            "SecurityCredential": security_credential,
+            "CommandID": "BusinessPayment",
+            "Amount": int(round(amount)),
+            "PartyA": self.shortcode,
+            "PartyB": phone,
+            "Remarks": remarks,
+            "QueueTimeOutURL": self._callback_url or "",
+            "ResultURL": self._callback_url or "",
+            "Occasion": occasion or "",
+        }
+
+        resp = self._post("/mpesa/b2c/v3/paymentrequest", payload)
+        return B2CResponse(
+            conversation_id=resp.get("ConversationID", ""),
+            originator_conversation_id=resp.get("OriginatorConversationID", ""),
+            response_code=resp.get("ResponseCode", ""),
+            response_description=resp.get("ResponseDescription", ""),
+            raw=resp,
+        )
+
+    # ── Account Balance ──────────────────────────────────────────
+
+    def account_balance(
+        self,
+        initiator_name: str = "testapi",
+        security_credential: str = "",
+    ) -> AccountBalanceResponse:
+        """Query M-Pesa account balance.
+
+        Args:
+            initiator_name: API initiator name (configured in M-Pesa portal).
+            security_credential: Encrypted security credential.
+
+        Returns:
+            AccountBalanceResponse with conversation details.
+        """
+        payload = {
+            "InitiatorName": initiator_name,
+            "SecurityCredential": security_credential,
+            "CommandID": "AccountBalance",
+            "PartyA": self.shortcode,
+            "IdentifierType": "4",
+            "QueueTimeOutURL": self._callback_url or "",
+            "ResultURL": self._callback_url or "",
+        }
+
+        resp = self._post("/mpesa/accountbalance/v1/query", payload)
+        return AccountBalanceResponse(
+            conversation_id=resp.get("ConversationID", ""),
+            originator_conversation_id=resp.get("OriginatorConversationID", ""),
+            response_code=resp.get("ResponseCode", ""),
+            response_description=resp.get("ResponseDescription", ""),
+            raw=resp,
+        )
+
+    # ── Helpers ──────────────────────────────────────────────────
+
+    def _post(self, path: str, payload: dict) -> dict:
+        url = f"{self.base_url}{path}"
+        try:
+            resp = httpx.post(url, json=payload, headers=self._headers, timeout=30)
+            data = resp.json()
+        except httpx.HTTPStatusError as e:
+            raise APIError(f"HTTP {e.response.status_code}: {e.response.text}")
+        except httpx.RequestError as e:
+            raise APIError(f"Request failed: {e}")
+        except ValueError:
+            raise APIError(f"Non-JSON response: {resp.text}")
+
+        # M-Pesa returns ResponseCode in various places
+        error_code = data.get("ResponseCode")
+        if error_code and error_code != "0":
+            raise APIError(
+                message=data.get("ResponseDescription", "M-Pesa API error"),
+                response_code=error_code,
+            )
+
+        return data
+
+    @staticmethod
+    def _normalise_phone(phone: str) -> str:
+        """Normalise a Kenyan phone number to 254 format."""
+        cleaned = phone.strip().replace(" ", "").replace("-", "")
+        if cleaned.startswith("+"):
+            cleaned = cleaned[1:]
+        if cleaned.startswith("0"):
+            cleaned = "254" + cleaned[1:]
+        if not cleaned.startswith("254"):
+            raise ValidationError(
+                f"Phone number must start with 254 or 0, got '{phone}'"
+            )
+        if len(cleaned) != 12:
+            raise ValidationError(
+                f"Phone number must be 12 digits in 254 format, got {len(cleaned)} digits"
+            )
+        return cleaned
+
+    def _timestamp(self) -> str:
+        return datetime.datetime.now().strftime("%Y%m%d%H%M%S")
+
+    def _password(self, timestamp: str) -> str:
+        raw = f"{self.shortcode}{self.passkey}{timestamp}"
+        return base64.b64encode(raw.encode()).decode()

safcom-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: safcom
+Version: 0.1.0
+Summary: M-Pesa API wrapper for Kenyan developers — STK push, callbacks, B2C, and more.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: httpx>=0.27.0
+
+<h1 align="center">safcom</h1>
+<p align="center">
+  <em>M-Pesa API — the way it should be.</em>
+  <br>
+  <br>
+  <img src="https://img.shields.io/badge/python-≥3.10-10b981" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/license-MIT-10b981" alt="MIT License">
+  <img src="https://img.shields.io/badge/version-0.1.0-10b981" alt="Version 0.1.0">
+</p>
+
+---
+
+STK push, payment queries, B2C, account balance — all in a clean Python package that doesn't make you read raw JSON.
+
+```bash
+pip install safcom
+```
+
+## Quick Start
+
+```python
+from safcom import Mpesa
+
+mpesa = Mpesa(
+    consumer_key="your_key",
+    consumer_secret="your_secret",
+    passkey="your_passkey",
+    shortcode="174379",
+    env="sandbox",      # or "production"
+)
+
+# One line. STK push. Done.
+resp = mpesa.stk_push(
+    phone="254712345678",
+    amount=100,
+    account_ref="INV-001",
+)
+
+print(resp.checkout_request_id)   # → "ws_CO_...202507..."
+print(resp.customer_message)      # → "Please enter your M-Pesa PIN"
+```
+
+## Features
+
+- **STK Push** — Initiate Lipa Na M-Pesa Online payments with one call
+- **STK Push Query** — Check if a payment went through
+- **B2C** — Send money to customers (BusinessPayment)
+- **Account Balance** — Query your M-Pesa balance
+- **Callback handling** — Decorator-based handler for M-Pesa notifications
+- **Automatic auth** — Tokens refresh automatically; you never think about it
+- **Typed responses** — Every response is a dataclass, not raw dicts
+- **CLI included** — Test payments from the terminal
+
+## Usage
+
+### STK Push
+
+```python
+# Minimal
+resp = mpesa.stk_push(phone="254712345678", amount=500, account_ref="INV-001")
+
+# With all options
+resp = mpesa.stk_push(
+    phone="254712345678",
+    amount=500,
+    account_ref="INV-001",
+    transaction_desc="Payment for invoice INV-001",
+    callback_url="https://your-app.com/mpesa/callback",
+)
+```
+
+### Check Payment Status
+
+```python
+status = mpesa.stk_push_query("ws_CO_...202507...")
+
+if status.success:
+    print(f"Paid! Receipt: {status.receipt}")
+else:
+    print(f"Not paid: {status.result_description}")
+```
+
+### Send Money (B2C)
+
+```python
+resp = mpesa.b2c(
+    phone="254712345678",
+    amount=500,
+    remarks="refund",
+    initiator_name="testapi",
+    security_credential="...",
+)
+```
+
+### Account Balance
+
+```python
+resp = mpesa.account_balance(
+    initiator_name="testapi",
+    security_credential="...",
+)
+```
+
+### From the CLI
+
+```bash
+# Set credentials (or use SAFCOM_* env vars)
+export SAFCOM_CONSUMER_KEY=your_key
+export SAFCOM_CONSUMER_SECRET=your_secret
+export SAFCOM_PASSKEY=your_passkey
+export SAFCOM_SHORTCODE=174379
+
+# Send STK push
+safcom stkpush 254712345678 100 --ref INV-001
+
+# Query payment status
+safcom query ws_CO_...202507...
+```
+
+## Why safcom?
+
+The M-Pesa API is powerful but painful:
+
+- Authentication is manual and easy to mess up
+- Responses come in inconsistent formats between sandbox and production
+- Error messages are cryptic
+- Every Kenyan dev rewrites the same wrapper
+
+safcom fixes all of that. Sensible defaults, typed responses, clear errors. One package, one `pip install`, done.
+
+## Roadmap
+
+- [x] STK Push
+- [x] STK Push Query
+- [x] B2C (BusinessPayment)
+- [x] Account Balance
+- [x] CLI
+- [ ] C2B Register URL
+- [ ] C2B Simulate
+- [ ] Reversal
+- [ ] Transaction Status
+- [ ] Async support (httpx.AsyncClient)
+
+## License
+
+MIT

safcom-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+safcom/__init__.py,sha256=BtMGb_FsMrht4WR2w8aU5SM5GW-OBTlvik6uMGp-8Ss,191
+safcom/auth.py,sha256=vXVwLbxN175DCjVjPoZ3aKmP21ToVWq5rdiFeDyfMps,2005
+safcom/cli.py,sha256=klbpjmJo25Y8KCZOCJt3f1x-xkVR6ay-G7wI1g5cpaU,3524
+safcom/exceptions.py,sha256=ZAX_E807F880f5cTcDrqp7h3QAbH6v90HuUaF4OcjTQ,566
+safcom/models.py,sha256=RrtKl0sXqz_tCpD1Wrdo5ybfE5HkYozpy1Wd-hcVmOM,1380
+safcom/mpesa.py,sha256=q8cFBms0DuSL2xcVHxFQZrOXOGsjU0bRUL33prECbR8,10821
+safcom-0.1.0.dist-info/METADATA,sha256=1lchWfZezsr9jWt_ZtBZRfnmexSxrQ63-7PLN-lZwGg,3764
+safcom-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+safcom-0.1.0.dist-info/entry_points.txt,sha256=yMODPL8ZiuzAAOvRfUshgiZsErb8Z2Pd2WfCAC6cZ6U,43
+safcom-0.1.0.dist-info/top_level.txt,sha256=_fG1svGN3DahdFMbP9w1HQyYVlCh8qaZrKwiuOcdhsc,7
+safcom-0.1.0.dist-info/RECORD,,

safcom-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

safcom-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+safcom = safcom.cli:main

safcom-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+safcom