pesapal-python 1.0.0__py3-none-any.whl

pesapal/__init__.py

@@ -0,0 +1,39 @@
+"""Python SDK for the Pesapal API v3.
+
+Public API::
+
+    from pesapal import PesapalClient, OrderRequest, BillingAddress
+"""
+
+from __future__ import annotations
+
+from .client import (
+    PRODUCTION_BASE_URL,
+    SANDBOX_BASE_URL,
+    PesapalClient,
+)
+from .exceptions import (
+    PesapalAPIError,
+    PesapalAuthError,
+    PesapalConfigError,
+    PesapalError,
+    PesapalMobileMoneyError,
+)
+from .models import BillingAddress, MobileMoneyResult, OrderRequest
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "PesapalClient",
+    "OrderRequest",
+    "BillingAddress",
+    "MobileMoneyResult",
+    "PesapalError",
+    "PesapalConfigError",
+    "PesapalAuthError",
+    "PesapalAPIError",
+    "PesapalMobileMoneyError",
+    "PRODUCTION_BASE_URL",
+    "SANDBOX_BASE_URL",
+    "__version__",
+]

pesapal/client.py

@@ -0,0 +1,367 @@
+"""Synchronous client for the Pesapal API v3."""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime, timedelta, timezone
+from typing import Any, Dict, Optional, Union
+
+import requests
+
+from .exceptions import (
+    PesapalAPIError,
+    PesapalAuthError,
+    PesapalConfigError,
+)
+from .models import MobileMoneyResult, OrderRequest
+
+#: Base URL for the Pesapal production environment.
+PRODUCTION_BASE_URL = "https://pay.pesapal.com/v3"
+#: Base URL for the Pesapal sandbox/demo environment.
+SANDBOX_BASE_URL = "https://cybqa.pesapal.com/pesapalv3"
+
+PayloadType = Union[Dict[str, Any], OrderRequest]
+
+
+class PesapalClient:
+    """A thin, typed wrapper around the Pesapal REST API.
+
+    Example::
+
+        from pesapal import PesapalClient, OrderRequest, BillingAddress
+
+        client = PesapalClient("consumer_key", "consumer_secret", sandbox=True)
+        ipn = client.register_ipn("https://example.com/ipn", "POST")
+        order = OrderRequest(
+            amount=1000,
+            currency="UGX",
+            description="Test payment",
+            callback_url="https://example.com/callback",
+            notification_id=ipn["ipn_id"],
+            billing_address=BillingAddress(
+                email_address="customer@example.com",
+                phone_number="0775000000",
+                country_code="UG",
+                first_name="Jane",
+                last_name="Doe",
+            ),
+        )
+        submitted = client.submit_order(order)
+        status = client.get_transaction_status(submitted["order_tracking_id"])
+    """
+
+    def __init__(
+        self,
+        consumer_key: str,
+        consumer_secret: str,
+        *,
+        sandbox: bool = False,
+        base_url: Optional[str] = None,
+        timeout: int = 30,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        if not consumer_key or not consumer_secret:
+            raise PesapalConfigError(
+                "consumer_key and consumer_secret are required."
+            )
+
+        self.consumer_key = consumer_key
+        self.consumer_secret = consumer_secret
+        self.base_url = (
+            base_url
+            or (SANDBOX_BASE_URL if sandbox else PRODUCTION_BASE_URL)
+        ).rstrip("/")
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+        self._token: Optional[str] = None
+        self._token_expiry: Optional[datetime] = None
+
+    # ------------------------------------------------------------------
+    # Construction from environment
+    # ------------------------------------------------------------------
+    @classmethod
+    def from_env(
+        cls,
+        *,
+        sandbox: bool = False,
+        dotenv_path: Optional[str] = None,
+        load_dotenv: bool = True,
+        **kwargs: Any,
+    ) -> "PesapalClient":
+        """Build a client from environment variables.
+
+        Reads the following variables (optionally loaded from a ``.env`` file)::
+
+            PESAPAL_CONSUMER_KEY
+            PESAPAL_CONSUMER_SECRET
+            PESAPAL_PRODUCTION_BASE_URL   (optional)
+            PESAPAL_SANDBOX_BASE_URL      (optional)
+
+        Args:
+            sandbox: Use the sandbox base URL when ``True``.
+            dotenv_path: Optional explicit path to a ``.env`` file.
+            load_dotenv: When ``True`` (default), attempt to load a ``.env``
+                file using ``python-dotenv`` if it is installed.
+            **kwargs: Forwarded to :class:`PesapalClient` (e.g. ``timeout``).
+        """
+        if load_dotenv:
+            try:
+                from dotenv import load_dotenv as _load_dotenv
+
+                _load_dotenv(dotenv_path)
+            except ImportError:
+                if dotenv_path:
+                    raise PesapalConfigError(
+                        "python-dotenv is required to load a .env file. "
+                        'Install it with: pip install python-dotenv'
+                    )
+
+        consumer_key = os.getenv("PESAPAL_CONSUMER_KEY")
+        consumer_secret = os.getenv("PESAPAL_CONSUMER_SECRET")
+        if not consumer_key or not consumer_secret:
+            raise PesapalConfigError(
+                "PESAPAL_CONSUMER_KEY and PESAPAL_CONSUMER_SECRET must be set "
+                "in the environment or a .env file."
+            )
+
+        base_url = kwargs.pop("base_url", None)
+        if base_url is None:
+            if sandbox:
+                base_url = os.getenv("PESAPAL_SANDBOX_BASE_URL") or SANDBOX_BASE_URL
+            else:
+                base_url = (
+                    os.getenv("PESAPAL_PRODUCTION_BASE_URL") or PRODUCTION_BASE_URL
+                )
+
+        return cls(
+            consumer_key,
+            consumer_secret,
+            sandbox=sandbox,
+            base_url=base_url,
+            **kwargs,
+        )
+
+    # ------------------------------------------------------------------
+    # Authentication
+    # ------------------------------------------------------------------
+    def authenticate(self) -> str:
+        """Request a fresh bearer token and cache it. Returns the token."""
+        url = f"{self.base_url}/api/Auth/RequestToken"
+        try:
+            resp = self.session.post(
+                url,
+                json={
+                    "consumer_key": self.consumer_key,
+                    "consumer_secret": self.consumer_secret,
+                },
+                headers={
+                    "Accept": "application/json",
+                    "Content-Type": "application/json",
+                },
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise PesapalAuthError(f"Authentication request failed: {exc}") from exc
+
+        data = self._safe_json(resp)
+        token = data.get("token")
+        if not token:
+            raise PesapalAuthError(
+                f"No token returned by Pesapal: {data.get('error') or data}"
+            )
+
+        self._token = token
+        self._token_expiry = self._parse_expiry(data.get("expiryDate"))
+        return token
+
+    @property
+    def token(self) -> Optional[str]:
+        """The currently cached token (may be ``None`` or expired)."""
+        return self._token
+
+    def _ensure_token(self) -> str:
+        """Return a valid token, authenticating/refreshing if necessary."""
+        if self._token is None:
+            return self.authenticate()
+        if self._token_expiry is not None:
+            now = datetime.now(timezone.utc)
+            if now >= self._token_expiry - timedelta(seconds=60):
+                return self.authenticate()
+        return self._token
+
+    # ------------------------------------------------------------------
+    # IPN registration (needed to obtain a notification_id for orders)
+    # ------------------------------------------------------------------
+    def register_ipn(
+        self, url: str, ipn_notification_type: str = "POST"
+    ) -> Dict[str, Any]:
+        """Register an Instant Payment Notification (IPN) URL.
+
+        Returns the decoded response containing the ``ipn_id``.
+        """
+        return self._request(
+            "POST",
+            "/api/URLSetup/RegisterIPN",
+            json={"url": url, "ipn_notification_type": ipn_notification_type},
+        )
+
+    def get_ipn_list(self) -> Any:
+        """Return the list of IPN URLs registered for this merchant."""
+        return self._request("GET", "/api/URLSetup/GetIpnList")
+
+    # ------------------------------------------------------------------
+    # Orders
+    # ------------------------------------------------------------------
+    def submit_order(self, order: PayloadType) -> Dict[str, Any]:
+        """Submit an order request.
+
+        Accepts an :class:`OrderRequest` or a raw ``dict``. Returns the decoded
+        response which includes ``order_tracking_id``, ``merchant_reference``
+        and ``redirect_url``.
+        """
+        payload = order.to_dict() if isinstance(order, OrderRequest) else order
+        return self._request(
+            "POST", "/api/Transactions/SubmitOrderRequest", json=payload
+        )
+
+    def get_transaction_status(self, order_tracking_id: str) -> Dict[str, Any]:
+        """Fetch the status of a transaction by its order tracking id."""
+        return self._request(
+            "GET",
+            "/api/Transactions/GetTransactionStatus",
+            params={"orderTrackingId": order_tracking_id},
+        )
+
+    def refund(
+        self,
+        confirmation_code: str,
+        amount: Union[str, float],
+        username: str,
+        remarks: str,
+    ) -> Dict[str, Any]:
+        """Request a refund for a completed transaction."""
+        return self._request(
+            "POST",
+            "/api/Transactions/RefundRequest",
+            json={
+                "confirmation_code": confirmation_code,
+                "amount": str(amount),
+                "username": username,
+                "remarks": remarks,
+            },
+        )
+
+    def cancel_order(self, order_tracking_id: str) -> Dict[str, Any]:
+        """Cancel a pending order by its order tracking id."""
+        return self._request(
+            "POST",
+            "/api/Transactions/CancelOrder",
+            json={"order_tracking_id": order_tracking_id},
+        )
+
+    # ------------------------------------------------------------------
+    # Mobile money (Selenium helper, optional dependency)
+    # ------------------------------------------------------------------
+    def initiate_mobile_money_payment(
+        self, redirect_url: str, **kwargs: Any
+    ) -> MobileMoneyResult:
+        """Drive the hosted Pesapal iframe to trigger a mobile-money STK push.
+
+        Uses the ``redirect_url`` returned by :meth:`submit_order`. The phone
+        number is already prepopulated on the hosted form, so it is not filled
+        here. Requires the optional ``mobilemoney`` extra (Selenium + Chrome).
+
+        Additional keyword arguments are forwarded to
+        :func:`pesapal.mobile_money.initiate_mobile_money_payment`.
+        """
+        from .mobile_money import initiate_mobile_money_payment
+
+        return initiate_mobile_money_payment(redirect_url, **kwargs)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Optional[Dict[str, Any]] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        token = self._ensure_token()
+        url = f"{self.base_url}{path}"
+        headers = {
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {token}",
+        }
+        try:
+            resp = self.session.request(
+                method,
+                url,
+                json=json,
+                params=params,
+                headers=headers,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as exc:
+            raise PesapalAPIError(f"Request to {path} failed: {exc}") from exc
+
+        data = self._safe_json(resp)
+        self._raise_for_pesapal_error(resp, data)
+        return data
+
+    def _safe_json(self, resp: requests.Response) -> Any:
+        try:
+            return resp.json()
+        except ValueError:
+            raise PesapalAPIError(
+                "Pesapal returned a non-JSON response.",
+                status_code=resp.status_code,
+                response=resp.text,
+            )
+
+    def _raise_for_pesapal_error(
+        self, resp: requests.Response, data: Any
+    ) -> None:
+        # Pesapal returns HTTP 200 even for logical errors, signalling them via
+        # a non-null ``error`` object, so we inspect both.
+        error = data.get("error") if isinstance(data, dict) else None
+        has_error = bool(error) and any(
+            error.get(k) for k in ("error_type", "code", "message")
+        ) if isinstance(error, dict) else bool(error)
+
+        if resp.status_code >= 400 or has_error:
+            message = "Pesapal API error"
+            if isinstance(error, dict) and error.get("message"):
+                message = str(error["message"])
+            elif isinstance(data, dict) and data.get("message"):
+                message = str(data["message"])
+            raise PesapalAPIError(
+                message,
+                status_code=resp.status_code,
+                error=error,
+                response=data,
+            )
+
+    @staticmethod
+    def _parse_expiry(value: Optional[str]) -> Optional[datetime]:
+        if not value:
+            return None
+        text = value.strip()
+        if text.endswith("Z"):
+            text = text[:-1] + "+00:00"
+        try:
+            dt = datetime.fromisoformat(text)
+        except ValueError:
+            # Trim fractional seconds beyond microsecond precision if present.
+            try:
+                head, _, tail = text.partition(".")
+                dt = datetime.fromisoformat(head)
+            except ValueError:
+                return None
+        if dt.tzinfo is None:
+            dt = dt.replace(tzinfo=timezone.utc)
+        return dt

pesapal/exceptions.py

@@ -0,0 +1,53 @@
+"""Exceptions raised by the Pesapal SDK."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class PesapalError(Exception):
+    """Base class for all Pesapal SDK errors."""
+
+
+class PesapalConfigError(PesapalError):
+    """Raised when the client is misconfigured (e.g. missing credentials)."""
+
+
+class PesapalAuthError(PesapalError):
+    """Raised when authentication with the Pesapal API fails."""
+
+
+class PesapalAPIError(PesapalError):
+    """Raised when the Pesapal API returns an error response.
+
+    Attributes:
+        message: Human readable error message.
+        status_code: HTTP status code of the response, if available.
+        error: The parsed ``error`` object returned by Pesapal, if any.
+        response: The raw decoded JSON body of the response, if any.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        error: Optional[Any] = None,
+        response: Optional[Any] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.error = error
+        self.response = response
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        parts = [self.message]
+        if self.status_code is not None:
+            parts.append(f"(HTTP {self.status_code})")
+        if self.error:
+            parts.append(f"error={self.error!r}")
+        return " ".join(parts)
+
+
+class PesapalMobileMoneyError(PesapalError):
+    """Raised when the Selenium mobile-money flow fails."""

pesapal/mobile_money.py

@@ -0,0 +1,116 @@
+"""Selenium-based mobile money helper.
+
+The Pesapal mobile-money flow happens on a hosted iframe page (the
+``redirect_url`` returned by ``SubmitOrderRequest``). There is no public JSON
+endpoint to trigger the STK push directly, so this module drives a headless
+browser to submit the prepopulated form and waits for Pesapal to redirect back
+with a ``ResponseId``.
+
+This module requires the optional ``mobilemoney`` extra::
+
+    pip install "pesapal-python[mobilemoney]"
+"""
+
+from __future__ import annotations
+
+from urllib.parse import parse_qs, urlparse
+
+from .exceptions import PesapalMobileMoneyError
+from .models import MobileMoneyResult
+
+try:
+    from selenium import webdriver
+    from selenium.webdriver.common.by import By
+    from selenium.webdriver.support import expected_conditions as EC
+    from selenium.webdriver.support.ui import WebDriverWait
+
+    _SELENIUM_AVAILABLE = True
+except ImportError:  # pragma: no cover - optional dependency
+    _SELENIUM_AVAILABLE = False
+
+
+def _build_driver(headless: bool):
+    options = webdriver.ChromeOptions()
+    if headless:
+        options.add_argument("--headless=new")
+    options.add_argument("--window-size=1280,800")
+    return webdriver.Chrome(options=options)
+
+
+def initiate_mobile_money_payment(
+    redirect_url: str,
+    *,
+    headless: bool = True,
+    timeout: int = 60,
+    click_timeout: int = 5,
+    driver=None,
+) -> MobileMoneyResult:
+    """Submit the hosted Pesapal payment form and wait for the redirect.
+
+    Args:
+        redirect_url: The ``redirect_url`` from ``submit_order``.
+        headless: Run Chrome without a visible window (default ``True``).
+        timeout: Seconds to wait for the post-submit redirect.
+        click_timeout: Seconds to wait for clickable elements (radios/button).
+        driver: Optional pre-built Selenium WebDriver to use instead of
+            creating one. When supplied, the caller is responsible for quitting.
+
+    Returns:
+        A :class:`~pesapal.models.MobileMoneyResult`.
+    """
+    if not _SELENIUM_AVAILABLE:
+        raise PesapalMobileMoneyError(
+            "Selenium is not installed. Install the optional extra: "
+            'pip install "pesapal-python[mobilemoney]"'
+        )
+
+    owns_driver = driver is None
+    if owns_driver:
+        driver = _build_driver(headless)
+
+    try:
+        driver.get(redirect_url)
+
+        wait = WebDriverWait(driver, timeout)
+        click_wait = WebDriverWait(driver, click_timeout)
+
+        # The phone number is prepopulated on the hosted form; just locate the
+        # submit button and click it once it is interactable.
+        proceed_button = click_wait.until(
+            EC.element_to_be_clickable((By.ID, "submitFormBtn"))
+        )
+        driver.execute_script(
+            "arguments[0].scrollIntoView({block:'center'});", proceed_button
+        )
+        proceed_button.click()
+
+        # Pesapal processes the request and redirects back with a ResponseId.
+        wait.until(lambda drv: "ResponseId=" in drv.current_url)
+
+        final_url = driver.current_url
+        query = parse_qs(urlparse(final_url).query)
+        tracking_id = query.get("OrderTrackingId", [None])[0]
+        response_id = query.get("ResponseId", [None])[0]
+
+        return MobileMoneyResult(
+            success=True,
+            tracking_id=tracking_id,
+            response_id=response_id,
+            final_url=final_url,
+        )
+
+    except Exception as exc:  # noqa: BLE001 - surface as a typed result
+        current_url = None
+        try:
+            current_url = driver.current_url
+        except Exception:  # pragma: no cover - driver may be dead
+            pass
+        return MobileMoneyResult(
+            success=False,
+            final_url=current_url,
+            error=f"{type(exc).__name__}: {exc}",
+        )
+
+    finally:
+        if owns_driver:
+            driver.quit()

pesapal/models.py

@@ -0,0 +1,86 @@
+"""Typed request/response models for the Pesapal SDK.
+
+These :mod:`dataclasses` are convenience helpers. Every client method also
+accepts a plain ``dict`` if you prefer to build payloads yourself.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any, Dict, Optional
+
+
+def _new_uuid() -> str:
+    return str(uuid.uuid4())
+
+
+@dataclass
+class BillingAddress:
+    """Customer billing information attached to an order."""
+
+    email_address: Optional[str] = None
+    phone_number: Optional[str] = None
+    country_code: Optional[str] = None
+    first_name: Optional[str] = None
+    middle_name: Optional[str] = None
+    last_name: Optional[str] = None
+    line_1: Optional[str] = None
+    line_2: Optional[str] = None
+    city: Optional[str] = None
+    state: Optional[str] = None
+    postal_code: Optional[str] = None
+    zip_code: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {k: ("" if v is None else v) for k, v in asdict(self).items()}
+
+
+@dataclass
+class OrderRequest:
+    """Payload for ``SubmitOrderRequest``.
+
+    ``notification_id`` is the IPN id returned by :meth:`PesapalClient.register_ipn`.
+    """
+
+    amount: float
+    currency: str
+    description: str
+    callback_url: str
+    notification_id: str
+    billing_address: BillingAddress
+    id: str = field(default_factory=_new_uuid)
+    redirect_mode: str = ""
+    branch: Optional[str] = None
+    cancellation_url: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        payload: Dict[str, Any] = {
+            "id": self.id,
+            "currency": self.currency,
+            "amount": self.amount,
+            "description": self.description,
+            "callback_url": self.callback_url,
+            "redirect_mode": self.redirect_mode,
+            "notification_id": self.notification_id,
+            "billing_address": self.billing_address.to_dict(),
+        }
+        if self.branch is not None:
+            payload["branch"] = self.branch
+        if self.cancellation_url is not None:
+            payload["cancellation_url"] = self.cancellation_url
+        return payload
+
+
+@dataclass
+class MobileMoneyResult:
+    """Result of the Selenium-driven mobile money flow."""
+
+    success: bool
+    tracking_id: Optional[str] = None
+    response_id: Optional[str] = None
+    final_url: Optional[str] = None
+    error: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        return asdict(self)

pesapal_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: pesapal-python
+Version: 1.0.0
+Summary: Python SDK for the Pesapal API v3 (authentication, orders, transaction status, refunds, cancellations) with an optional Selenium mobile-money helper.
+Author: Pesapal SDK Contributors
+License: MIT
+Project-URL: Homepage, https://github.com/robin-001/pesapal-py
+Project-URL: Documentation, https://github.com/robin-001/pesapal-py#readme
+Project-URL: Source, https://github.com/robin-001/pesapal-py
+Project-URL: Bug Tracker, https://github.com/robin-001/pesapal-py/issues
+Keywords: pesapal,payments,mobile money,uganda,kenya,api
+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.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: mobilemoney
+Requires-Dist: selenium>=4.10; extra == "mobilemoney"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: responses>=0.23; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# pesapal-python
+
+A lightweight Python SDK for the [Pesapal API v3](https://developer.pesapal.com/),
+covering authentication, order submission, transaction status, refunds and
+cancellations, plus an optional Selenium helper to trigger the mobile-money
+STK push from the hosted payment page.
+
+## Features
+
+- **Authenticate** and transparently cache/refresh the bearer token.
+- **Register IPN** URLs and list them (needed to obtain a `notification_id`).
+- **Submit orders** and get back the `redirect_url` / `order_tracking_id`.
+- **Initiate mobile money** payment by driving the hosted iframe (optional).
+- **Get transaction status** for an order.
+- **Refund** completed transactions.
+- **Cancel** pending orders.
+
+## Installation
+
+```bash
+pip install pesapal-python
+```
+
+To use the Selenium mobile-money helper (requires Google Chrome + chromedriver):
+
+```bash
+pip install "pesapal-python[mobilemoney]"
+```
+
+## Configuration via `.env`
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```dotenv
+PESAPAL_CONSUMER_KEY=xxx
+PESAPAL_CONSUMER_SECRET=xxx=
+PESAPAL_PRODUCTION_BASE_URL=https://pay.pesapal.com/v3
+PESAPAL_SANDBOX_BASE_URL=https://cybqa.pesapal.com/pesapalv3
+```
+
+Then build the client straight from the environment:
+
+```python
+from pesapal import PesapalClient
+
+client = PesapalClient.from_env(sandbox=True)  # loads .env automatically
+```
+
+`from_env` reads `PESAPAL_CONSUMER_KEY` / `PESAPAL_CONSUMER_SECRET` and picks the
+base URL from `PESAPAL_SANDBOX_BASE_URL` or `PESAPAL_PRODUCTION_BASE_URL`
+depending on `sandbox`, falling back to the built-in defaults.
+
+## Quick start
+
+```python
+from pesapal import PesapalClient, OrderRequest, BillingAddress
+
+client = PesapalClient(
+    consumer_key="YOUR_CONSUMER_KEY",
+    consumer_secret="YOUR_CONSUMER_SECRET",
+    sandbox=True,  # omit or set False for production
+)
+
+# 1. Authenticate (optional — called automatically on first request)
+client.authenticate()
+
+# 2. Register an IPN URL (once) to obtain a notification_id
+ipn = client.register_ipn("https://your-app.com/ipn", "POST")
+notification_id = ipn["ipn_id"]
+
+# 3. Submit an order
+order = OrderRequest(
+    amount=1000,
+    currency="UGX",
+    description="Order #1234",
+    callback_url="https://your-app.com/callback",
+    notification_id=notification_id,
+    branch="HQ",
+    billing_address=BillingAddress(
+        email_address="customer@example.com",
+        phone_number="0775000000",
+        country_code="UG",
+        first_name="Jane",
+        last_name="Doe",
+    ),
+)
+submitted = client.submit_order(order)
+order_tracking_id = submitted["order_tracking_id"]
+redirect_url = submitted["redirect_url"]
+
+# 4. Initiate mobile money (drives the hosted form; phone is prepopulated)
+result = client.initiate_mobile_money_payment(redirect_url, headless=True)
+print(result.success, result.tracking_id, result.response_id)
+
+# 5. Check transaction status
+status = client.get_transaction_status(order_tracking_id)
+print(status["payment_status_description"])
+
+# 6. Refund a completed transaction
+client.refund(
+    confirmation_code=status["confirmation_code"],
+    amount=1000,
+    username="Operator Name",
+    remarks="Service not offered",
+)
+
+# 7. Cancel a pending order
+client.cancel_order(order_tracking_id)
+```
+
+## Environments
+
+| Environment | Base URL                                   |
+| ----------- | ------------------------------------------ |
+| Production  | `https://pay.pesapal.com/v3`               |
+| Sandbox     | `https://cybqa.pesapal.com/pesapalv3`      |
+
+Select with `PesapalClient(..., sandbox=True)` or pass a custom `base_url`.
+
+## Error handling
+
+All API failures raise a subclass of `PesapalError`:
+
+```python
+from pesapal import PesapalAPIError, PesapalAuthError
+
+try:
+    client.submit_order(order)
+except PesapalAuthError as exc:
+    ...  # bad credentials / token problem
+except PesapalAPIError as exc:
+    print(exc.status_code, exc.error, exc.response)
+```
+
+The mobile-money helper does **not** raise on failure; it returns a
+`MobileMoneyResult` with `success=False` and an `error` message.
+
+## License
+
+MIT

pesapal_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+pesapal/__init__.py,sha256=LguQyBanzYFgFWxY8ceg3I-1jJB8-t4HDc_vSD3Am6A,782
+pesapal/client.py,sha256=y56liFM0pFuJiEvmDKEzbO8dOgXb_i0uo_y76QgLc9A,13170
+pesapal/exceptions.py,sha256=P-SO8CcqT3Gha4NAkfLudPyjmrq1LI38t5dACQ-SZZM,1557
+pesapal/mobile_money.py,sha256=aWs8JlC-gs6R_-polhxfKaBvSzvUsndkTH2-eMfFY6A,3858
+pesapal/models.py,sha256=IjkoInd_Tz1KcgM20QGymWKcdBq7m2PlG7yi4lLQKIw,2493
+pesapal/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pesapal_python-1.0.0.dist-info/licenses/LICENSE,sha256=uZg89QLWGUDSijT7JTXecrHJjiglUPBHXcWay4Q1ap0,1081
+pesapal_python-1.0.0.dist-info/METADATA,sha256=ZXbnMoLMpMqXttfpTuBL4ySuo5WzW5ULOOoKQbPtVZM,5657
+pesapal_python-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pesapal_python-1.0.0.dist-info/top_level.txt,sha256=80JDSH0Hu8HEr0jPh_9LNGythBU1UNFZQRFa9DtaGUc,8
+pesapal_python-1.0.0.dist-info/RECORD,,

pesapal_python-1.0.0.dist-info/WHEEL

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

pesapal_python-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pesapal SDK Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pesapal_python-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pesapal