clickpesa-python-sdk 0.1.0__py3-none-any.whl

clickpesa/services/billpay.py

@@ -0,0 +1,340 @@
+"""
+BillPay collection services — Order and Customer Control Numbers.
+
+Sync:  ``BillPayService``      — attach to :class:`~clickpesa.client.ClickPesaClient`.
+Async: ``AsyncBillPayService`` — attach to :class:`~clickpesa.async_client.AsyncClickPesaClient`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from ..client import ClickPesaClient
+    from ..async_client import AsyncClickPesaClient
+
+_BASE = "/third-parties/billpay"
+_BULK_LIMIT = 50
+
+BillPaymentMode = Literal["ALLOW_PARTIAL_AND_OVER_PAYMENT", "EXACT"]
+BillStatus = Literal["ACTIVE", "INACTIVE"]
+
+
+# ---------------------------------------------------------------------------
+# Sync
+# ---------------------------------------------------------------------------
+
+class BillPayService:
+    """Synchronous BillPay control-number management."""
+
+    def __init__(self, client: "ClickPesaClient") -> None:
+        self._c = client
+
+    def create_order_control_number(
+        self,
+        bill_reference: str | None = None,
+        amount: float | None = None,
+        description: str | None = None,
+        payment_mode: BillPaymentMode | None = None,
+    ) -> dict[str, Any]:
+        """
+        Generate a one-time order control number.
+
+        All fields are optional.  If ``bill_reference`` is omitted the API
+        auto-generates one.  ``payment_mode`` is only applied when ``amount``
+        is also set.
+
+        Args:
+            bill_reference: Custom alphanumeric reference (must be unique).
+            amount:         Bill amount.
+            description:    Human-readable bill description.
+            payment_mode:   ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` (default) or ``"EXACT"``.
+
+        Returns:
+            Dict with ``billPayNumber``, ``billDescription``, ``billAmount``, etc.
+        """
+        payload: dict[str, Any] = {}
+        if bill_reference is not None:
+            payload["billReference"] = bill_reference
+        if amount is not None:
+            payload["billAmount"] = amount
+        if description is not None:
+            payload["billDescription"] = description
+        if payment_mode is not None:
+            payload["billPaymentMode"] = payment_mode
+        return self._c.request("POST", f"{_BASE}/create-order-control-number", json=payload)
+
+    def create_customer_control_number(
+        self,
+        customer_name: str,
+        phone: str | None = None,
+        email: str | None = None,
+        bill_reference: str | None = None,
+        amount: float | None = None,
+        description: str | None = None,
+        payment_mode: BillPaymentMode | None = None,
+    ) -> dict[str, Any]:
+        """
+        Generate a persistent control number tied to a specific customer.
+
+        Either ``phone`` or ``email`` (or both) must be supplied.
+
+        Args:
+            customer_name:  Customer's full name.
+            phone:          Phone with country code, no ``+`` (e.g. ``"255712345678"``).
+            email:          Customer email address.
+            bill_reference: Custom alphanumeric reference (must be unique).
+            amount:         Bill amount.
+            description:    Human-readable bill description.
+            payment_mode:   ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` (default) or ``"EXACT"``.
+
+        Returns:
+            Dict with ``billPayNumber``, ``billCustomerName``, ``billAmount``, etc.
+        """
+        if phone is None and email is None:
+            raise ValueError("At least one of 'phone' or 'email' must be provided.")
+
+        payload: dict[str, Any] = {"customerName": customer_name}
+        if phone is not None:
+            payload["customerPhone"] = phone
+        if email is not None:
+            payload["customerEmail"] = email
+        if bill_reference is not None:
+            payload["billReference"] = bill_reference
+        if amount is not None:
+            payload["billAmount"] = amount
+        if description is not None:
+            payload["billDescription"] = description
+        if payment_mode is not None:
+            payload["billPaymentMode"] = payment_mode
+        return self._c.request("POST", f"{_BASE}/create-customer-control-number", json=payload)
+
+    def bulk_create_order_numbers(
+        self,
+        control_numbers: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """
+        Bulk-create up to 50 order control numbers in a single request.
+
+        Each item may contain: ``billReference``, ``billAmount``,
+        ``billDescription``, ``billPaymentMode``.
+
+        Args:
+            control_numbers: List of order dicts (1–50 items).
+
+        Returns:
+            Dict with ``billPayNumbers``, ``created``, ``failed``, and
+            optional ``errors`` list.
+
+        Raises:
+            ValueError: If the list exceeds 50 items or is empty.
+        """
+        if not control_numbers:
+            raise ValueError("control_numbers must contain at least 1 item.")
+        if len(control_numbers) > _BULK_LIMIT:
+            raise ValueError(f"ClickPesa bulk limit is {_BULK_LIMIT} items per request.")
+        return self._c.request(
+            "POST",
+            f"{_BASE}/bulk-create-order-control-numbers",
+            json={"controlNumbers": control_numbers},
+        )
+
+    def bulk_create_customer_numbers(
+        self,
+        control_numbers: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        """
+        Bulk-create up to 50 customer control numbers in a single request.
+
+        Each item must contain ``customerName`` and at least one of
+        ``customerPhone`` / ``customerEmail``.  Optional fields:
+        ``billReference``, ``billAmount``, ``billDescription``, ``billPaymentMode``.
+
+        Args:
+            control_numbers: List of customer dicts (1–50 items).
+
+        Returns:
+            Dict with ``billPayNumbers``, ``created``, ``failed``, and
+            optional ``errors`` list.
+
+        Raises:
+            ValueError: If the list exceeds 50 items or is empty.
+        """
+        if not control_numbers:
+            raise ValueError("control_numbers must contain at least 1 item.")
+        if len(control_numbers) > _BULK_LIMIT:
+            raise ValueError(f"ClickPesa bulk limit is {_BULK_LIMIT} items per request.")
+        return self._c.request(
+            "POST",
+            f"{_BASE}/bulk-create-customer-control-numbers",
+            json={"controlNumbers": control_numbers},
+        )
+
+    def get_details(self, bill_pay_number: str) -> dict[str, Any]:
+        """
+        Query details of a specific control number.
+
+        Returns:
+            Dict with ``billPayNumber``, ``billDescription``, ``billAmount``,
+            ``billPaymentMode``, and ``billCustomerName``.
+        """
+        return self._c.request("GET", f"{_BASE}/{bill_pay_number}")
+
+    def update_reference(
+        self,
+        bill_pay_number: str,
+        amount: float | None = None,
+        description: str | None = None,
+        status: BillStatus | None = None,
+        payment_mode: BillPaymentMode | None = None,
+    ) -> dict[str, Any]:
+        """
+        Partially update a BillPay reference.
+
+        At least one argument besides ``bill_pay_number`` must be provided.
+
+        Args:
+            bill_pay_number: The BillPay number to update.
+            amount:          New bill amount (positive, max 2 decimal places).
+            description:     New description (max 500 characters).
+            status:          ``"ACTIVE"`` or ``"INACTIVE"``.
+            payment_mode:    ``"ALLOW_PARTIAL_AND_OVER_PAYMENT"`` or ``"EXACT"``.
+
+        Returns:
+            Updated BillPay object.
+        """
+        data: dict[str, Any] = {}
+        if amount is not None:
+            data["billAmount"] = amount
+        if description is not None:
+            data["billDescription"] = description
+        if status is not None:
+            data["billStatus"] = status
+        if payment_mode is not None:
+            data["billPaymentMode"] = payment_mode
+        if not data:
+            raise ValueError("At least one field must be provided to update.")
+        return self._c.request("PATCH", f"{_BASE}/{bill_pay_number}", json=data)
+
+    def update_status(self, bill_pay_number: str, status: BillStatus) -> dict[str, Any]:
+        """
+        Convenience method to activate or deactivate a control number.
+
+        Args:
+            bill_pay_number: The BillPay number to update.
+            status:          ``"ACTIVE"`` or ``"INACTIVE"``.
+        """
+        return self.update_reference(bill_pay_number, status=status)
+
+
+# ---------------------------------------------------------------------------
+# Async
+# ---------------------------------------------------------------------------
+
+class AsyncBillPayService:
+    """Asynchronous BillPay control-number management (mirrors :class:`BillPayService`)."""
+
+    def __init__(self, client: "AsyncClickPesaClient") -> None:
+        self._c = client
+
+    async def create_order_control_number(
+        self,
+        bill_reference: str | None = None,
+        amount: float | None = None,
+        description: str | None = None,
+        payment_mode: BillPaymentMode | None = None,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if bill_reference is not None:
+            payload["billReference"] = bill_reference
+        if amount is not None:
+            payload["billAmount"] = amount
+        if description is not None:
+            payload["billDescription"] = description
+        if payment_mode is not None:
+            payload["billPaymentMode"] = payment_mode
+        return await self._c.request("POST", f"{_BASE}/create-order-control-number", json=payload)
+
+    async def create_customer_control_number(
+        self,
+        customer_name: str,
+        phone: str | None = None,
+        email: str | None = None,
+        bill_reference: str | None = None,
+        amount: float | None = None,
+        description: str | None = None,
+        payment_mode: BillPaymentMode | None = None,
+    ) -> dict[str, Any]:
+        if phone is None and email is None:
+            raise ValueError("At least one of 'phone' or 'email' must be provided.")
+        payload: dict[str, Any] = {"customerName": customer_name}
+        if phone is not None:
+            payload["customerPhone"] = phone
+        if email is not None:
+            payload["customerEmail"] = email
+        if bill_reference is not None:
+            payload["billReference"] = bill_reference
+        if amount is not None:
+            payload["billAmount"] = amount
+        if description is not None:
+            payload["billDescription"] = description
+        if payment_mode is not None:
+            payload["billPaymentMode"] = payment_mode
+        return await self._c.request(
+            "POST", f"{_BASE}/create-customer-control-number", json=payload
+        )
+
+    async def bulk_create_order_numbers(
+        self,
+        control_numbers: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        if not control_numbers:
+            raise ValueError("control_numbers must contain at least 1 item.")
+        if len(control_numbers) > _BULK_LIMIT:
+            raise ValueError(f"ClickPesa bulk limit is {_BULK_LIMIT} items per request.")
+        return await self._c.request(
+            "POST",
+            f"{_BASE}/bulk-create-order-control-numbers",
+            json={"controlNumbers": control_numbers},
+        )
+
+    async def bulk_create_customer_numbers(
+        self,
+        control_numbers: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        if not control_numbers:
+            raise ValueError("control_numbers must contain at least 1 item.")
+        if len(control_numbers) > _BULK_LIMIT:
+            raise ValueError(f"ClickPesa bulk limit is {_BULK_LIMIT} items per request.")
+        return await self._c.request(
+            "POST",
+            f"{_BASE}/bulk-create-customer-control-numbers",
+            json={"controlNumbers": control_numbers},
+        )
+
+    async def get_details(self, bill_pay_number: str) -> dict[str, Any]:
+        return await self._c.request("GET", f"{_BASE}/{bill_pay_number}")
+
+    async def update_reference(
+        self,
+        bill_pay_number: str,
+        amount: float | None = None,
+        description: str | None = None,
+        status: BillStatus | None = None,
+        payment_mode: BillPaymentMode | None = None,
+    ) -> dict[str, Any]:
+        data: dict[str, Any] = {}
+        if amount is not None:
+            data["billAmount"] = amount
+        if description is not None:
+            data["billDescription"] = description
+        if status is not None:
+            data["billStatus"] = status
+        if payment_mode is not None:
+            data["billPaymentMode"] = payment_mode
+        if not data:
+            raise ValueError("At least one field must be provided to update.")
+        return await self._c.request("PATCH", f"{_BASE}/{bill_pay_number}", json=data)
+
+    async def update_status(self, bill_pay_number: str, status: BillStatus) -> dict[str, Any]:
+        return await self.update_reference(bill_pay_number, status=status)

clickpesa/services/exchange.py

@@ -0,0 +1,74 @@
+"""
+Exchange rate services.
+
+Sync:  ``ExchangeService``      — attach to :class:`~clickpesa.client.ClickPesaClient`.
+Async: ``AsyncExchangeService`` — attach to :class:`~clickpesa.async_client.AsyncClickPesaClient`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..client import ClickPesaClient
+    from ..async_client import AsyncClickPesaClient
+
+_ENDPOINT = "/third-parties/exchange-rates/all"
+
+
+# ---------------------------------------------------------------------------
+# Sync
+# ---------------------------------------------------------------------------
+
+class ExchangeService:
+    """Synchronous exchange rate methods."""
+
+    def __init__(self, client: "ClickPesaClient") -> None:
+        self._c = client
+
+    def get_rates(
+        self,
+        source: str | None = None,
+        target: str | None = None,
+    ) -> list[dict[str, Any]]:
+        """
+        Fetch the latest exchange rates.
+
+        Args:
+            source: ISO 4217 source currency code (e.g. ``"USD"``).
+                    When omitted all available source currencies are returned.
+            target: ISO 4217 target currency code (e.g. ``"TZS"``).
+                    When omitted all available target currencies are returned.
+
+        Returns:
+            List of ``{"source": "…", "target": "…", "rate": 2510, "date": "…"}`` dicts.
+        """
+        params: dict[str, Any] = {}
+        if source is not None:
+            params["source"] = source
+        if target is not None:
+            params["target"] = target
+        return self._c.request("GET", _ENDPOINT, params=params)
+
+
+# ---------------------------------------------------------------------------
+# Async
+# ---------------------------------------------------------------------------
+
+class AsyncExchangeService:
+    """Asynchronous exchange rate methods (mirrors :class:`ExchangeService`)."""
+
+    def __init__(self, client: "AsyncClickPesaClient") -> None:
+        self._c = client
+
+    async def get_rates(
+        self,
+        source: str | None = None,
+        target: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {}
+        if source is not None:
+            params["source"] = source
+        if target is not None:
+            params["target"] = target
+        return await self._c.request("GET", _ENDPOINT, params=params)

clickpesa/services/links.py

@@ -0,0 +1,169 @@
+"""
+Hosted link generation services — Checkout and Payout Links.
+
+Sync:  ``LinkService``      — attach to :class:`~clickpesa.client.ClickPesaClient`.
+Async: ``AsyncLinkService`` — attach to :class:`~clickpesa.async_client.AsyncClickPesaClient`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from ..client import ClickPesaClient
+    from ..async_client import AsyncClickPesaClient
+
+_CHECKOUT = "/third-parties/checkout-link/generate-checkout-url"
+_PAYOUT = "/third-parties/payout-link/generate-payout-url"
+
+OrderCurrency = Literal["TZS", "USD"]
+
+
+# ---------------------------------------------------------------------------
+# Sync
+# ---------------------------------------------------------------------------
+
+class LinkService:
+    """Synchronous hosted-link generation methods."""
+
+    def __init__(self, client: "ClickPesaClient") -> None:
+        self._c = client
+
+    def generate_checkout(
+        self,
+        order_id: str,
+        order_currency: OrderCurrency,
+        total_price: str | None = None,
+        order_items: list[dict[str, Any]] | None = None,
+        customer_name: str | None = None,
+        customer_email: str | None = None,
+        customer_phone: str | None = None,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Generate a hosted checkout payment page.
+
+        Supply **either** ``total_price`` **or** ``order_items`` — not both.
+
+        Args:
+            order_id:       Unique alphanumeric order reference.
+            order_currency: ``"TZS"`` or ``"USD"``.
+            total_price:    Order total as a string (Option 1).
+            order_items:    List of ``{"name": …, "price": …, "quantity": …}``
+                            dicts (Option 2).
+            customer_name:  Pre-fill customer name on the checkout page.
+            customer_email: Pre-fill customer email.
+            customer_phone: Customer phone with country code, no ``+``.
+            description:    Order description shown on the checkout page.
+
+        Returns:
+            Dict with ``checkoutLink`` (URL string) and ``clientId``.
+
+        Raises:
+            ValueError: If neither or both of ``total_price`` / ``order_items``
+                        are provided.
+        """
+        if total_price is None and order_items is None:
+            raise ValueError("Provide either 'total_price' or 'order_items'.")
+        if total_price is not None and order_items is not None:
+            raise ValueError("Provide either 'total_price' or 'order_items', not both.")
+
+        payload: dict[str, Any] = {
+            "orderReference": order_id,
+            "orderCurrency": order_currency,
+        }
+        if total_price is not None:
+            payload["totalPrice"] = str(total_price)
+        if order_items is not None:
+            payload["orderItems"] = order_items
+        if customer_name is not None:
+            payload["customerName"] = customer_name
+        if customer_email is not None:
+            payload["customerEmail"] = customer_email
+        if customer_phone is not None:
+            payload["customerPhone"] = customer_phone
+        if description is not None:
+            payload["description"] = description
+
+        return self._c.request("POST", _CHECKOUT, json=payload)
+
+    def generate_payout(
+        self,
+        amount: str,
+        order_id: str,
+    ) -> dict[str, Any]:
+        """
+        Generate a hosted payout link.
+
+        The recipient uses the link to enter their own bank / mobile-money
+        details without you needing to collect them yourself.
+
+        Args:
+            amount:   Payout amount.
+            order_id: Unique alphanumeric order reference.
+
+        Returns:
+            Dict with ``payoutLink`` (URL string) and ``clientId``.
+        """
+        payload: dict[str, Any] = {
+            "amount": str(amount),
+            "orderReference": order_id,
+        }
+        return self._c.request("POST", _PAYOUT, json=payload)
+
+
+# ---------------------------------------------------------------------------
+# Async
+# ---------------------------------------------------------------------------
+
+class AsyncLinkService:
+    """Asynchronous hosted-link generation methods (mirrors :class:`LinkService`)."""
+
+    def __init__(self, client: "AsyncClickPesaClient") -> None:
+        self._c = client
+
+    async def generate_checkout(
+        self,
+        order_id: str,
+        order_currency: OrderCurrency,
+        total_price: str | None = None,
+        order_items: list[dict[str, Any]] | None = None,
+        customer_name: str | None = None,
+        customer_email: str | None = None,
+        customer_phone: str | None = None,
+        description: str | None = None,
+    ) -> dict[str, Any]:
+        if total_price is None and order_items is None:
+            raise ValueError("Provide either 'total_price' or 'order_items'.")
+        if total_price is not None and order_items is not None:
+            raise ValueError("Provide either 'total_price' or 'order_items', not both.")
+
+        payload: dict[str, Any] = {
+            "orderReference": order_id,
+            "orderCurrency": order_currency,
+        }
+        if total_price is not None:
+            payload["totalPrice"] = str(total_price)
+        if order_items is not None:
+            payload["orderItems"] = order_items
+        if customer_name is not None:
+            payload["customerName"] = customer_name
+        if customer_email is not None:
+            payload["customerEmail"] = customer_email
+        if customer_phone is not None:
+            payload["customerPhone"] = customer_phone
+        if description is not None:
+            payload["description"] = description
+
+        return await self._c.request("POST", _CHECKOUT, json=payload)
+
+    async def generate_payout(
+        self,
+        amount: str,
+        order_id: str,
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "amount": str(amount),
+            "orderReference": order_id,
+        }
+        return await self._c.request("POST", _PAYOUT, json=payload)