cinetpay-python 0.1.0__py3-none-any.whl

cinetpay/__init__.py

@@ -0,0 +1,175 @@
+"""CinetPay Python SDK — payments and mobile money transfers in Africa.
+
+Usage::
+
+    from cinetpay import CinetPayClient, ClientConfig, CountryCredentials
+
+    client = CinetPayClient(ClientConfig(
+        credentials={
+            "CI": CountryCredentials(api_key="sk_test_...", api_password="..."),
+        },
+    ))
+
+    # Initialize a payment
+    payment = client.payment.initialize(request, "CI")
+
+    # Check payment status
+    status = client.payment.get_status(payment.payment_token, "CI")
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+# ---------------------------------------------------------------------------
+# Main clients
+# ---------------------------------------------------------------------------
+from cinetpay.async_client import AsyncCinetPayClient
+from cinetpay.client import CinetPayClient
+
+# ---------------------------------------------------------------------------
+# Configuration types
+# ---------------------------------------------------------------------------
+from cinetpay.types.config import (
+    API_KEY_PREFIX_LIVE,
+    API_KEY_PREFIX_TEST,
+    AsyncTokenStoreProtocol,
+    ClientConfig,
+    CountryCredentials,
+    DEFAULT_BASE_URL,
+    DEFAULT_TIMEOUT,
+    DEFAULT_TOKEN_TTL,
+    PRODUCTION_BASE_URL,
+    TokenStoreProtocol,
+)
+
+# ---------------------------------------------------------------------------
+# Domain types
+# ---------------------------------------------------------------------------
+from cinetpay.types.balance import Balance
+from cinetpay.types.payment import (
+    PaymentDetails,
+    PaymentRequest,
+    PaymentResponse,
+    PaymentStatus,
+    PaymentStatusUser,
+)
+from cinetpay.types.transfer import (
+    TransferRequest,
+    TransferResponse,
+    TransferStatus,
+    TransferStatusUser,
+)
+from cinetpay.types.webhook import WebhookPayload, WebhookUser
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+from cinetpay.constants import (
+    API_CODES,
+    CHANNELS,
+    COUNTRY_CODES,
+    CURRENCIES,
+    PAYMENT_METHODS,
+    PAYMENT_METHODS_BY_COUNTRY,
+    TRANSACTION_STATUSES,
+    Channel,
+    CountryCode,
+    Currency,
+    PaymentMethod,
+    TransactionStatus,
+    is_final_status,
+)
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+from cinetpay.errors import (
+    ApiError,
+    AuthenticationError,
+    CinetPayError,
+    NetworkError,
+    TimeoutError,
+)
+
+# ---------------------------------------------------------------------------
+# Validation
+# ---------------------------------------------------------------------------
+from cinetpay.validation import ValidationError
+
+# ---------------------------------------------------------------------------
+# Webhooks
+# ---------------------------------------------------------------------------
+from cinetpay.webhooks.notification import parse_notification, verify_notification
+
+# ---------------------------------------------------------------------------
+# Logger
+# ---------------------------------------------------------------------------
+from cinetpay.logger import LoggerProtocol, NoopLogger, StandardLibLogger
+
+# ---------------------------------------------------------------------------
+# Token store
+# ---------------------------------------------------------------------------
+from cinetpay.auth.token_store import MemoryTokenStore
+
+__all__ = [
+    # Version
+    "__version__",
+    # Clients
+    "AsyncCinetPayClient",
+    "CinetPayClient",
+    # Config types
+    "API_KEY_PREFIX_LIVE",
+    "API_KEY_PREFIX_TEST",
+    "AsyncTokenStoreProtocol",
+    "ClientConfig",
+    "CountryCredentials",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT",
+    "DEFAULT_TOKEN_TTL",
+    "PRODUCTION_BASE_URL",
+    "TokenStoreProtocol",
+    # Domain types
+    "Balance",
+    "PaymentDetails",
+    "PaymentRequest",
+    "PaymentResponse",
+    "PaymentStatus",
+    "PaymentStatusUser",
+    "TransferRequest",
+    "TransferResponse",
+    "TransferStatus",
+    "TransferStatusUser",
+    "WebhookPayload",
+    "WebhookUser",
+    # Constants
+    "API_CODES",
+    "CHANNELS",
+    "COUNTRY_CODES",
+    "CURRENCIES",
+    "Channel",
+    "CountryCode",
+    "Currency",
+    "PAYMENT_METHODS",
+    "PAYMENT_METHODS_BY_COUNTRY",
+    "PaymentMethod",
+    "TRANSACTION_STATUSES",
+    "TransactionStatus",
+    "is_final_status",
+    # Errors
+    "ApiError",
+    "AuthenticationError",
+    "CinetPayError",
+    "NetworkError",
+    "TimeoutError",
+    "ValidationError",
+    # Webhooks
+    "parse_notification",
+    "verify_notification",
+    # Logger
+    "LoggerProtocol",
+    "NoopLogger",
+    "StandardLibLogger",
+    # Token store
+    "MemoryTokenStore",
+]

cinetpay/api/__init__.py

@@ -0,0 +1,17 @@
+"""API modules — payment, transfer, balance (sync and async)."""
+
+from cinetpay.api.async_balance import AsyncBalanceApi
+from cinetpay.api.async_payment import AsyncPaymentApi
+from cinetpay.api.async_transfer import AsyncTransferApi
+from cinetpay.api.balance import BalanceApi
+from cinetpay.api.payment import PaymentApi
+from cinetpay.api.transfer import TransferApi
+
+__all__ = [
+    "AsyncBalanceApi",
+    "AsyncPaymentApi",
+    "AsyncTransferApi",
+    "BalanceApi",
+    "PaymentApi",
+    "TransferApi",
+]

cinetpay/api/async_balance.py

@@ -0,0 +1,70 @@
+"""Asynchronous balance API — retrieve merchant account balance."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cinetpay.auth.async_authenticator import AsyncAuthenticator
+from cinetpay.errors.api_error import ApiError
+from cinetpay.http.async_http_client import AsyncHttpClient
+from cinetpay.types.balance import Balance, to_balance
+
+
+class AsyncBalanceApi:
+    """Async CinetPay merchant balance API.
+
+    Accessible via ``client.balance``.
+
+    Example::
+
+        balance = await client.balance.get("CI")
+        print(balance.available_balance)  # "249711.74"
+    """
+
+    def __init__(
+        self,
+        http_client: AsyncHttpClient,
+        authenticators: dict[str, AsyncAuthenticator],
+    ) -> None:
+        self._http_client = http_client
+        self._authenticators = authenticators
+
+    async def get(self, country: str) -> Balance:
+        """Retrieve the available balance for a merchant account.
+
+        Args:
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Balance with available amount and currency.
+
+        Raises:
+            ApiError: If authentication fails.
+            TypeError: If the country is not configured.
+        """
+        auth = self._resolve_authenticator(country)
+
+        try:
+            token = await auth.get_token()
+            raw: dict[str, Any] = await self._http_client.get("/v1/balances", token)
+            return to_balance(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = await auth.force_refresh()
+                raw = await self._http_client.get("/v1/balances", token)
+                return to_balance(raw)
+            raise
+
+    def _resolve_authenticator(self, country: str) -> AsyncAuthenticator:
+        key = country.upper()
+        auth = self._authenticators.get(key)
+        if auth is None:
+            available = ", ".join(self._authenticators.keys())
+            raise TypeError(
+                f'No credentials configured for country "{key}". Available: {available}'
+            )
+        return auth
+
+
+def _is_token_expired(error: ApiError) -> bool:
+    return error.api_code == 1003 or error.api_status == "EXPIRED_TOKEN"

cinetpay/api/async_payment.py

@@ -0,0 +1,118 @@
+"""Asynchronous payment API — initialize payments and check status."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from cinetpay.auth.async_authenticator import AsyncAuthenticator
+from cinetpay.errors.api_error import ApiError
+from cinetpay.http.async_http_client import AsyncHttpClient
+from cinetpay.types.payment import (
+    PaymentRequest,
+    PaymentResponse,
+    PaymentStatus,
+    serialize_payment_request,
+    to_payment_response,
+    to_payment_status,
+)
+from cinetpay.validation import validate_payment_request
+
+
+class AsyncPaymentApi:
+    """Async CinetPay web payment API.
+
+    Accessible via ``client.payment``.
+
+    Example::
+
+        payment = await client.payment.initialize(request, "CI")
+        status = await client.payment.get_status(payment.payment_token, "CI")
+    """
+
+    def __init__(
+        self,
+        http_client: AsyncHttpClient,
+        authenticators: dict[str, AsyncAuthenticator],
+    ) -> None:
+        self._http_client = http_client
+        self._authenticators = authenticators
+
+    async def initialize(
+        self,
+        request: PaymentRequest,
+        country: str,
+    ) -> PaymentResponse:
+        """Initialize a web payment transaction.
+
+        Args:
+            request: Payment parameters (amount, currency, URLs, customer, etc.).
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Response containing ``payment_url`` (redirect) and ``payment_token`` (status check).
+
+        Raises:
+            ApiError: If the API returns an error (e.g. TRANSACTION_EXIST).
+            ValidationError: If a request field is invalid.
+            TypeError: If the country is not configured.
+        """
+        validate_payment_request(request)
+        auth = self._resolve_authenticator(country)
+        body = serialize_payment_request(request)
+
+        try:
+            token = await auth.get_token()
+            raw: dict[str, Any] = await self._http_client.post("/v1/payment", body, token)
+            return to_payment_response(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = await auth.force_refresh()
+                raw = await self._http_client.post("/v1/payment", body, token)
+                return to_payment_response(raw)
+            raise
+
+    async def get_status(
+        self,
+        identifier: str,
+        country: str,
+    ) -> PaymentStatus:
+        """Retrieve the current status of a payment.
+
+        Args:
+            identifier: ``payment_token``, ``transaction_id``, or ``merchant_transaction_id``.
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Transaction status with user information.
+
+        Raises:
+            ApiError: If the transaction is not found (NOT_FOUND).
+        """
+        auth = self._resolve_authenticator(country)
+        path = f"/v1/payment/{quote(identifier, safe='')}"
+
+        try:
+            token = await auth.get_token()
+            raw: dict[str, Any] = await self._http_client.get(path, token)
+            return to_payment_status(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = await auth.force_refresh()
+                raw = await self._http_client.get(path, token)
+                return to_payment_status(raw)
+            raise
+
+    def _resolve_authenticator(self, country: str) -> AsyncAuthenticator:
+        key = country.upper()
+        auth = self._authenticators.get(key)
+        if auth is None:
+            available = ", ".join(self._authenticators.keys())
+            raise TypeError(
+                f'No credentials configured for country "{key}". Available: {available}'
+            )
+        return auth
+
+
+def _is_token_expired(error: ApiError) -> bool:
+    return error.api_code == 1003 or error.api_status == "EXPIRED_TOKEN"

cinetpay/api/async_transfer.py

@@ -0,0 +1,118 @@
+"""Asynchronous transfer API — create transfers and check status."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from cinetpay.auth.async_authenticator import AsyncAuthenticator
+from cinetpay.errors.api_error import ApiError
+from cinetpay.http.async_http_client import AsyncHttpClient
+from cinetpay.types.transfer import (
+    TransferRequest,
+    TransferResponse,
+    TransferStatus,
+    serialize_transfer_request,
+    to_transfer_response,
+    to_transfer_status,
+)
+from cinetpay.validation import validate_transfer_request
+
+
+class AsyncTransferApi:
+    """Async CinetPay money transfer API.
+
+    Accessible via ``client.transfer``.
+
+    Example::
+
+        transfer = await client.transfer.create(request, "CI")
+        status = await client.transfer.get_status(transfer.transaction_id, "CI")
+    """
+
+    def __init__(
+        self,
+        http_client: AsyncHttpClient,
+        authenticators: dict[str, AsyncAuthenticator],
+    ) -> None:
+        self._http_client = http_client
+        self._authenticators = authenticators
+
+    async def create(
+        self,
+        request: TransferRequest,
+        country: str,
+    ) -> TransferResponse:
+        """Create a money transfer to a mobile money number.
+
+        Args:
+            request: Transfer parameters (amount, currency, phone, operator, etc.).
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Response containing initial status and transaction identifiers.
+
+        Raises:
+            ApiError: If the API returns an error (e.g. INSUFFICIENT_BALANCE).
+            ValidationError: If a request field is invalid.
+            TypeError: If the country is not configured.
+        """
+        validate_transfer_request(request)
+        auth = self._resolve_authenticator(country)
+        body = serialize_transfer_request(request)
+
+        try:
+            token = await auth.get_token()
+            raw: dict[str, Any] = await self._http_client.post("/v1/transfer", body, token)
+            return to_transfer_response(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = await auth.force_refresh()
+                raw = await self._http_client.post("/v1/transfer", body, token)
+                return to_transfer_response(raw)
+            raise
+
+    async def get_status(
+        self,
+        transaction_id: str,
+        country: str,
+    ) -> TransferStatus:
+        """Retrieve the current status of a transfer.
+
+        Args:
+            transaction_id: CinetPay transaction ID or ``merchant_transaction_id``.
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Transfer status with recipient information.
+
+        Raises:
+            ApiError: If the transaction is not found (NOT_FOUND).
+        """
+        auth = self._resolve_authenticator(country)
+        path = f"/v1/transfer/{quote(transaction_id, safe='')}"
+
+        try:
+            token = await auth.get_token()
+            raw: dict[str, Any] = await self._http_client.get(path, token)
+            return to_transfer_status(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = await auth.force_refresh()
+                raw = await self._http_client.get(path, token)
+                return to_transfer_status(raw)
+            raise
+
+    def _resolve_authenticator(self, country: str) -> AsyncAuthenticator:
+        key = country.upper()
+        auth = self._authenticators.get(key)
+        if auth is None:
+            available = ", ".join(self._authenticators.keys())
+            raise TypeError(
+                f'No credentials configured for country "{key}". Available: {available}'
+            )
+        return auth
+
+
+def _is_token_expired(error: ApiError) -> bool:
+    return error.api_code == 1003 or error.api_status == "EXPIRED_TOKEN"

cinetpay/api/balance.py

@@ -0,0 +1,70 @@
+"""Synchronous balance API — retrieve merchant account balance."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from cinetpay.auth.authenticator import Authenticator
+from cinetpay.errors.api_error import ApiError
+from cinetpay.http.http_client import HttpClient
+from cinetpay.types.balance import Balance, to_balance
+
+
+class BalanceApi:
+    """CinetPay merchant balance API.
+
+    Accessible via ``client.balance``.
+
+    Example::
+
+        balance = client.balance.get("CI")
+        print(balance.available_balance)  # "249711.74"
+    """
+
+    def __init__(
+        self,
+        http_client: HttpClient,
+        authenticators: dict[str, Authenticator],
+    ) -> None:
+        self._http_client = http_client
+        self._authenticators = authenticators
+
+    def get(self, country: str) -> Balance:
+        """Retrieve the available balance for a merchant account.
+
+        Args:
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Balance with available amount and currency.
+
+        Raises:
+            ApiError: If authentication fails.
+            TypeError: If the country is not configured.
+        """
+        auth = self._resolve_authenticator(country)
+
+        try:
+            token = auth.get_token()
+            raw: dict[str, Any] = self._http_client.get("/v1/balances", token)
+            return to_balance(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = auth.force_refresh()
+                raw = self._http_client.get("/v1/balances", token)
+                return to_balance(raw)
+            raise
+
+    def _resolve_authenticator(self, country: str) -> Authenticator:
+        key = country.upper()
+        auth = self._authenticators.get(key)
+        if auth is None:
+            available = ", ".join(self._authenticators.keys())
+            raise TypeError(
+                f'No credentials configured for country "{key}". Available: {available}'
+            )
+        return auth
+
+
+def _is_token_expired(error: ApiError) -> bool:
+    return error.api_code == 1003 or error.api_status == "EXPIRED_TOKEN"

cinetpay/api/payment.py

@@ -0,0 +1,118 @@
+"""Synchronous payment API — initialize payments and check status."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+from cinetpay.auth.authenticator import Authenticator
+from cinetpay.errors.api_error import ApiError
+from cinetpay.http.http_client import HttpClient
+from cinetpay.types.payment import (
+    PaymentRequest,
+    PaymentResponse,
+    PaymentStatus,
+    serialize_payment_request,
+    to_payment_response,
+    to_payment_status,
+)
+from cinetpay.validation import validate_payment_request
+
+
+class PaymentApi:
+    """CinetPay web payment API.
+
+    Accessible via ``client.payment``.
+
+    Example::
+
+        payment = client.payment.initialize(request, "CI")
+        status = client.payment.get_status(payment.payment_token, "CI")
+    """
+
+    def __init__(
+        self,
+        http_client: HttpClient,
+        authenticators: dict[str, Authenticator],
+    ) -> None:
+        self._http_client = http_client
+        self._authenticators = authenticators
+
+    def initialize(
+        self,
+        request: PaymentRequest,
+        country: str,
+    ) -> PaymentResponse:
+        """Initialize a web payment transaction.
+
+        Args:
+            request: Payment parameters (amount, currency, URLs, customer, etc.).
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Response containing ``payment_url`` (redirect) and ``payment_token`` (status check).
+
+        Raises:
+            ApiError: If the API returns an error (e.g. TRANSACTION_EXIST).
+            ValidationError: If a request field is invalid.
+            TypeError: If the country is not configured.
+        """
+        validate_payment_request(request)
+        auth = self._resolve_authenticator(country)
+        body = serialize_payment_request(request)
+
+        try:
+            token = auth.get_token()
+            raw: dict[str, Any] = self._http_client.post("/v1/payment", body, token)
+            return to_payment_response(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = auth.force_refresh()
+                raw = self._http_client.post("/v1/payment", body, token)
+                return to_payment_response(raw)
+            raise
+
+    def get_status(
+        self,
+        identifier: str,
+        country: str,
+    ) -> PaymentStatus:
+        """Retrieve the current status of a payment.
+
+        Args:
+            identifier: ``payment_token``, ``transaction_id``, or ``merchant_transaction_id``.
+            country: ISO country code (e.g. ``"CI"``, ``"SN"``).
+
+        Returns:
+            Transaction status with user information.
+
+        Raises:
+            ApiError: If the transaction is not found (NOT_FOUND).
+        """
+        auth = self._resolve_authenticator(country)
+        path = f"/v1/payment/{quote(identifier, safe='')}"
+
+        try:
+            token = auth.get_token()
+            raw: dict[str, Any] = self._http_client.get(path, token)
+            return to_payment_status(raw)
+        except ApiError as exc:
+            if _is_token_expired(exc):
+                token = auth.force_refresh()
+                raw = self._http_client.get(path, token)
+                return to_payment_status(raw)
+            raise
+
+    def _resolve_authenticator(self, country: str) -> Authenticator:
+        key = country.upper()
+        auth = self._authenticators.get(key)
+        if auth is None:
+            available = ", ".join(self._authenticators.keys())
+            raise TypeError(
+                f'No credentials configured for country "{key}". Available: {available}'
+            )
+        return auth
+
+
+def _is_token_expired(error: ApiError) -> bool:
+    return error.api_code == 1003 or error.api_status == "EXPIRED_TOKEN"