hostpay 0.1.0__tar.gz

hostpay-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/

hostpay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Heuristic of Science and Technology SL Limited ("HOST SL")
+
+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.

hostpay-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: hostpay
+Version: 0.1.0
+Summary: Python SDK for the HostPay payments API
+Project-URL: Homepage, https://hpay.host-sl.com
+Project-URL: Documentation, https://hpay.host-sl.com/docs
+Project-URL: Repository, https://github.com/HOST-SL/host_pay
+Author-email: HostPay <host.sl.co@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: escrow,hostpay,mobile-money,payments,sdk,wallet
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx>=0.24
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# HostPay Python SDK
+
+A small, typed client for the [HostPay](https://hpay.host-sl.com) payments API —
+wallets, deposits, transfers, payouts, escrow, and webhook verification.
+
+## Install
+
+```bash
+pip install hostpay          # once published
+# or, from this repo:
+pip install ./sdk/python
+```
+
+Requires Python 3.8+ and `httpx`.
+
+## Quickstart
+
+```python
+from hostpay import HostPay
+
+client = HostPay(api_key="ak-...", secret_key="sk-...")
+# Test Mode? use your test keys — same code, no real money moves.
+
+# 1. Create a user and their wallet
+user = client.users.create(
+    app_user_id="user_123",
+    name="Alice",
+    phone_number="+23279000000",
+    email="alice@example.com",
+)
+wallet = client.wallets.create(user.id)
+
+# 2. Deposit via mobile money
+deposit = client.deposits.mobile_money(wallet_id=wallet.id, amount=100)
+
+# 3. Check the balance (attribute or dict access)
+bal = client.wallets.balance(wallet.id)
+print(bal.balance, bal["currency"])
+
+# 4. Transfer, pay out, escrow
+client.transfers.create(sender_wallet_id=wallet.id, recipient_identifier="bob", amount=20)
+client.payouts.mobile_money(wallet_id=wallet.id, amount=5, phone_number="+23279000000")
+hold = client.escrow.hold(wallet_id=wallet.id, amount=10)
+client.escrow.release(hold.id, recipient_wallet_id="...")
+```
+
+## Authentication
+
+Pass your `api-key` and `secret-key` once at construction; they're sent on every
+request. `base_url` defaults to production — point it at your staging host for
+testing.
+
+## Idempotency
+
+Money-moving calls accept `idempotency_key` — reuse the same key to safely retry
+without double-charging:
+
+```python
+client.payouts.mobile_money(
+    wallet_id=w, amount=5, phone_number="+232...", idempotency_key="order-42-payout"
+)
+```
+
+## Verifying webhooks
+
+Pass the **raw** request body and headers straight from your web framework:
+
+```python
+from hostpay import HostPay, SignatureVerificationError
+
+client = HostPay(api_key="ak-...", secret_key="sk-...")
+
+# e.g. in Flask
+@app.post("/webhooks/hostpay")
+def hook():
+    try:
+        event = client.webhooks.construct_event(
+            payload=request.get_data(),          # raw bytes, not request.json
+            headers=request.headers,
+            secret=WEBHOOK_SIGNING_SECRET,
+        )
+    except SignatureVerificationError:
+        return "", 400
+    if event.event == "deposit.completed":
+        ...
+    return "", 200
+```
+
+Signatures are HMAC-SHA256 over `"<timestamp>.<body>"`; deliveries older than
+`tolerance` seconds (default 300) are rejected.
+
+## Errors
+
+All errors derive from `HostPayError` and carry `.status_code` and `.detail`:
+`AuthenticationError` (401/403), `InvalidRequestError` (400/404/422),
+`RateLimitError` (429), `APIError` (5xx), `APIConnectionError`,
+`SignatureVerificationError`.
+
+## Sandbox testing
+
+In Test Mode, a user's phone number drives deterministic outcomes (see the
+[Testing guide](https://hpay.host-sl.com/docs/guides/testing)): `+23299000001`
+completes, `+23299000002` fails, `+23299000009` stays pending. The same fail
+number works for payout recipients.
+
+## Typed responses
+
+Core methods are annotated with `TypedDict` models (`hostpay.models`): `users.*`
+return `UserRead`, `wallets.create/get` return `WalletRead`, `transfers`/
+`payouts` return `TransactionResponse`, and `escrow.*` returns `EscrowResponse`.
+A type checker (mypy/Pyright) will autocomplete and check keyed access —
+`user["id"]`, `wallet["balance"]`. Ad-hoc responses (wallet balance, the deposit
+envelope) stay loosely typed.
+
+At runtime every response is a `HostPayObject` (a dict), so both `resp["field"]`
+and `resp.field` work regardless of typing. The model fields mirror the committed
+[`../openapi.json`](../openapi.json), the source of truth for both SDKs —
+regenerate the spec with `python wallet-system/scripts/dump_openapi.py`.

hostpay-0.1.0/README.md

@@ -0,0 +1,118 @@
+# HostPay Python SDK
+
+A small, typed client for the [HostPay](https://hpay.host-sl.com) payments API —
+wallets, deposits, transfers, payouts, escrow, and webhook verification.
+
+## Install
+
+```bash
+pip install hostpay          # once published
+# or, from this repo:
+pip install ./sdk/python
+```
+
+Requires Python 3.8+ and `httpx`.
+
+## Quickstart
+
+```python
+from hostpay import HostPay
+
+client = HostPay(api_key="ak-...", secret_key="sk-...")
+# Test Mode? use your test keys — same code, no real money moves.
+
+# 1. Create a user and their wallet
+user = client.users.create(
+    app_user_id="user_123",
+    name="Alice",
+    phone_number="+23279000000",
+    email="alice@example.com",
+)
+wallet = client.wallets.create(user.id)
+
+# 2. Deposit via mobile money
+deposit = client.deposits.mobile_money(wallet_id=wallet.id, amount=100)
+
+# 3. Check the balance (attribute or dict access)
+bal = client.wallets.balance(wallet.id)
+print(bal.balance, bal["currency"])
+
+# 4. Transfer, pay out, escrow
+client.transfers.create(sender_wallet_id=wallet.id, recipient_identifier="bob", amount=20)
+client.payouts.mobile_money(wallet_id=wallet.id, amount=5, phone_number="+23279000000")
+hold = client.escrow.hold(wallet_id=wallet.id, amount=10)
+client.escrow.release(hold.id, recipient_wallet_id="...")
+```
+
+## Authentication
+
+Pass your `api-key` and `secret-key` once at construction; they're sent on every
+request. `base_url` defaults to production — point it at your staging host for
+testing.
+
+## Idempotency
+
+Money-moving calls accept `idempotency_key` — reuse the same key to safely retry
+without double-charging:
+
+```python
+client.payouts.mobile_money(
+    wallet_id=w, amount=5, phone_number="+232...", idempotency_key="order-42-payout"
+)
+```
+
+## Verifying webhooks
+
+Pass the **raw** request body and headers straight from your web framework:
+
+```python
+from hostpay import HostPay, SignatureVerificationError
+
+client = HostPay(api_key="ak-...", secret_key="sk-...")
+
+# e.g. in Flask
+@app.post("/webhooks/hostpay")
+def hook():
+    try:
+        event = client.webhooks.construct_event(
+            payload=request.get_data(),          # raw bytes, not request.json
+            headers=request.headers,
+            secret=WEBHOOK_SIGNING_SECRET,
+        )
+    except SignatureVerificationError:
+        return "", 400
+    if event.event == "deposit.completed":
+        ...
+    return "", 200
+```
+
+Signatures are HMAC-SHA256 over `"<timestamp>.<body>"`; deliveries older than
+`tolerance` seconds (default 300) are rejected.
+
+## Errors
+
+All errors derive from `HostPayError` and carry `.status_code` and `.detail`:
+`AuthenticationError` (401/403), `InvalidRequestError` (400/404/422),
+`RateLimitError` (429), `APIError` (5xx), `APIConnectionError`,
+`SignatureVerificationError`.
+
+## Sandbox testing
+
+In Test Mode, a user's phone number drives deterministic outcomes (see the
+[Testing guide](https://hpay.host-sl.com/docs/guides/testing)): `+23299000001`
+completes, `+23299000002` fails, `+23299000009` stays pending. The same fail
+number works for payout recipients.
+
+## Typed responses
+
+Core methods are annotated with `TypedDict` models (`hostpay.models`): `users.*`
+return `UserRead`, `wallets.create/get` return `WalletRead`, `transfers`/
+`payouts` return `TransactionResponse`, and `escrow.*` returns `EscrowResponse`.
+A type checker (mypy/Pyright) will autocomplete and check keyed access —
+`user["id"]`, `wallet["balance"]`. Ad-hoc responses (wallet balance, the deposit
+envelope) stay loosely typed.
+
+At runtime every response is a `HostPayObject` (a dict), so both `resp["field"]`
+and `resp.field` work regardless of typing. The model fields mirror the committed
+[`../openapi.json`](../openapi.json), the source of truth for both SDKs —
+regenerate the spec with `python wallet-system/scripts/dump_openapi.py`.

hostpay-0.1.0/hostpay/__init__.py

@@ -0,0 +1,31 @@
+"""HostPay Python SDK."""
+from ._client import HostPay
+from ._object import HostPayObject
+from .errors import (
+    APIConnectionError,
+    APIError,
+    AuthenticationError,
+    HostPayError,
+    InvalidRequestError,
+    RateLimitError,
+    SignatureVerificationError,
+)
+from .models import EscrowResponse, TransactionResponse, UserRead, WalletRead
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "HostPay",
+    "HostPayObject",
+    "HostPayError",
+    "AuthenticationError",
+    "InvalidRequestError",
+    "RateLimitError",
+    "APIError",
+    "APIConnectionError",
+    "SignatureVerificationError",
+    "UserRead",
+    "WalletRead",
+    "TransactionResponse",
+    "EscrowResponse",
+]

hostpay-0.1.0/hostpay/_client.py

@@ -0,0 +1,129 @@
+"""HTTP transport + the top-level HostPay client."""
+from __future__ import annotations
+
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from ._object import HostPayObject, _wrap
+from .errors import APIConnectionError, error_from_status
+from .resources import Deposits, Escrow, Payouts, Transfers, Users, Wallets
+from .webhooks import Webhooks
+
+DEFAULT_BASE_URL = "https://hpay-api.host-sl.com"
+
+
+class _Transport:
+    """Builds authenticated requests, retries transient failures, maps errors."""
+
+    def __init__(
+        self,
+        api_key: str,
+        secret_key: str,
+        base_url: str,
+        timeout: float,
+        max_retries: int,
+        http_client: Optional[httpx.Client],
+    ) -> None:
+        self._max_retries = max_retries
+        # Auth is applied per-request so a caller-supplied http_client is still
+        # authenticated.
+        self._auth = {
+            "api-key": api_key,
+            "secret-key": secret_key,
+            "User-Agent": "hostpay-python/0.1.0",
+        }
+        self._client = http_client or httpx.Client(
+            base_url=base_url.rstrip("/"), timeout=timeout
+        )
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[dict] = None,
+        params: Optional[dict] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        headers: Dict[str, str] = dict(self._auth)
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        # Retry only idempotent-safe conditions: connection errors and 5xx. POSTs
+        # are retried too — the API supports Idempotency-Key for money movements.
+        last_exc: Optional[Exception] = None
+        for attempt in range(self._max_retries + 1):
+            try:
+                resp = self._client.request(
+                    method, path, json=json, params=params, headers=headers
+                )
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    time.sleep(0.5 * (2 ** attempt))
+                    continue
+                raise APIConnectionError(f"Could not reach HostPay: {exc}") from exc
+
+            if resp.status_code >= 500 and attempt < self._max_retries:
+                time.sleep(0.5 * (2 ** attempt))
+                continue
+            return _handle_response(resp)
+        raise APIConnectionError(f"Could not reach HostPay: {last_exc}")
+
+    def close(self) -> None:
+        self._client.close()
+
+
+def _handle_response(resp: "httpx.Response") -> Any:
+    if 200 <= resp.status_code < 300:
+        if not resp.content:
+            return None
+        return _wrap(resp.json())
+    try:
+        body = resp.json()
+        detail = body.get("detail", body) if isinstance(body, dict) else body
+    except ValueError:
+        detail = resp.text
+    message = detail if isinstance(detail, str) else f"HTTP {resp.status_code}"
+    raise error_from_status(resp.status_code, message, detail)
+
+
+class HostPay:
+    """HostPay API client.
+
+    >>> client = HostPay(api_key="ak-...", secret_key="sk-...")
+    >>> user = client.users.create(app_user_id="u1", name="Alice", phone_number="+23279000000")
+    >>> wallet = client.wallets.create(user.id)
+    >>> client.deposits.mobile_money(wallet_id=wallet.id, amount=100)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        secret_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        max_retries: int = 2,
+        http_client: Optional[httpx.Client] = None,
+    ) -> None:
+        if not api_key or not secret_key:
+            raise ValueError("api_key and secret_key are required")
+        self._transport = _Transport(
+            api_key, secret_key, base_url, timeout, max_retries, http_client
+        )
+        self.users = Users(self._transport)
+        self.wallets = Wallets(self._transport)
+        self.deposits = Deposits(self._transport)
+        self.transfers = Transfers(self._transport)
+        self.payouts = Payouts(self._transport)
+        self.escrow = Escrow(self._transport)
+        self.webhooks = Webhooks()
+
+    def close(self) -> None:
+        self._transport.close()
+
+    def __enter__(self) -> "HostPay":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

hostpay-0.1.0/hostpay/_object.py

@@ -0,0 +1,31 @@
+"""Lightweight attribute-access wrapper for API responses.
+
+Responses come back as HostPayObject so you can use `wallet.id` and
+`wallet["id"]` interchangeably. Unknown/new fields are preserved automatically —
+strict typed models can be generated later from ../openapi.json.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+class HostPayObject(dict):
+    def __getattr__(self, name: str) -> Any:
+        try:
+            return _wrap(self[name])
+        except KeyError as exc:
+            raise AttributeError(name) from exc
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        self[name] = value
+
+    def __repr__(self) -> str:
+        return f"HostPayObject({dict.__repr__(self)})"
+
+
+def _wrap(value: Any) -> Any:
+    if isinstance(value, dict):
+        return HostPayObject(value)
+    if isinstance(value, list):
+        return [_wrap(v) for v in value]
+    return value

hostpay-0.1.0/hostpay/errors.py

@@ -0,0 +1,54 @@
+"""Exception hierarchy for the HostPay SDK."""
+from __future__ import annotations
+
+from typing import Optional
+
+
+class HostPayError(Exception):
+    """Base class for all SDK errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        detail: Optional[object] = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+
+class AuthenticationError(HostPayError):
+    """Invalid or missing api-key / secret-key (401, 403)."""
+
+
+class InvalidRequestError(HostPayError):
+    """Bad request, not found, or validation error (400, 404, 422)."""
+
+
+class RateLimitError(HostPayError):
+    """Too many requests (429)."""
+
+
+class APIError(HostPayError):
+    """Server-side error (5xx)."""
+
+
+class APIConnectionError(HostPayError):
+    """Network problem reaching the API."""
+
+
+class SignatureVerificationError(HostPayError):
+    """A webhook signature could not be verified."""
+
+
+def error_from_status(status_code: int, message: str, detail: object) -> HostPayError:
+    if status_code in (401, 403):
+        cls = AuthenticationError
+    elif status_code == 429:
+        cls = RateLimitError
+    elif 400 <= status_code < 500:
+        cls = InvalidRequestError
+    else:
+        cls = APIError
+    return cls(message, status_code=status_code, detail=detail)

hostpay-0.1.0/hostpay/models.py

@@ -0,0 +1,91 @@
+"""Response models (TypedDict) mirroring the OpenAPI schemas.
+
+Compile-time only: responses are returned as dict-like ``HostPayObject`` at
+runtime, which is structurally these types. Access typed fields with
+``resp["field"]`` (attribute access ``resp.field`` also works at runtime).
+
+Fields mirror ../../openapi.json — the source of truth. Regenerate/refresh when
+the API changes.
+"""
+from __future__ import annotations
+
+from typing import Optional, TypedDict
+
+
+class _UserRequired(TypedDict):
+    id: str
+    app_user_id: str
+    name: str
+    phone_number: str
+    created_at: str
+
+
+class UserRead(_UserRequired, total=False):
+    email: Optional[str]
+    username: Optional[str]
+    is_active: bool
+    stripe_connect_account_id: Optional[str]
+    stripe_connect_verified: Optional[bool]
+
+
+class _WalletRequired(TypedDict):
+    id: str
+    user_id: str
+    balance: str
+    currency: str
+    created_at: str
+    updated_at: str
+
+
+class WalletRead(_WalletRequired, total=False):
+    is_active: bool
+
+
+class _TransactionRequired(TypedDict):
+    id: str
+    amount: str
+    transaction_type: str
+    payment_method: str
+    status: str
+    live_mode: bool
+    timestamp: str
+    created_at: str
+    updated_at: str
+
+
+class TransactionResponse(_TransactionRequired, total=False):
+    currency: Optional[str]
+    description: Optional[str]
+    reference_id: Optional[str]
+    wallet_id: Optional[str]
+    recipient_wallet_id: Optional[str]
+    amount_in_base_currency: Optional[str]
+    application_fee: Optional[str]
+    platform_fee: Optional[str]
+    monime_fee: Optional[str]
+    stripe_fee: Optional[str]
+    estimated_monime_fee: Optional[str]
+    estimated_stripe_fee: Optional[str]
+    total_amount_paid: Optional[str]
+    escrow_amount: Optional[str]
+    escrow_wallet_id: Optional[str]
+    order_id: Optional[str]
+
+
+class _EscrowRequired(TypedDict):
+    id: str
+    wallet_id: str
+    escrow_wallet_id: str
+    amount: float
+    escrow_amount: float
+    status: str
+    transaction_type: str
+    created_at: str
+    updated_at: str
+
+
+class EscrowResponse(_EscrowRequired, total=False):
+    recipient_wallet_id: Optional[str]
+    application_wallet_id: Optional[str]
+    application_fee: Optional[float]
+    description: Optional[str]

hostpay-0.1.0/hostpay/resources.py

@@ -0,0 +1,171 @@
+"""Resource groups mapped to the HostPay money surface.
+
+Each method mirrors a real endpoint; see ../openapi.json for the full API.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .models import EscrowResponse, TransactionResponse, UserRead, WalletRead
+
+# Mobile-money providers (wire values expected by the API).
+PROVIDER_ORANGE = "m17"
+PROVIDER_AFRICELL = "m18"
+
+
+class _Resource:
+    def __init__(self, transport: Any) -> None:
+        self._t = transport
+
+
+class Users(_Resource):
+    def create(
+        self,
+        app_user_id: str,
+        name: str,
+        phone_number: str,
+        email: Optional[str] = None,
+        username: Optional[str] = None,
+    ) -> UserRead:
+        return self._t.request("POST", "/api/v1/users/create/", json={
+            "app_user_id": app_user_id,
+            "name": name,
+            "phone_number": phone_number,
+            "email": email,
+            "username": username,
+        })
+
+    def get(self, user_id: str) -> UserRead:
+        return self._t.request("GET", f"/api/v1/users/{user_id}/")
+
+
+class Wallets(_Resource):
+    def create(self, user_id: str) -> WalletRead:
+        return self._t.request("POST", f"/api/v1/wallets/create/{user_id}/")
+
+    def get(self, user_id: str) -> WalletRead:
+        return self._t.request("GET", f"/api/v1/wallets/{user_id}/")
+
+    def balance(self, wallet_id: str) -> Any:
+        return self._t.request("GET", f"/api/v1/wallets/{wallet_id}/balance")
+
+
+class Deposits(_Resource):
+    def mobile_money(
+        self, wallet_id: str, amount: int, idempotency_key: Optional[str] = None
+    ) -> Any:
+        return self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/mobile-money-deposit",
+            json={"wallet_id": wallet_id, "amount": amount},
+            idempotency_key=idempotency_key,
+        )
+
+    def card(
+        self,
+        wallet_id: str,
+        amount: float,
+        payment_method_id: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> Any:
+        return self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/card-deposit/create",
+            json={
+                "wallet_id": wallet_id,
+                "amount": amount,
+                "payment_method_id": payment_method_id,
+            },
+            idempotency_key=idempotency_key,
+        )
+
+
+class Transfers(_Resource):
+    def create(
+        self,
+        sender_wallet_id: str,
+        recipient_identifier: str,
+        amount: float,
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> TransactionResponse:
+        return self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/transfer/",
+            json={
+                "sender_wallet_id": sender_wallet_id,
+                "recipient_identifier": recipient_identifier,
+                "amount": amount,
+                "description": description,
+            },
+            idempotency_key=idempotency_key,
+        )
+
+
+class Payouts(_Resource):
+    def mobile_money(
+        self,
+        wallet_id: str,
+        amount: float,
+        phone_number: str,
+        provider: str = PROVIDER_ORANGE,
+        currency: str = "SLE",
+        idempotency_key: Optional[str] = None,
+    ) -> TransactionResponse:
+        return self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/mobile-money-cashout/",
+            json={
+                "wallet_id": wallet_id,
+                "amount": amount,
+                "phone_number": phone_number,
+                "provider": provider,
+                "currency": currency,
+            },
+            idempotency_key=idempotency_key,
+        )
+
+    def bank(
+        self,
+        wallet_id: str,
+        amount: float,
+        currency: str = "usd",
+        description: Optional[str] = None,
+        idempotency_key: Optional[str] = None,
+    ) -> TransactionResponse:
+        return self._t.request(
+            "POST",
+            "/api/v1/transactions/wallet/payout/",
+            json={
+                "wallet_id": wallet_id,
+                "amount": amount,
+                "currency": currency,
+                "description": description,
+            },
+            idempotency_key=idempotency_key,
+        )
+
+
+class Escrow(_Resource):
+    def hold(
+        self, wallet_id: str, amount: float, description: Optional[str] = None
+    ) -> EscrowResponse:
+        return self._t.request("POST", "/api/v1/escrow/hold", json={
+            "wallet_id": wallet_id,
+            "amount": amount,
+            "description": description,
+        })
+
+    def release(
+        self, transaction_id: str, recipient_wallet_id: str, amount: Optional[float] = None
+    ) -> EscrowResponse:
+        return self._t.request(
+            "POST",
+            f"/api/v1/escrow/{transaction_id}/release",
+            json={"recipient_wallet_id": recipient_wallet_id, "amount": amount},
+        )
+
+    def refund(self, transaction_id: str, amount: Optional[float] = None) -> EscrowResponse:
+        return self._t.request(
+            "POST", f"/api/v1/escrow/{transaction_id}/refund", json={"amount": amount}
+        )

hostpay-0.1.0/hostpay/webhooks.py

@@ -0,0 +1,68 @@
+"""Verify inbound HostPay webhooks.
+
+HostPay signs each delivery with:
+    X-Webhook-Timestamp: <unix seconds>
+    X-HostPay-Signature: v1=<hex HMAC-SHA256( secret, "<timestamp>.<raw body>" )>
+
+Pass the **raw** request body (bytes or str) exactly as received — not a
+re-serialized dict — or the signature will not match.
+"""
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import time
+from typing import Any, Mapping, Union
+
+from ._object import HostPayObject
+from .errors import SignatureVerificationError
+
+_SIG_HEADER = "x-hostpay-signature"
+_TS_HEADER = "x-webhook-timestamp"
+
+
+class Webhooks:
+    @staticmethod
+    def construct_event(
+        payload: Union[str, bytes],
+        headers: Mapping[str, str],
+        secret: str,
+        tolerance: int = 300,
+    ) -> Any:
+        """Verify the signature and return the parsed event.
+
+        Raises SignatureVerificationError on any mismatch or if the timestamp is
+        older than `tolerance` seconds (replay protection; set 0 to disable).
+        """
+        body = payload.decode("utf-8") if isinstance(payload, bytes) else payload
+        lower = {k.lower(): v for k, v in headers.items()}
+
+        timestamp = lower.get(_TS_HEADER)
+        sig_header = lower.get(_SIG_HEADER)
+        if not timestamp or not sig_header:
+            raise SignatureVerificationError(
+                "Missing X-Webhook-Timestamp or X-HostPay-Signature header"
+            )
+
+        signature = sig_header[3:] if sig_header.startswith("v1=") else sig_header
+
+        expected = hmac.new(
+            secret.encode("utf-8"),
+            f"{timestamp}.{body}".encode("utf-8"),
+            hashlib.sha256,
+        ).hexdigest()
+        if not hmac.compare_digest(expected, signature):
+            raise SignatureVerificationError("Signature mismatch")
+
+        if tolerance:
+            try:
+                age = abs(time.time() - int(timestamp))
+            except ValueError as exc:
+                raise SignatureVerificationError("Invalid timestamp") from exc
+            if age > tolerance:
+                raise SignatureVerificationError(
+                    f"Timestamp outside tolerance ({age:.0f}s > {tolerance}s)"
+                )
+
+        return HostPayObject(json.loads(body))

hostpay-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hostpay"
+version = "0.1.0"
+description = "Python SDK for the HostPay payments API"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "HostPay", email = "host.sl.co@gmail.com" }]
+keywords = ["hostpay", "payments", "wallet", "mobile-money", "escrow", "sdk"]
+dependencies = ["httpx>=0.24"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.8",
+  "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",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://hpay.host-sl.com"
+Documentation = "https://hpay.host-sl.com/docs"
+Repository = "https://github.com/HOST-SL/host_pay"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["hostpay"]

hostpay-0.1.0/tests/test_client.py

@@ -0,0 +1,64 @@
+import json
+
+import httpx
+import pytest
+
+from hostpay import AuthenticationError, HostPay, InvalidRequestError
+
+
+def _client(handler):
+    """A HostPay client whose HTTP layer is a MockTransport running `handler`."""
+    mock = httpx.MockTransport(handler)
+    http = httpx.Client(base_url="https://api.test", transport=mock)
+    return HostPay(api_key="ak-x", secret_key="sk-y", http_client=http)
+
+
+def test_auth_headers_and_path_and_body():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["api-key"] = request.headers.get("api-key")
+        seen["secret-key"] = request.headers.get("secret-key")
+        seen["body"] = json.loads(request.content)
+        return httpx.Response(201, json={"id": "usr_1", "name": "Alice"})
+
+    client = _client(handler)
+    user = client.users.create(app_user_id="u1", name="Alice", phone_number="+23279000000")
+
+    assert seen["path"] == "/api/v1/users/create/"
+    assert seen["api-key"] == "ak-x" and seen["secret-key"] == "sk-y"
+    assert seen["body"]["app_user_id"] == "u1"
+    assert user.id == "usr_1"  # attribute access on the response
+
+
+def test_idempotency_key_forwarded():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["idem"] = request.headers.get("Idempotency-Key")
+        return httpx.Response(200, json={"transaction_id": "txn_1"})
+
+    client = _client(handler)
+    client.deposits.mobile_money(wallet_id="w1", amount=100, idempotency_key="abc-123")
+    assert seen["idem"] == "abc-123"
+
+
+def test_error_mapping():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(403, json={"detail": "Invalid credentials"})
+
+    client = _client(handler)
+    with pytest.raises(AuthenticationError) as exc:
+        client.wallets.balance("w1")
+    assert exc.value.status_code == 403
+    assert "Invalid credentials" in str(exc.value)
+
+
+def test_validation_error_is_invalid_request():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(422, json={"detail": "bad amount"})
+
+    client = _client(handler)
+    with pytest.raises(InvalidRequestError):
+        client.payouts.mobile_money(wallet_id="w1", amount=-5, phone_number="+232")

hostpay-0.1.0/tests/test_webhook_signature.py

@@ -0,0 +1,70 @@
+import hashlib
+import hmac
+import json
+import time
+
+import pytest
+
+from hostpay.errors import SignatureVerificationError
+from hostpay.webhooks import Webhooks
+
+SECRET = "whsec_test_secret"
+
+
+def _sign(secret, ts, body):
+    return hmac.new(
+        secret.encode(), f"{ts}.{body}".encode(), hashlib.sha256
+    ).hexdigest()
+
+
+def _headers(ts, body, secret=SECRET, prefix="v1="):
+    return {
+        "X-Webhook-Timestamp": ts,
+        "X-HostPay-Signature": prefix + _sign(secret, ts, body),
+    }
+
+
+def test_valid_signature_parses_event():
+    body = json.dumps({"event": "deposit.completed", "data": {"id": "txn_1"}})
+    ts = str(int(time.time()))
+    evt = Webhooks.construct_event(body, _headers(ts, body), SECRET)
+    assert evt.event == "deposit.completed"
+    assert evt.data.id == "txn_1"
+
+
+def test_tampered_body_rejected():
+    ts = str(int(time.time()))
+    signed = json.dumps({"amount": 1})
+    headers = _headers(ts, signed)
+    with pytest.raises(SignatureVerificationError):
+        Webhooks.construct_event(json.dumps({"amount": 1000000}), headers, SECRET)
+
+
+def test_wrong_secret_rejected():
+    body = json.dumps({"a": 1})
+    ts = str(int(time.time()))
+    with pytest.raises(SignatureVerificationError):
+        Webhooks.construct_event(body, _headers(ts, body), "whsec_other")
+
+
+def test_expired_timestamp_rejected():
+    body = json.dumps({"a": 1})
+    ts = str(int(time.time()) - 10_000)
+    with pytest.raises(SignatureVerificationError):
+        Webhooks.construct_event(body, _headers(ts, body), SECRET, tolerance=300)
+
+
+def test_missing_headers_rejected():
+    with pytest.raises(SignatureVerificationError):
+        Webhooks.construct_event("{}", {}, SECRET)
+
+
+def test_bytes_payload_and_no_prefix_and_lowercase_headers():
+    body = json.dumps({"ok": True})
+    ts = str(int(time.time()))
+    headers = {
+        "x-webhook-timestamp": ts,
+        "x-hostpay-signature": _sign(SECRET, ts, body),  # no "v1=" prefix
+    }
+    evt = Webhooks.construct_event(body.encode("utf-8"), headers, SECRET)
+    assert evt.ok is True