paysawa 0.1.0__tar.gz

paysawa-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paysawa
+
+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.

paysawa-0.1.0/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: paysawa
+Version: 0.1.0
+Summary: Python SDK for the Paysawa mobile money gateway (MTN / Orange): collect, withdraw, payment links and signed webhooks.
+Author: Paysawa
+License: MIT
+Project-URL: Homepage, https://github.com/ChrinaerDev/paysawa-python
+Project-URL: Issues, https://github.com/ChrinaerDev/paysawa-python/issues
+Project-URL: Changelog, https://github.com/ChrinaerDev/paysawa-python/blob/main/CHANGELOG.md
+Keywords: paysawa,mobile money,payments,cameroon,mtn,orange money,campay,xaf
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Requires-Dist: PyJWT>=2.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# paysawa
+
+Python SDK for the **Paysawa** mobile money gateway (MTN Mobile Money and Orange Money, XAF).
+Collect payments, send money, create payment links and verify signed webhooks with a few lines of code.
+It speaks Paysawa's Campay-style API, so the concepts are the same as Campay's.
+
+```bash
+pip install paysawa
+```
+
+## 1. Get your credentials
+
+In your Paysawa dashboard create an **app**. It gives you three values (you can show them again any time):
+
+| Value | What it is |
+|---|---|
+| App username | like `pa_1a2b3c4d5e6f7a8b` |
+| App password | secret, never put it in front-end code or in git |
+| Webhook key | verifies that webhooks really come from Paysawa |
+
+A **test** app uses the sandbox (no real money). A **live** app moves real money.
+
+## 2. Quick start
+
+```python
+from paysawa import Client
+
+client = Client(
+    app_username="pa_xxxxxxxxxxxxxxxx",
+    app_password="your-app-password",
+    webhook_key="whk_xxxxxxxx",
+    base_url="https://YOUR-PAYSAWA-URL/api/",   # or set PAYSAWA_BASE_URL
+)
+
+# Ask a customer to pay: they get a prompt on their phone and approve with their PIN.
+tx = client.collect(amount=5000, phone="670000001", description="Order 1001",
+                    external_reference="order-1001", wait=True)   # wait=True blocks until final
+if tx.is_successful:
+    print("Paid!", tx.reference)
+else:
+    print("Not paid:", tx.status)
+
+print(client.get_balance().total_balance)                          # your Paysawa balance
+client.withdraw(amount=1000, phone="690000001", description="Refund")   # pay money out
+link = client.get_payment_link(amount=2000, description="Order 1002", redirect_url="https://shop.example.com/thanks")
+print(link.link)                                                    # send this to your customer
+```
+
+Put the credentials in environment variables instead of code and use `Client.from_env()`:
+`PAYSAWA_APP_USERNAME`, `PAYSAWA_APP_PASSWORD`, `PAYSAWA_WEBHOOK_KEY`, `PAYSAWA_BASE_URL`.
+
+## 3. Statuses
+
+Every transaction is `PENDING`, `SUCCESSFUL` or `FAILED` (`tx.is_pending`, `tx.is_successful`, `tx.is_failed`, `tx.is_final`).
+A collection stays `PENDING` until the customer approves. Without `wait=True`, check it later with
+`client.get_transaction(reference)` or use `client.wait_for_transaction(reference, timeout=120)`, or rely on webhooks.
+
+## 4. Webhooks
+
+Set your app's webhook URL in the dashboard. Paysawa calls it with a `GET` and query parameters plus a signed `signature`.
+**Always verify it**:
+
+```python
+# Flask
+@app.get("/webhooks/paysawa")
+def paysawa_webhook():
+    try:
+        event = client.verify_webhook(request.args.to_dict())
+    except WebhookVerificationError:
+        return "invalid", 401
+    if event.is_successful:
+        mark_order_paid(event.external_reference, event.amount)
+    return "ok"
+```
+
+```python
+# FastAPI
+@app.get("/webhooks/paysawa")
+async def paysawa_webhook(request: Request):
+    event = client.verify_webhook(dict(request.query_params))   # raises WebhookVerificationError if not authentic
+    ...
+```
+
+Django: `client.verify_webhook(request.GET.dict())`. Reply with any 2xx status; otherwise Paysawa retries.
+Check `event.amount` against the order before you ship anything.
+
+## 5. Async
+
+```python
+from paysawa import AsyncClient
+
+async with AsyncClient.from_env() as client:
+    tx = await client.collect(5000, "670000001", "Order 1001", "order-1001", wait=True)
+```
+
+## 6. Errors
+
+All errors inherit from `PaysawaError` (`.message`, `.status`, `.code`):
+
+| Exception | When |
+|---|---|
+| `AuthenticationError` | wrong app username/password |
+| `PermissionDeniedError` | live mode not enabled, account suspended |
+| `InvalidRequestError` | bad amount or phone number, unknown reference, limits |
+| `InsufficientFundsError` | withdrawal larger than your balance (amount + fee) |
+| `RateLimitError` | too many requests |
+| `ServerError` / `NetworkError` | Paysawa busy or unreachable |
+| `WaitTimeoutError` | `wait_for_transaction` gave up (`.transaction` has the latest state) |
+| `WebhookVerificationError` | the webhook is not authentic: ignore it |
+
+Payments (collect, withdraw) are **never retried automatically**, so a retry can never charge twice.
+Reads are retried twice. If a payment call fails with a network error, look the payment up by your
+`external_reference` before trying again.
+
+## 7. Sandbox numbers (test apps)
+
+`670000001` succeeds, a number ending in `0000` fails, a number ending in `9999` stays pending.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

paysawa-0.1.0/README.md

@@ -0,0 +1,124 @@
+# paysawa
+
+Python SDK for the **Paysawa** mobile money gateway (MTN Mobile Money and Orange Money, XAF).
+Collect payments, send money, create payment links and verify signed webhooks with a few lines of code.
+It speaks Paysawa's Campay-style API, so the concepts are the same as Campay's.
+
+```bash
+pip install paysawa
+```
+
+## 1. Get your credentials
+
+In your Paysawa dashboard create an **app**. It gives you three values (you can show them again any time):
+
+| Value | What it is |
+|---|---|
+| App username | like `pa_1a2b3c4d5e6f7a8b` |
+| App password | secret, never put it in front-end code or in git |
+| Webhook key | verifies that webhooks really come from Paysawa |
+
+A **test** app uses the sandbox (no real money). A **live** app moves real money.
+
+## 2. Quick start
+
+```python
+from paysawa import Client
+
+client = Client(
+    app_username="pa_xxxxxxxxxxxxxxxx",
+    app_password="your-app-password",
+    webhook_key="whk_xxxxxxxx",
+    base_url="https://YOUR-PAYSAWA-URL/api/",   # or set PAYSAWA_BASE_URL
+)
+
+# Ask a customer to pay: they get a prompt on their phone and approve with their PIN.
+tx = client.collect(amount=5000, phone="670000001", description="Order 1001",
+                    external_reference="order-1001", wait=True)   # wait=True blocks until final
+if tx.is_successful:
+    print("Paid!", tx.reference)
+else:
+    print("Not paid:", tx.status)
+
+print(client.get_balance().total_balance)                          # your Paysawa balance
+client.withdraw(amount=1000, phone="690000001", description="Refund")   # pay money out
+link = client.get_payment_link(amount=2000, description="Order 1002", redirect_url="https://shop.example.com/thanks")
+print(link.link)                                                    # send this to your customer
+```
+
+Put the credentials in environment variables instead of code and use `Client.from_env()`:
+`PAYSAWA_APP_USERNAME`, `PAYSAWA_APP_PASSWORD`, `PAYSAWA_WEBHOOK_KEY`, `PAYSAWA_BASE_URL`.
+
+## 3. Statuses
+
+Every transaction is `PENDING`, `SUCCESSFUL` or `FAILED` (`tx.is_pending`, `tx.is_successful`, `tx.is_failed`, `tx.is_final`).
+A collection stays `PENDING` until the customer approves. Without `wait=True`, check it later with
+`client.get_transaction(reference)` or use `client.wait_for_transaction(reference, timeout=120)`, or rely on webhooks.
+
+## 4. Webhooks
+
+Set your app's webhook URL in the dashboard. Paysawa calls it with a `GET` and query parameters plus a signed `signature`.
+**Always verify it**:
+
+```python
+# Flask
+@app.get("/webhooks/paysawa")
+def paysawa_webhook():
+    try:
+        event = client.verify_webhook(request.args.to_dict())
+    except WebhookVerificationError:
+        return "invalid", 401
+    if event.is_successful:
+        mark_order_paid(event.external_reference, event.amount)
+    return "ok"
+```
+
+```python
+# FastAPI
+@app.get("/webhooks/paysawa")
+async def paysawa_webhook(request: Request):
+    event = client.verify_webhook(dict(request.query_params))   # raises WebhookVerificationError if not authentic
+    ...
+```
+
+Django: `client.verify_webhook(request.GET.dict())`. Reply with any 2xx status; otherwise Paysawa retries.
+Check `event.amount` against the order before you ship anything.
+
+## 5. Async
+
+```python
+from paysawa import AsyncClient
+
+async with AsyncClient.from_env() as client:
+    tx = await client.collect(5000, "670000001", "Order 1001", "order-1001", wait=True)
+```
+
+## 6. Errors
+
+All errors inherit from `PaysawaError` (`.message`, `.status`, `.code`):
+
+| Exception | When |
+|---|---|
+| `AuthenticationError` | wrong app username/password |
+| `PermissionDeniedError` | live mode not enabled, account suspended |
+| `InvalidRequestError` | bad amount or phone number, unknown reference, limits |
+| `InsufficientFundsError` | withdrawal larger than your balance (amount + fee) |
+| `RateLimitError` | too many requests |
+| `ServerError` / `NetworkError` | Paysawa busy or unreachable |
+| `WaitTimeoutError` | `wait_for_transaction` gave up (`.transaction` has the latest state) |
+| `WebhookVerificationError` | the webhook is not authentic: ignore it |
+
+Payments (collect, withdraw) are **never retried automatically**, so a retry can never charge twice.
+Reads are retried twice. If a payment call fails with a network error, look the payment up by your
+`external_reference` before trying again.
+
+## 7. Sandbox numbers (test apps)
+
+`670000001` succeeds, a number ending in `0000` fails, a number ending in `9999` stays pending.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

paysawa-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "paysawa"
+dynamic = ["version"]
+description = "Python SDK for the Paysawa mobile money gateway (MTN / Orange): collect, withdraw, payment links and signed webhooks."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [{name = "Paysawa"}]
+keywords = ["paysawa", "mobile money", "payments", "cameroon", "mtn", "orange money", "campay", "xaf"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Office/Business :: Financial :: Point-Of-Sale",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.25", "PyJWT>=2.4"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.23", "build>=1.0", "twine>=5.0"]
+
+[project.urls]
+Homepage = "https://github.com/ChrinaerDev/paysawa-python"
+Issues = "https://github.com/ChrinaerDev/paysawa-python/issues"
+Changelog = "https://github.com/ChrinaerDev/paysawa-python/blob/main/CHANGELOG.md"
+
+[tool.setuptools.dynamic]
+version = {attr = "paysawa._version.__version__"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+paysawa = ["py.typed"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

paysawa-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

paysawa-0.1.0/src/paysawa/__init__.py

@@ -0,0 +1,24 @@
+"""Paysawa Python SDK: collect and withdraw mobile money (MTN / Orange), payment links and webhooks."""
+from ._version import __version__
+from .client import DEFAULT_BASE_URL, AsyncClient, Client
+from .errors import (
+    AuthenticationError,
+    InsufficientFundsError,
+    InvalidRequestError,
+    NetworkError,
+    PaysawaError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    WaitTimeoutError,
+    WebhookVerificationError,
+)
+from .models import FAILED, PENDING, SUCCESSFUL, Result, Transaction, WebhookEvent
+from .webhooks import verify_webhook
+
+__all__ = [
+    "__version__", "Client", "AsyncClient", "DEFAULT_BASE_URL", "verify_webhook",
+    "PENDING", "SUCCESSFUL", "FAILED", "Result", "Transaction", "WebhookEvent",
+    "PaysawaError", "AuthenticationError", "PermissionDeniedError", "InvalidRequestError", "InsufficientFundsError",
+    "RateLimitError", "ServerError", "NetworkError", "WebhookVerificationError", "WaitTimeoutError",
+]

paysawa-0.1.0/src/paysawa/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

paysawa-0.1.0/src/paysawa/client.py

@@ -0,0 +1,322 @@
+"""Paysawa clients (synchronous `Client` and asynchronous `AsyncClient`).
+
+    from paysawa import Client
+
+    client = Client(app_username="pa_...", app_password="...", webhook_key="whk_...", base_url="https://your-paysawa/api/")
+    tx = client.collect(amount=5000, phone="670000001", description="Order 1001", external_reference="order-1001", wait=True)
+    if tx.is_successful: ...
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import threading
+import time
+from typing import Any, Callable, Mapping, Optional, Union
+
+import httpx
+
+from .errors import AuthenticationError, NetworkError, PaysawaError, WaitTimeoutError, error_from_response
+from .models import Result, Transaction, WebhookEvent
+from .webhooks import verify_webhook
+
+# Change this one line once Paysawa is hosted, or set PAYSAWA_BASE_URL, or pass base_url= to the client.
+DEFAULT_BASE_URL = "http://localhost:8000/api/"
+
+_sleep = time.sleep           # indirections so tests can run instantly
+_monotonic = time.monotonic
+_asleep = asyncio.sleep
+
+Amount = Union[int, str]
+
+
+def _base_url(value: Optional[str]) -> str:
+    return (value or os.environ.get("PAYSAWA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/") + "/"
+
+
+def _amount(value: Any) -> str:
+    """Amounts are whole XAF. Accepts 5000, "5000", 5000.0; rejects 0, negatives and fractions."""
+    try:
+        number = float(str(value).strip())
+    except ValueError:
+        raise ValueError(f"amount must be a number, got {value!r}") from None
+    if number <= 0 or number != int(number):
+        raise ValueError(f"amount must be a whole positive number of XAF, got {value!r}")
+    return str(int(number))
+
+
+def _raise(response: Any) -> None:
+    try:
+        data = response.json()
+    except ValueError:
+        data = {}
+    raise error_from_response(response.status_code, data)
+
+
+def _collect_body(amount: Amount, phone: str, description: str, external_reference: Optional[str], currency: str) -> dict:
+    return {"amount": _amount(amount), "currency": currency, "from": phone, "description": description, "external_reference": external_reference}
+
+
+def _withdraw_body(amount: Amount, phone: str, description: str, external_reference: Optional[str], currency: str) -> dict:
+    return {"amount": _amount(amount), "currency": currency, "to": phone, "description": description, "external_reference": external_reference}
+
+
+def _link_body(amount: Amount, description: str, external_reference: Optional[str], redirect_url: Optional[str], currency: str) -> dict:
+    body = {"amount": _amount(amount), "currency": currency, "description": description, "external_reference": external_reference}
+    if redirect_url:
+        body["redirect_url"] = redirect_url
+    return body
+
+
+def _env(name: str, required: bool = True) -> str:
+    value = os.environ.get(name, "")
+    if required and not value:
+        raise ValueError(f"Environment variable {name} is not set.")
+    return value
+
+
+class Client:
+    """Synchronous client. Use as a context manager (`with Client(...) as client:`) or call close() when done."""
+
+    def __init__(self, app_username: str, app_password: str, webhook_key: str = "", *, base_url: Optional[str] = None,
+                 timeout: float = 30.0, max_retries: int = 2, http_client: Optional[httpx.Client] = None):
+        if not app_username or not app_password:
+            raise ValueError("app_username and app_password are required (create an app in your Paysawa dashboard).")
+        self.base_url = _base_url(base_url)
+        self.app_username = app_username
+        self._password = app_password
+        self.webhook_key = webhook_key
+        self.max_retries = max(0, int(max_retries))
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.Client(timeout=timeout)
+        self._token: Optional[str] = None
+        self._expires_at = 0.0
+        self._lock = threading.Lock()
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> "Client":
+        """Reads PAYSAWA_APP_USERNAME, PAYSAWA_APP_PASSWORD, PAYSAWA_WEBHOOK_KEY (optional) and PAYSAWA_BASE_URL."""
+        return cls(_env("PAYSAWA_APP_USERNAME"), _env("PAYSAWA_APP_PASSWORD"), _env("PAYSAWA_WEBHOOK_KEY", required=False), **kwargs)
+
+    def __enter__(self) -> "Client":
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        if self._owns_http:
+            self._http.close()
+
+    # ------------------------------------------------------------------ transport
+    def _send(self, method: str, url: str, json: Any = None, headers: Optional[dict] = None) -> Any:
+        try:
+            return self._http.request(method, url, json=json, headers=headers or {})
+        except httpx.TimeoutException:
+            raise NetworkError("Paysawa did not answer in time.", code="timeout") from None
+        except httpx.HTTPError:
+            raise NetworkError(f"Cannot reach Paysawa at {self.base_url}.", code="unreachable") from None
+
+    def _get_token(self, force: bool = False) -> str:
+        with self._lock:
+            if not force and self._token and _monotonic() < self._expires_at:
+                return self._token
+            response = self._send("POST", self.base_url + "token/", {"username": self.app_username, "password": self._password})
+            if response.status_code >= 400:
+                _raise(response)
+            data = response.json()
+            self._token = data["token"]
+            self._expires_at = _monotonic() + max(int(data.get("expires_in") or 300) - 30, 10)
+            return self._token
+
+    def _request(self, method: str, path: str, json: Any = None) -> dict:
+        """Payments (POST) are never retried automatically, so a retry cannot create a second payment. Reads are."""
+        retries_left = self.max_retries if method == "GET" else 0
+        force_token = False
+        while True:
+            token = self._get_token(force=force_token)
+            try:
+                response = self._send(method, self.base_url + path, json, {"Authorization": f"Token {token}"})
+            except NetworkError:
+                if retries_left <= 0:
+                    raise
+                retries_left -= 1
+                _sleep(0.5 * (self.max_retries - retries_left))
+                continue
+            if response.status_code == 401 and not force_token:
+                force_token = True
+                continue
+            if response.status_code >= 500 and retries_left > 0:
+                retries_left -= 1
+                _sleep(0.5 * (self.max_retries - retries_left))
+                continue
+            if response.status_code >= 400:
+                _raise(response)
+            return response.json()
+
+    # ------------------------------------------------------------------ API
+    def collect(self, amount: Amount, phone: str, description: str = "", external_reference: Optional[str] = None, *,
+                currency: str = "XAF", wait: bool = False, timeout: float = 120.0, interval: float = 3.0) -> Transaction:
+        """Ask `phone` to pay `amount`. The customer approves on their phone. With wait=True this blocks until the payment
+        is SUCCESSFUL or FAILED (or raises WaitTimeoutError). Returns a Transaction (reference, status, operator, ussd_code)."""
+        tx = Transaction(self._request("POST", "collect/", _collect_body(amount, phone, description, external_reference, currency)))
+        if wait and not tx.is_final:
+            return self.wait_for_transaction(tx.reference, timeout=timeout, interval=interval)
+        return tx
+
+    def withdraw(self, amount: Amount, phone: str, description: str = "", external_reference: Optional[str] = None, *,
+                 currency: str = "XAF", wait: bool = False, timeout: float = 120.0, interval: float = 3.0) -> Transaction:
+        """Send `amount` from your Paysawa balance to `phone`. Raises InsufficientFundsError if amount + fee exceeds the balance."""
+        tx = Transaction(self._request("POST", "withdraw/", _withdraw_body(amount, phone, description, external_reference, currency)))
+        if wait and not tx.is_final:
+            return self.wait_for_transaction(tx.reference, timeout=timeout, interval=interval)
+        return tx
+
+    def get_transaction(self, reference: str) -> Transaction:
+        """Latest state of a collection, withdrawal (col_..., pay_...) or payment link (cs_...)."""
+        return Transaction(self._request("GET", f"transaction/{reference}/"))
+
+    def wait_for_transaction(self, reference: str, *, timeout: float = 120.0, interval: float = 3.0,
+                             on_update: Optional[Callable[[Transaction], None]] = None) -> Transaction:
+        deadline = _monotonic() + timeout
+        tx = self.get_transaction(reference)
+        while not tx.is_final:
+            if on_update:
+                on_update(tx)
+            if _monotonic() >= deadline:
+                raise WaitTimeoutError(f"Transaction {reference} is still pending after {timeout:g}s.", transaction=tx)
+            _sleep(max(0.0, min(interval, deadline - _monotonic())))
+            tx = self.get_transaction(reference)
+        return tx
+
+    def get_balance(self) -> Result:
+        """{'total_balance': ..., 'held_balance': ..., 'currency': 'XAF'}. One balance per merchant."""
+        return Result(self._request("GET", "balance/"))
+
+    def get_payment_link(self, amount: Amount, description: str = "", external_reference: Optional[str] = None,
+                         redirect_url: Optional[str] = None, *, currency: str = "XAF") -> Result:
+        """Create a hosted payment page link. Returns {'link': ..., 'reference': 'cs_...'}."""
+        return Result(self._request("POST", "get_payment_link/", _link_body(amount, description, external_reference, redirect_url, currency)))
+
+    def verify_webhook(self, params: Mapping[str, Any]) -> WebhookEvent:
+        """Verify a webhook received on your webhook URL with this client's webhook_key."""
+        return verify_webhook(params, self.webhook_key)
+
+
+class AsyncClient:
+    """Asynchronous client with the same methods. Use `async with AsyncClient(...) as client:`."""
+
+    def __init__(self, app_username: str, app_password: str, webhook_key: str = "", *, base_url: Optional[str] = None,
+                 timeout: float = 30.0, max_retries: int = 2, http_client: Optional[httpx.AsyncClient] = None):
+        if not app_username or not app_password:
+            raise ValueError("app_username and app_password are required (create an app in your Paysawa dashboard).")
+        self.base_url = _base_url(base_url)
+        self.app_username = app_username
+        self._password = app_password
+        self.webhook_key = webhook_key
+        self.max_retries = max(0, int(max_retries))
+        self._owns_http = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout)
+        self._token: Optional[str] = None
+        self._expires_at = 0.0
+        self._lock: Optional[asyncio.Lock] = None
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> "AsyncClient":
+        return cls(_env("PAYSAWA_APP_USERNAME"), _env("PAYSAWA_APP_PASSWORD"), _env("PAYSAWA_WEBHOOK_KEY", required=False), **kwargs)
+
+    async def __aenter__(self) -> "AsyncClient":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_http:
+            await self._http.aclose()
+
+    async def _send(self, method: str, url: str, json: Any = None, headers: Optional[dict] = None) -> Any:
+        try:
+            return await self._http.request(method, url, json=json, headers=headers or {})
+        except httpx.TimeoutException:
+            raise NetworkError("Paysawa did not answer in time.", code="timeout") from None
+        except httpx.HTTPError:
+            raise NetworkError(f"Cannot reach Paysawa at {self.base_url}.", code="unreachable") from None
+
+    async def _get_token(self, force: bool = False) -> str:
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        async with self._lock:
+            if not force and self._token and _monotonic() < self._expires_at:
+                return self._token
+            response = await self._send("POST", self.base_url + "token/", {"username": self.app_username, "password": self._password})
+            if response.status_code >= 400:
+                _raise(response)
+            data = response.json()
+            self._token = data["token"]
+            self._expires_at = _monotonic() + max(int(data.get("expires_in") or 300) - 30, 10)
+            return self._token
+
+    async def _request(self, method: str, path: str, json: Any = None) -> dict:
+        retries_left = self.max_retries if method == "GET" else 0
+        force_token = False
+        while True:
+            token = await self._get_token(force=force_token)
+            try:
+                response = await self._send(method, self.base_url + path, json, {"Authorization": f"Token {token}"})
+            except NetworkError:
+                if retries_left <= 0:
+                    raise
+                retries_left -= 1
+                await _asleep(0.5 * (self.max_retries - retries_left))
+                continue
+            if response.status_code == 401 and not force_token:
+                force_token = True
+                continue
+            if response.status_code >= 500 and retries_left > 0:
+                retries_left -= 1
+                await _asleep(0.5 * (self.max_retries - retries_left))
+                continue
+            if response.status_code >= 400:
+                _raise(response)
+            return response.json()
+
+    async def collect(self, amount: Amount, phone: str, description: str = "", external_reference: Optional[str] = None, *,
+                      currency: str = "XAF", wait: bool = False, timeout: float = 120.0, interval: float = 3.0) -> Transaction:
+        tx = Transaction(await self._request("POST", "collect/", _collect_body(amount, phone, description, external_reference, currency)))
+        if wait and not tx.is_final:
+            return await self.wait_for_transaction(tx.reference, timeout=timeout, interval=interval)
+        return tx
+
+    async def withdraw(self, amount: Amount, phone: str, description: str = "", external_reference: Optional[str] = None, *,
+                       currency: str = "XAF", wait: bool = False, timeout: float = 120.0, interval: float = 3.0) -> Transaction:
+        tx = Transaction(await self._request("POST", "withdraw/", _withdraw_body(amount, phone, description, external_reference, currency)))
+        if wait and not tx.is_final:
+            return await self.wait_for_transaction(tx.reference, timeout=timeout, interval=interval)
+        return tx
+
+    async def get_transaction(self, reference: str) -> Transaction:
+        return Transaction(await self._request("GET", f"transaction/{reference}/"))
+
+    async def wait_for_transaction(self, reference: str, *, timeout: float = 120.0, interval: float = 3.0,
+                                   on_update: Optional[Callable[[Transaction], None]] = None) -> Transaction:
+        deadline = _monotonic() + timeout
+        tx = await self.get_transaction(reference)
+        while not tx.is_final:
+            if on_update:
+                on_update(tx)
+            if _monotonic() >= deadline:
+                raise WaitTimeoutError(f"Transaction {reference} is still pending after {timeout:g}s.", transaction=tx)
+            await _asleep(max(0.0, min(interval, deadline - _monotonic())))
+            tx = await self.get_transaction(reference)
+        return tx
+
+    async def get_balance(self) -> Result:
+        return Result(await self._request("GET", "balance/"))
+
+    async def get_payment_link(self, amount: Amount, description: str = "", external_reference: Optional[str] = None,
+                               redirect_url: Optional[str] = None, *, currency: str = "XAF") -> Result:
+        return Result(await self._request("POST", "get_payment_link/", _link_body(amount, description, external_reference, redirect_url, currency)))
+
+    def verify_webhook(self, params: Mapping[str, Any]) -> WebhookEvent:
+        return verify_webhook(params, self.webhook_key)

paysawa-0.1.0/src/paysawa/errors.py

@@ -0,0 +1,78 @@
+"""Exceptions raised by the SDK. Catch PaysawaError to catch them all."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class PaysawaError(Exception):
+    """Base class. `status` is the HTTP status (None for network problems), `code` the machine-readable error code."""
+
+    def __init__(self, message: str, *, status: Optional[int] = None, code: Optional[str] = None):
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+
+    def __str__(self) -> str:
+        prefix = f"[{self.code}] " if self.code else ""
+        return f"{prefix}{self.message}"
+
+
+class AuthenticationError(PaysawaError):
+    """Wrong app username/password, or an expired/invalid token (HTTP 401)."""
+
+
+class PermissionDeniedError(PaysawaError):
+    """The account cannot do this yet, e.g. live mode not enabled or account suspended (HTTP 403)."""
+
+
+class InvalidRequestError(PaysawaError):
+    """The request was refused: bad amount, bad phone number, unknown reference, limits... (HTTP 400/404/409/410/422)."""
+
+
+class InsufficientFundsError(InvalidRequestError):
+    """A withdrawal needs more than the available balance (amount + fee)."""
+
+
+class RateLimitError(PaysawaError):
+    """Too many requests (HTTP 429)."""
+
+
+class ServerError(PaysawaError):
+    """Paysawa had a problem or is busy (HTTP 5xx). Safe to retry reads; for payments check the transaction first."""
+
+
+class NetworkError(PaysawaError):
+    """Could not reach Paysawa (timeout, DNS, connection refused)."""
+
+
+class WebhookVerificationError(PaysawaError):
+    """A webhook did not pass signature verification. Do NOT trust it."""
+
+
+class WaitTimeoutError(PaysawaError):
+    """wait_for_transaction() gave up while the transaction was still pending. `.transaction` holds its latest state."""
+
+    def __init__(self, message: str, *, transaction: Any = None):
+        super().__init__(message, code="wait_timeout")
+        self.transaction = transaction
+
+
+def error_from_response(status: int, data: Any) -> PaysawaError:
+    """Builds the right exception from an error response (flat {message, code} or {error: {code, message}})."""
+    message, code = f"HTTP {status}", None
+    if isinstance(data, dict):
+        inner = data.get("error") if isinstance(data.get("error"), dict) else data
+        message = str(inner.get("message") or data.get("detail") or message)
+        code = inner.get("code")
+    if code == "insufficient_funds":
+        return InsufficientFundsError(message, status=status, code=code)
+    if status == 401:
+        return AuthenticationError(message, status=status, code=code)
+    if status == 403:
+        return PermissionDeniedError(message, status=status, code=code)
+    if status == 429:
+        return RateLimitError(message, status=status, code=code)
+    if status >= 500:
+        return ServerError(message, status=status, code=code)
+    return InvalidRequestError(message, status=status, code=code)

paysawa-0.1.0/src/paysawa/models.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import Any
+
+PENDING = "PENDING"
+SUCCESSFUL = "SUCCESSFUL"
+FAILED = "FAILED"
+
+
+class Result(dict):
+    """A plain dict that also allows attribute access: result["reference"] == result.reference."""
+
+    __slots__ = ()
+
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return self[name]
+        except KeyError:
+            raise AttributeError(name) from None
+
+
+class Transaction(Result):
+    """A collection or withdrawal. `status` is PENDING, SUCCESSFUL or FAILED."""
+
+    __slots__ = ()
+
+    @property
+    def is_pending(self) -> bool:
+        return self.get("status") == PENDING
+
+    @property
+    def is_successful(self) -> bool:
+        return self.get("status") == SUCCESSFUL
+
+    @property
+    def is_failed(self) -> bool:
+        return self.get("status") == FAILED
+
+    @property
+    def is_final(self) -> bool:
+        return self.get("status") in (SUCCESSFUL, FAILED)
+
+
+class WebhookEvent(Transaction):
+    """A verified webhook: status, reference, amount (int), currency, operator, external_reference..."""
+
+    __slots__ = ()

paysawa-0.1.0/src/paysawa/webhooks.py

@@ -0,0 +1,41 @@
+"""Webhook verification. Paysawa calls your app's webhook URL with a GET request: query parameters plus a `signature`
+(a JWT signed with your app's webhook key). Always verify it before trusting the data."""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+import jwt
+
+from .errors import WebhookVerificationError
+from .models import WebhookEvent
+
+
+def verify_webhook(params: Mapping[str, Any], webhook_key: str) -> WebhookEvent:
+    """Verify a webhook and return it as a WebhookEvent. Raises WebhookVerificationError if it is not authentic.
+
+    `params` are the query parameters, as plain strings (Flask: request.args.to_dict(), FastAPI: dict(request.query_params),
+    Django: request.GET.dict()). Besides checking the signature, every signed field is compared with the received one, so a
+    valid signature cannot be replayed with other values (a different amount, for example).
+    """
+    if not webhook_key:
+        raise WebhookVerificationError("A webhook_key is required to verify webhooks.", code="no_webhook_key")
+    data = dict(params)
+    signature = data.get("signature")
+    if not signature:
+        raise WebhookVerificationError("The webhook has no signature.", code="missing_signature")
+    try:
+        signed = jwt.decode(signature, webhook_key, algorithms=["HS256"], leeway=10)
+    except jwt.ExpiredSignatureError:
+        raise WebhookVerificationError("The webhook signature has expired.", code="expired_signature") from None
+    except jwt.PyJWTError:
+        raise WebhookVerificationError("The webhook signature is not valid for this webhook key.", code="invalid_signature") from None
+    clean = {k: v for k, v in data.items() if k != "signature"}
+    for key, value in signed.items():
+        if key in ("iat", "exp"):
+            continue
+        if str(clean.get(key, "")) != str(value):
+            raise WebhookVerificationError(f"Parameter '{key}' does not match what was signed.", code="tampered")
+    amount = clean.get("amount")
+    if isinstance(amount, str) and amount.isdigit():
+        clean["amount"] = int(amount)
+    return WebhookEvent(clean)

paysawa-0.1.0/src/paysawa.egg-info/PKG-INFO

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: paysawa
+Version: 0.1.0
+Summary: Python SDK for the Paysawa mobile money gateway (MTN / Orange): collect, withdraw, payment links and signed webhooks.
+Author: Paysawa
+License: MIT
+Project-URL: Homepage, https://github.com/ChrinaerDev/paysawa-python
+Project-URL: Issues, https://github.com/ChrinaerDev/paysawa-python/issues
+Project-URL: Changelog, https://github.com/ChrinaerDev/paysawa-python/blob/main/CHANGELOG.md
+Keywords: paysawa,mobile money,payments,cameroon,mtn,orange money,campay,xaf
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.25
+Requires-Dist: PyJWT>=2.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: build>=1.0; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Dynamic: license-file
+
+# paysawa
+
+Python SDK for the **Paysawa** mobile money gateway (MTN Mobile Money and Orange Money, XAF).
+Collect payments, send money, create payment links and verify signed webhooks with a few lines of code.
+It speaks Paysawa's Campay-style API, so the concepts are the same as Campay's.
+
+```bash
+pip install paysawa
+```
+
+## 1. Get your credentials
+
+In your Paysawa dashboard create an **app**. It gives you three values (you can show them again any time):
+
+| Value | What it is |
+|---|---|
+| App username | like `pa_1a2b3c4d5e6f7a8b` |
+| App password | secret, never put it in front-end code or in git |
+| Webhook key | verifies that webhooks really come from Paysawa |
+
+A **test** app uses the sandbox (no real money). A **live** app moves real money.
+
+## 2. Quick start
+
+```python
+from paysawa import Client
+
+client = Client(
+    app_username="pa_xxxxxxxxxxxxxxxx",
+    app_password="your-app-password",
+    webhook_key="whk_xxxxxxxx",
+    base_url="https://YOUR-PAYSAWA-URL/api/",   # or set PAYSAWA_BASE_URL
+)
+
+# Ask a customer to pay: they get a prompt on their phone and approve with their PIN.
+tx = client.collect(amount=5000, phone="670000001", description="Order 1001",
+                    external_reference="order-1001", wait=True)   # wait=True blocks until final
+if tx.is_successful:
+    print("Paid!", tx.reference)
+else:
+    print("Not paid:", tx.status)
+
+print(client.get_balance().total_balance)                          # your Paysawa balance
+client.withdraw(amount=1000, phone="690000001", description="Refund")   # pay money out
+link = client.get_payment_link(amount=2000, description="Order 1002", redirect_url="https://shop.example.com/thanks")
+print(link.link)                                                    # send this to your customer
+```
+
+Put the credentials in environment variables instead of code and use `Client.from_env()`:
+`PAYSAWA_APP_USERNAME`, `PAYSAWA_APP_PASSWORD`, `PAYSAWA_WEBHOOK_KEY`, `PAYSAWA_BASE_URL`.
+
+## 3. Statuses
+
+Every transaction is `PENDING`, `SUCCESSFUL` or `FAILED` (`tx.is_pending`, `tx.is_successful`, `tx.is_failed`, `tx.is_final`).
+A collection stays `PENDING` until the customer approves. Without `wait=True`, check it later with
+`client.get_transaction(reference)` or use `client.wait_for_transaction(reference, timeout=120)`, or rely on webhooks.
+
+## 4. Webhooks
+
+Set your app's webhook URL in the dashboard. Paysawa calls it with a `GET` and query parameters plus a signed `signature`.
+**Always verify it**:
+
+```python
+# Flask
+@app.get("/webhooks/paysawa")
+def paysawa_webhook():
+    try:
+        event = client.verify_webhook(request.args.to_dict())
+    except WebhookVerificationError:
+        return "invalid", 401
+    if event.is_successful:
+        mark_order_paid(event.external_reference, event.amount)
+    return "ok"
+```
+
+```python
+# FastAPI
+@app.get("/webhooks/paysawa")
+async def paysawa_webhook(request: Request):
+    event = client.verify_webhook(dict(request.query_params))   # raises WebhookVerificationError if not authentic
+    ...
+```
+
+Django: `client.verify_webhook(request.GET.dict())`. Reply with any 2xx status; otherwise Paysawa retries.
+Check `event.amount` against the order before you ship anything.
+
+## 5. Async
+
+```python
+from paysawa import AsyncClient
+
+async with AsyncClient.from_env() as client:
+    tx = await client.collect(5000, "670000001", "Order 1001", "order-1001", wait=True)
+```
+
+## 6. Errors
+
+All errors inherit from `PaysawaError` (`.message`, `.status`, `.code`):
+
+| Exception | When |
+|---|---|
+| `AuthenticationError` | wrong app username/password |
+| `PermissionDeniedError` | live mode not enabled, account suspended |
+| `InvalidRequestError` | bad amount or phone number, unknown reference, limits |
+| `InsufficientFundsError` | withdrawal larger than your balance (amount + fee) |
+| `RateLimitError` | too many requests |
+| `ServerError` / `NetworkError` | Paysawa busy or unreachable |
+| `WaitTimeoutError` | `wait_for_transaction` gave up (`.transaction` has the latest state) |
+| `WebhookVerificationError` | the webhook is not authentic: ignore it |
+
+Payments (collect, withdraw) are **never retried automatically**, so a retry can never charge twice.
+Reads are retried twice. If a payment call fails with a network error, look the payment up by your
+`external_reference` before trying again.
+
+## 7. Sandbox numbers (test apps)
+
+`670000001` succeeds, a number ending in `0000` fails, a number ending in `9999` stays pending.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

paysawa-0.1.0/src/paysawa.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/paysawa/__init__.py
+src/paysawa/_version.py
+src/paysawa/client.py
+src/paysawa/errors.py
+src/paysawa/models.py
+src/paysawa/py.typed
+src/paysawa/webhooks.py
+src/paysawa.egg-info/PKG-INFO
+src/paysawa.egg-info/SOURCES.txt
+src/paysawa.egg-info/dependency_links.txt
+src/paysawa.egg-info/requires.txt
+src/paysawa.egg-info/top_level.txt
+tests/test_client.py
+tests/test_webhooks.py

paysawa-0.1.0/src/paysawa.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

paysawa-0.1.0/src/paysawa.egg-info/requires.txt

@@ -0,0 +1,8 @@
+httpx>=0.25
+PyJWT>=2.4
+
+[dev]
+pytest>=8
+pytest-asyncio>=0.23
+build>=1.0
+twine>=5.0

paysawa-0.1.0/src/paysawa.egg-info/top_level.txt

@@ -0,0 +1 @@
+paysawa

paysawa-0.1.0/tests/test_client.py

@@ -0,0 +1,207 @@
+import json
+import os
+
+import httpx
+import pytest
+
+import paysawa
+from paysawa import (
+    AsyncClient, AuthenticationError, Client, InsufficientFundsError, InvalidRequestError, NetworkError,
+    PermissionDeniedError, RateLimitError, ServerError, Transaction, WaitTimeoutError,
+)
+import paysawa.client as client_module
+
+client_module._sleep = lambda seconds: None          # keep the tests instant
+
+
+async def _no_sleep(seconds):
+    return None
+
+
+client_module._asleep = _no_sleep
+BASE = "http://paysawa.test/api/"
+
+
+def make_server(**state):
+    state.setdefault("calls", [])
+    state.setdefault("tokens", 0)
+    state.setdefault("script", {})   # path suffix -> list of responses (last one repeats)
+
+    def respond(path):
+        queue = state["script"].get(path)
+        if not queue:
+            return None
+        item = queue.pop(0) if len(queue) > 1 else queue[0]
+        if isinstance(item, Exception):
+            raise item
+        return httpx.Response(item[0], json=item[1])
+
+    def handler(request):
+        path = request.url.path
+        body = json.loads(request.content) if request.content else {}
+        state["calls"].append((request.method, path, body, {k.lower(): v for k, v in request.headers.items()}))
+        if path.endswith("/token/"):
+            state["tokens"] += 1
+            if body.get("password") != "secret":
+                return httpx.Response(401, json={"message": "Invalid app username or password.", "code": "invalid_credentials"})
+            return httpx.Response(200, json={"token": f"T{state['tokens']}", "expires_in": 3600})
+        for suffix in state["script"]:
+            if path.endswith(suffix):
+                return respond(suffix)
+        return httpx.Response(404, json={"message": "no such endpoint", "code": "not_found"})
+
+    return handler, state
+
+
+def make_client(**state):
+    handler, st = make_server(**state)
+    http = httpx.Client(transport=httpx.MockTransport(handler))
+    return Client("pa_demo", "secret", "whk_demo", base_url=BASE, http_client=http), st
+
+
+def calls_to(state, suffix):
+    return [c for c in state["calls"] if c[1].endswith(suffix)]
+
+
+def test_collect_sends_a_campay_style_request_and_caches_the_token():
+    client, st = make_client(script={"/collect/": [(200, {"reference": "col_1", "ussd_code": "*126#", "operator": "MTN", "status": "PENDING"})],
+                                     "/balance/": [(200, {"total_balance": 10, "held_balance": 0, "currency": "XAF"})]})
+    tx = client.collect(5000, "670000001", "Order 1001", "order-1001")
+    client.get_balance()
+    assert isinstance(tx, Transaction) and tx.reference == "col_1" and tx["operator"] == "MTN" and tx.is_pending and not tx.is_final
+    assert st["tokens"] == 1
+    method, path, body, headers = calls_to(st, "/collect/")[0]
+    assert headers["authorization"] == "Token T1"
+    assert body == {"amount": "5000", "currency": "XAF", "from": "670000001", "description": "Order 1001", "external_reference": "order-1001"}
+
+
+def test_withdraw_uses_the_to_field_and_reports_status():
+    client, st = make_client(script={"/withdraw/": [(200, {"reference": "pay_1", "status": "SUCCESSFUL", "amount": 1000, "currency": "XAF", "operator": "ORANGE"})]})
+    tx = client.withdraw("1000", "690000001", "Refund")
+    assert tx.is_successful and tx.is_final and tx.operator == "ORANGE"
+    assert calls_to(st, "/withdraw/")[0][2]["to"] == "690000001"
+
+
+def test_expired_token_is_replaced_once():
+    handler, st = make_server(script={"/balance/": [(401, {"message": "Invalid or expired token.", "code": "unauthorized"}),
+                                                    (200, {"total_balance": 4875, "held_balance": 0, "currency": "XAF"})]})
+    client = Client("pa_demo", "secret", base_url=BASE, http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+    assert client.get_balance().total_balance == 4875
+    assert st["tokens"] == 2
+
+
+def test_wrong_credentials_raise_authentication_error():
+    handler, _ = make_server()
+    client = Client("pa_demo", "wrong", base_url=BASE, http_client=httpx.Client(transport=httpx.MockTransport(handler)))
+    with pytest.raises(AuthenticationError) as exc:
+        client.get_balance()
+    assert exc.value.code == "invalid_credentials" and exc.value.status == 401
+
+
+def test_error_responses_become_specific_exceptions():
+    client, _ = make_client(script={
+        "/withdraw/": [(402, {"message": "Available balance is 0 XAF, 1025 XAF needed (amount + fee).", "code": "insufficient_funds"})],
+        "/collect/": [(422, {"message": "expected a Cameroonian mobile number", "code": "invalid_phone"})],
+        "/get_payment_link/": [(403, {"message": "Live mode is not enabled for this account yet.", "code": "live_not_enabled"})],
+        "/balance/": [(429, {"message": "Too many requests, slow down.", "code": "rate_limited"})],
+    })
+    with pytest.raises(InsufficientFundsError) as exc:
+        client.withdraw(1000, "690000001")
+    assert exc.value.code == "insufficient_funds" and isinstance(exc.value, InvalidRequestError)
+    with pytest.raises(InvalidRequestError) as exc:
+        client.collect(1000, "12345")
+    assert exc.value.code == "invalid_phone" and "[invalid_phone]" in str(exc.value)
+    with pytest.raises(PermissionDeniedError):
+        client.get_payment_link(2000)
+    with pytest.raises(RateLimitError):
+        client.get_balance()
+
+
+def test_payments_are_never_retried_but_reads_are():
+    client, st = make_client(script={"/collect/": [(503, {"message": "busy", "code": "busy"})],
+                                     "/balance/": [(503, {"message": "busy", "code": "busy"}), (200, {"total_balance": 5, "held_balance": 0, "currency": "XAF"})]})
+    with pytest.raises(ServerError):
+        client.collect(1000, "670000001")
+    assert len(calls_to(st, "/collect/")) == 1                       # a retry could have charged the customer twice
+    assert client.get_balance().total_balance == 5
+    assert len(calls_to(st, "/balance/")) == 2
+
+
+def test_network_problems_are_wrapped():
+    client, st = make_client(script={"/collect/": [httpx.ConnectError("refused")], "/balance/": [httpx.ConnectError("refused")]})
+    with pytest.raises(NetworkError) as exc:
+        client.collect(1000, "670000001")
+    assert exc.value.code == "unreachable" and len(calls_to(st, "/collect/")) == 1
+    with pytest.raises(NetworkError):
+        client.get_balance()
+    assert len(calls_to(st, "/balance/")) == 3                       # 1 try + 2 retries
+
+
+def test_wait_for_transaction_polls_until_final():
+    pending = (200, {"reference": "col_1", "status": "PENDING"})
+    done = (200, {"reference": "col_1", "status": "SUCCESSFUL", "amount": 5000})
+    client, st = make_client(script={"/collect/": [(200, {"reference": "col_1", "status": "PENDING", "operator": "MTN", "ussd_code": "*126#"})],
+                                     "/transaction/col_1/": [pending, pending, done]})
+    tx = client.collect(5000, "670000001", wait=True)
+    assert tx.is_successful and tx.amount == 5000
+    assert len(calls_to(st, "/transaction/col_1/")) == 3
+
+
+def test_wait_for_transaction_times_out_with_the_latest_state():
+    client, _ = make_client(script={"/transaction/col_1/": [(200, {"reference": "col_1", "status": "PENDING"})]})
+    clock = {"t": 0.0}
+    client_module._monotonic = lambda: clock.__setitem__("t", clock["t"] + 50.0) or clock["t"]
+    try:
+        with pytest.raises(WaitTimeoutError) as exc:
+            client.wait_for_transaction("col_1", timeout=120, interval=3)
+    finally:
+        import time
+        client_module._monotonic = time.monotonic
+    assert exc.value.transaction.is_pending and exc.value.code == "wait_timeout"
+
+
+def test_balance_and_payment_link_and_attribute_access():
+    client, st = make_client(script={"/balance/": [(200, {"total_balance": 4875, "mtn_balance": None, "orange_balance": None, "held_balance": 0, "currency": "XAF"})],
+                                     "/get_payment_link/": [(200, {"link": "http://paysawa.test/pay/cs_1", "reference": "cs_1"})]})
+    assert client.get_balance().total_balance == 4875
+    link = client.get_payment_link(2000, "Order", "order-1", "https://shop.example.com/thanks")
+    assert link.link.endswith("/pay/cs_1") and link["reference"] == "cs_1"
+    assert calls_to(st, "/get_payment_link/")[0][2]["redirect_url"] == "https://shop.example.com/thanks"
+    with pytest.raises(AttributeError):
+        link.nothing_here
+
+
+def test_bad_input_fails_before_any_request():
+    client, st = make_client()
+    for bad in (0, -5, 5.5, "abc"):
+        with pytest.raises(ValueError):
+            client.collect(bad, "670000001")
+    with pytest.raises(ValueError):
+        Client("", "x")
+    assert st["calls"] == []
+
+
+def test_from_env():
+    os.environ.update({"PAYSAWA_APP_USERNAME": "pa_env", "PAYSAWA_APP_PASSWORD": "pw", "PAYSAWA_WEBHOOK_KEY": "whk_env", "PAYSAWA_BASE_URL": "http://x.test/api"})
+    try:
+        client = Client.from_env()
+        assert client.app_username == "pa_env" and client.webhook_key == "whk_env" and client.base_url == "http://x.test/api/"
+        os.environ.pop("PAYSAWA_APP_PASSWORD")
+        with pytest.raises(ValueError):
+            Client.from_env()
+    finally:
+        for key in ("PAYSAWA_APP_USERNAME", "PAYSAWA_APP_PASSWORD", "PAYSAWA_WEBHOOK_KEY", "PAYSAWA_BASE_URL"):
+            os.environ.pop(key, None)
+
+
+async def test_async_client_collect_and_wait():
+    handler, st = make_server(script={"/collect/": [(200, {"reference": "col_7", "status": "PENDING"})],
+                                      "/transaction/col_7/": [(200, {"reference": "col_7", "status": "PENDING"}), (200, {"reference": "col_7", "status": "FAILED", "reason": "x"})]})
+    client = AsyncClient("pa_demo", "secret", "whk_demo", base_url=BASE, http_client=httpx.AsyncClient(transport=httpx.MockTransport(handler)))
+    tx = await client.collect(5000, "670000000", wait=True)
+    assert tx.is_failed and tx.reason == "x"
+    assert st["tokens"] == 1
+
+
+def test_package_exports():
+    assert paysawa.__version__ and paysawa.PENDING == "PENDING" and callable(paysawa.verify_webhook)

paysawa-0.1.0/tests/test_webhooks.py

@@ -0,0 +1,46 @@
+import time
+
+import jwt
+import pytest
+
+from paysawa import Client, WebhookVerificationError, verify_webhook
+
+KEY = "whk_test_key"
+
+
+def signed(params, key=KEY, exp_in=3600):
+    now = int(time.time())
+    return {**params, "signature": jwt.encode({**params, "iat": now, "exp": now + exp_in}, key, algorithm="HS256")}
+
+
+PARAMS = {"status": "SUCCESSFUL", "reference": "col_1", "amount": "5000", "currency": "XAF", "operator": "MTN",
+          "code": "", "operator_reference": "op-1", "external_reference": "order-1001"}
+
+
+def test_valid_webhook_becomes_an_event():
+    event = verify_webhook(signed(PARAMS), KEY)
+    assert event.is_successful and event.amount == 5000 and event.external_reference == "order-1001" and "signature" not in event
+
+
+def test_client_verifies_with_its_own_key():
+    client = Client("pa_x", "pw", KEY, base_url="http://x.test/api/")
+    assert client.verify_webhook(signed(PARAMS)).reference == "col_1"
+
+
+def test_changed_values_wrong_key_missing_and_expired_are_rejected():
+    good = signed(PARAMS)
+    with pytest.raises(WebhookVerificationError) as exc:
+        verify_webhook({**good, "amount": "1"}, KEY)
+    assert exc.value.code == "tampered"
+    with pytest.raises(WebhookVerificationError) as exc:
+        verify_webhook(signed(PARAMS, key="whk_other"), KEY)
+    assert exc.value.code == "invalid_signature"
+    with pytest.raises(WebhookVerificationError) as exc:
+        verify_webhook(PARAMS, KEY)
+    assert exc.value.code == "missing_signature"
+    with pytest.raises(WebhookVerificationError) as exc:
+        verify_webhook(signed(PARAMS, exp_in=-3600), KEY)
+    assert exc.value.code == "expired_signature"
+    with pytest.raises(WebhookVerificationError) as exc:
+        verify_webhook(good, "")
+    assert exc.value.code == "no_webhook_key"