finopal-py-sdk 0.1.0__py3-none-any.whl

finopal/__init__.py

@@ -0,0 +1,106 @@
+"""FinoPal Python SDK — a friendly client for the FinoPal payment gateway.
+
+Quick start::
+
+    from finopal import FinoPal, Config
+
+    finopal = FinoPal(Config(merchant_id="fino-xxxx-xxxx-xxxx-xxxx", sandbox=True))
+
+    payment = finopal.payments.create({
+        "amount": 1_100,                                  # Rials
+        "callback_url": "https://shop.example.com/callback",
+        "order_id": "ORD-1001",
+    })
+    print(payment.payment_url)
+
+    # ... buyer returns to callback_url ...
+
+    from finopal import parse_callback
+
+    cb = parse_callback(request.args)
+    if cb.is_success:
+        result = finopal.verifications.verify({
+            "authority": cb.authority,
+            "amount": 1_100,
+        })
+        print(result.ref_id)
+
+Docs: https://finopal.ir/docs
+"""
+
+from finopal.errors import (
+    ApiError,
+    FinoPalError,
+    FinoPalException,
+    TransportError,
+    ValidationError,
+)
+from finopal.finopal import FinoPal
+from finopal.http import CallableTransport, RequestsTransport, Transport
+from finopal.models import (
+    ApiResponse,
+    FeeResponse,
+    InquiryResponse,
+    PaymentRequestResponse,
+    ReverseResponse,
+    VerificationResponse,
+)
+from finopal.utils import (
+    MAX_AMOUNT_RIAL,
+    MIN_AMOUNT_RIAL,
+    CallbackResult,
+    CallbackStatus,
+    Config,
+    Currency,
+    FeeType,
+    ResultCode,
+    TransactionStatus,
+    Validator,
+    describe,
+    is_success_status,
+    parse_callback,
+    to_rial,
+    to_toman,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # client
+    "FinoPal",
+    "Config",
+    # transports
+    "Transport",
+    "RequestsTransport",
+    "CallableTransport",
+    # errors
+    "FinoPalError",
+    "ValidationError",
+    "TransportError",
+    "FinoPalException",
+    "ApiError",
+    # response models
+    "ApiResponse",
+    "PaymentRequestResponse",
+    "VerificationResponse",
+    "InquiryResponse",
+    "ReverseResponse",
+    "FeeResponse",
+    # helpers
+    "Validator",
+    "to_rial",
+    "to_toman",
+    "MIN_AMOUNT_RIAL",
+    "MAX_AMOUNT_RIAL",
+    "parse_callback",
+    "is_success_status",
+    "CallbackResult",
+    "describe",
+    # enums
+    "Currency",
+    "TransactionStatus",
+    "CallbackStatus",
+    "FeeType",
+    "ResultCode",
+    "__version__",
+]

finopal/errors/__init__.py

@@ -0,0 +1,17 @@
+"""Error types raised by the FinoPal SDK."""
+
+from finopal.errors.exceptions import (
+    ApiError,
+    FinoPalError,
+    FinoPalException,
+    TransportError,
+    ValidationError,
+)
+
+__all__ = [
+    "FinoPalError",
+    "ValidationError",
+    "TransportError",
+    "FinoPalException",
+    "ApiError",
+]

finopal/errors/exceptions.py

@@ -0,0 +1,124 @@
+"""Exception hierarchy for the FinoPal SDK.
+
+Every exception raised by this package derives from :class:`FinoPalError`, so
+``except FinoPalError`` is always a safe catch-all::
+
+    from finopal import FinoPalError, FinoPalException, ValidationError
+
+    try:
+        payment = finopal.payments.create({...})
+    except ValidationError as exc:
+        # Bad input caught before the HTTP call.
+        ...
+    except FinoPalException as exc:
+        # The gateway answered with success=false or a non-100 code.
+        print(exc.code, exc.describe())
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+__all__ = [
+    "FinoPalError",
+    "ValidationError",
+    "TransportError",
+    "FinoPalException",
+    "ApiError",
+]
+
+
+class FinoPalError(Exception):
+    """Base class for every error raised by the SDK."""
+
+
+class ValidationError(FinoPalError):
+    """Raised when input fails client-side validation.
+
+    No HTTP request is made when this is raised.
+    """
+
+
+class TransportError(FinoPalError):
+    """Raised when the gateway could not be reached or answered with garbage.
+
+    Covers DNS/TLS/connection failures, timeouts, non-JSON bodies and 5xx
+    responses. It means "we do not know what happened", which is exactly why
+    the caller should retry the *inquiry* endpoint rather than blindly
+    re-issuing a payment request.
+
+    :ivar status_code: HTTP status if a response was received, else ``None``.
+    :ivar response: Decoded body if available, else ``{}``.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.response: Dict[str, Any] = dict(response or {})
+
+    def __str__(self) -> str:  # pragma: no cover - trivial
+        if self.status_code is not None:
+            return "{} (HTTP {})".format(self.message, self.status_code)
+        return self.message
+
+
+class FinoPalException(FinoPalError):
+    """Raised when the gateway rejects a request.
+
+    Carries the numeric gateway ``code`` so callers can branch on it::
+
+        from finopal.utils.error_codes import describe
+
+        try:
+            finopal.verifications.verify({"authority": authority, "amount": amount})
+        except FinoPalException as exc:
+            if exc.code == -50:
+                ...  # amount mismatch
+            elif exc.code == 101:
+                ...  # already verified — treat as success
+
+    :ivar code: Numeric gateway code, or ``None`` if none was returned.
+    :ivar message: Human-readable message from the gateway.
+    :ivar response: The full decoded payload, useful for logging.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        code: Optional[int] = None,
+        response: Optional[Mapping[str, Any]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.response: Dict[str, Any] = dict(response or {})
+
+    def describe(self) -> str:
+        """English description of :attr:`code` from the published error list."""
+        # Imported lazily: ``finopal.utils`` pulls in the validator, which in
+        # turn imports this module — a module-level import would be circular.
+        from finopal.utils.error_codes import describe
+
+        return describe(self.code)
+
+    @property
+    def scope(self) -> str:
+        """API surface the code belongs to (``PaymentRequest``, ...)."""
+        from finopal.utils.error_codes import scope_of
+
+        return scope_of(self.code)
+
+    def __str__(self) -> str:
+        if self.code is None:
+            return self.message
+        return "{} (code={})".format(self.message, self.code)
+
+
+#: Backwards/forwards-friendly alias — ``ApiError`` reads better in some codebases.
+ApiError = FinoPalException

finopal/finopal.py

@@ -0,0 +1,140 @@
+"""The :class:`FinoPal` entry point.
+
+Mirrors the ergonomics of the ZarinPal Python SDK — one client object, lazily
+created resource namespaces — while speaking FinoPal's REST API exactly as
+documented at https://finopal.ir/docs.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from finopal.http.client import HttpClient
+from finopal.http.transport import RequestsTransport, Transport
+from finopal.resources.fees import Fees
+from finopal.resources.inquiries import Inquiries
+from finopal.resources.payments import Payments
+from finopal.resources.reversals import Reversals
+from finopal.resources.verifications import Verifications
+from finopal.utils.config import Config
+
+__all__ = ["FinoPal"]
+
+
+class FinoPal:
+    """Client for the FinoPal online payment gateway.
+
+    :param config: A :class:`~finopal.utils.config.Config`.
+    :param transport: Optional transport override (proxies, stubs, an async
+        adapter...). Defaults to :class:`~finopal.http.transport.RequestsTransport`.
+
+    Example::
+
+        from finopal import FinoPal, Config
+
+        finopal = FinoPal(Config(merchant_id="fino-1234-5678-9012-3456"))
+
+        payment = finopal.payments.create({
+            "amount": 1_100,
+            "callback_url": "https://shop.example.com/payment/callback",
+            "order_id": "ORD-1001",
+        })
+        print(payment.payment_url)
+    """
+
+    def __init__(self, config: Config, transport: Optional[Transport] = None) -> None:
+        if not isinstance(config, Config):
+            raise TypeError(
+                "config must be a finopal.Config instance, got {}.".format(
+                    type(config).__name__
+                )
+            )
+
+        self.config = config
+        self.transport: Transport = transport or RequestsTransport(
+            timeout=config.timeout,
+            verify=config.verify_ssl,
+            max_retries=config.max_retries,
+        )
+        self.http = HttpClient(config, self.transport)
+
+        self._payments: Optional[Payments] = None
+        self._verifications: Optional[Verifications] = None
+        self._inquiries: Optional[Inquiries] = None
+        self._reversals: Optional[Reversals] = None
+        self._fees: Optional[Fees] = None
+
+    # --------------------------------------------------------------- resources
+    @property
+    def payments(self) -> Payments:
+        """Create payment requests. ``POST /api/v1/payment/request``."""
+        if self._payments is None:
+            self._payments = Payments(self.http)
+        return self._payments
+
+    @property
+    def verifications(self) -> Verifications:
+        """Verify payments. ``POST /api/v1/payment/verify``."""
+        if self._verifications is None:
+            self._verifications = Verifications(self.http)
+        return self._verifications
+
+    @property
+    def inquiries(self) -> Inquiries:
+        """Read-only status lookups. ``POST /api/v1/payment/inquiry``."""
+        if self._inquiries is None:
+            self._inquiries = Inquiries(self.http)
+        return self._inquiries
+
+    @property
+    def reversals(self) -> Reversals:
+        """Reverse verified transactions. ``POST /api/v1/payment/reverse``."""
+        if self._reversals is None:
+            self._reversals = Reversals(self.http)
+        return self._reversals
+
+    @property
+    def fees(self) -> Fees:
+        """Preview gateway fees. ``POST /api/v1/payment/feeCalculation``."""
+        if self._fees is None:
+            self._fees = Fees(self.http)
+        return self._fees
+
+    # -------------------------------------------------------------- primitives
+    @property
+    def base_url(self) -> str:
+        """Effective gateway host for this client."""
+        return self.config.base_url
+
+    @property
+    def is_sandbox(self) -> bool:
+        """Whether this client points at the sandbox host."""
+        return bool(self.config.sandbox)
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        payload: Optional[Mapping[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Escape hatch for endpoints the SDK does not wrap yet.
+
+        ``merchant_id`` is injected automatically. Only ``POST`` is supported
+        today because that is all the FinoPal gateway exposes::
+
+            finopal.request("POST", "/api/v1/payment/inquiry",
+                            {"authority": "FP_..."})
+        """
+        if str(method).upper() != "POST":
+            raise ValueError(
+                "The FinoPal gateway only exposes POST endpoints; got {!r}.".format(
+                    method
+                )
+            )
+        return self.http.post(path, payload)
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        mode = "sandbox" if self.is_sandbox else "live"
+        return "FinoPal(merchant_id={!r}, mode={!r})".format(
+            self.config.merchant_id, mode
+        )

finopal/http/__init__.py

@@ -0,0 +1,6 @@
+"""HTTP transport layer."""
+
+from finopal.http.client import HttpClient
+from finopal.http.transport import CallableTransport, RequestsTransport, Transport
+
+__all__ = ["HttpClient", "Transport", "RequestsTransport", "CallableTransport"]

finopal/http/client.py

@@ -0,0 +1,69 @@
+"""Thin HTTP client shared by every resource.
+
+Responsibilities:
+
+* build the absolute URL from :class:`~finopal.utils.config.Config`;
+* inject ``merchant_id`` (callers may override it per call);
+* send the standard FinoPal headers;
+* guarantee a ``dict`` comes back, or raise :class:`TransportError`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Mapping, Optional
+
+from finopal.errors.exceptions import TransportError
+from finopal.http.transport import Transport
+from finopal.utils.config import Config
+
+__all__ = ["HttpClient"]
+
+
+class HttpClient:
+    """Wraps a :class:`Transport` with FinoPal-specific request shaping."""
+
+    def __init__(self, config: Config, transport: Transport) -> None:
+        self.config = config
+        self.transport = transport
+
+    @property
+    def base_url(self) -> str:
+        return self.config.base_url
+
+    def headers(self, extra: Optional[Mapping[str, str]] = None) -> Dict[str, str]:
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "User-Agent": self.config.user_agent,
+        }
+        headers.update(dict(extra or {}))
+        return headers
+
+    def post(
+        self,
+        path: str,
+        payload: Optional[Mapping[str, Any]] = None,
+        *,
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """POST ``payload`` to ``path`` with ``merchant_id`` injected.
+
+        A ``merchant_id`` present in ``payload`` wins, so a single client can
+        serve several terminals when needed.
+        """
+        url = self.config.endpoint(path)
+        body: Dict[str, Any] = {"merchant_id": self.config.merchant_id}
+        body.update(dict(payload or {}))
+
+        response = self.transport.post_json(url, body, self.headers(headers))
+
+        if not isinstance(response, Mapping):
+            raise TransportError(
+                "Malformed response from {}: expected a JSON object.".format(url)
+            )
+        return dict(response)
+
+    def __repr__(self) -> str:  # pragma: no cover - trivial
+        return "HttpClient(base_url={!r}, transport={})".format(
+            self.base_url, type(self.transport).__name__
+        )

finopal/http/transport.py

@@ -0,0 +1,176 @@
+"""Transport layer.
+
+The SDK talks to the gateway through a tiny abstraction — :class:`Transport` —
+so the HTTP implementation can be swapped without touching the resource
+classes. This mirrors ``FinoPal\\Sdk\\Http\\TransportInterface`` in the PHP SDK
+and makes the whole package testable without mocking ``requests``.
+
+Built-in implementations:
+
+* :class:`RequestsTransport` — default, backed by ``requests.Session``.
+* :class:`CallableTransport` — wraps any ``fn(url, body, headers) -> dict``,
+  which is what the test-suite and most integrations use for stubs.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable, Dict, Mapping, Optional
+
+import requests
+
+from finopal.errors.exceptions import TransportError
+
+__all__ = ["Transport", "RequestsTransport", "CallableTransport"]
+
+
+class Transport:
+    """Interface every transport must implement."""
+
+    def post_json(
+        self,
+        url: str,
+        body: Mapping[str, Any],
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Dict[str, Any]:
+        """POST ``body`` as JSON to ``url`` and return the decoded response.
+
+        :raises TransportError: on connection failure, timeout, non-JSON body
+            or a 5xx response.
+        """
+        raise NotImplementedError
+
+
+class RequestsTransport(Transport):
+    """Default transport built on ``requests.Session``.
+
+    A single session is reused so TCP connections and TLS handshakes are
+    pooled across calls.
+
+    :param timeout: Per-request timeout in seconds.
+    :param verify: TLS verification. Keep ``True`` in production.
+    :param max_retries: Extra attempts for connection errors only.
+    :param session: Inject a pre-configured session (proxies, adapters...).
+    """
+
+    def __init__(
+        self,
+        timeout: float = 30.0,
+        verify: bool = True,
+        max_retries: int = 0,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        self.timeout = float(timeout)
+        self.verify = bool(verify)
+        self.max_retries = max(0, int(max_retries))
+        self.session = session or requests.Session()
+
+    def post_json(
+        self,
+        url: str,
+        body: Mapping[str, Any],
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Dict[str, Any]:
+        payload = dict(body)
+        request_headers = {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+        request_headers.update(dict(headers or {}))
+
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self.max_retries + 1):
+            try:
+                response = self.session.post(
+                    url,
+                    json=payload,
+                    headers=request_headers,
+                    timeout=self.timeout,
+                    verify=self.verify,
+                )
+            except requests.RequestException as exc:
+                last_error = exc
+                # Only connection-level problems are worth retrying; the SDK
+                # never retries a request the gateway may have already handled.
+                if attempt < self.max_retries:
+                    time.sleep(0.5 * (attempt + 1))
+                    continue
+                raise TransportError(
+                    "Could not reach the FinoPal gateway at {}: {}".format(url, exc)
+                ) from exc
+
+            return self._decode(response, url)
+
+        raise TransportError(  # pragma: no cover - loop always raises or returns
+            "Could not reach the FinoPal gateway at {}: {}".format(url, last_error)
+        )
+
+    @staticmethod
+    def _decode(response: requests.Response, url: str) -> Dict[str, Any]:
+        try:
+            data = response.json()
+        except ValueError as exc:
+            snippet = (response.text or "")[:300]
+            raise TransportError(
+                "The FinoPal gateway returned a non-JSON response "
+                "(HTTP {}) from {}: {!r}".format(response.status_code, url, snippet),
+                status_code=response.status_code,
+            ) from exc
+
+        if not isinstance(data, dict):
+            raise TransportError(
+                "Unexpected response shape from {} (expected a JSON object, "
+                "got {}).".format(url, type(data).__name__),
+                status_code=response.status_code,
+            )
+
+        # 5xx means the gateway itself failed — surface it as a transport error.
+        # 4xx bodies are usually structured FinoPal errors, so let the resource
+        # layer interpret them.
+        if response.status_code >= 500:
+            raise TransportError(
+                "The FinoPal gateway returned HTTP {} from {}.".format(
+                    response.status_code, url
+                ),
+                status_code=response.status_code,
+                response=data,
+            )
+
+        return data
+
+
+class CallableTransport(Transport):
+    """Adapt a plain function into a transport.
+
+    Handy in tests and in frameworks that already own an HTTP client::
+
+        def fake(url, body, headers):
+            return {"success": True, "code": 100,
+                    "data": {"authority": "FP_1", "payment_url": "https://x"}}
+
+        finopal = FinoPal(config, transport=CallableTransport(fake))
+    """
+
+    def __init__(
+        self,
+        handler: Callable[[str, Mapping[str, Any], Mapping[str, str]], Mapping[str, Any]],
+    ) -> None:
+        if not callable(handler):
+            raise TypeError("handler must be callable")
+        self._handler = handler
+
+    def post_json(
+        self,
+        url: str,
+        body: Mapping[str, Any],
+        headers: Optional[Mapping[str, str]] = None,
+    ) -> Dict[str, Any]:
+        result = self._handler(url, dict(body), dict(headers or {}))
+        if not isinstance(result, Mapping):
+            raise TransportError(
+                "CallableTransport handler must return a mapping, got {}.".format(
+                    type(result).__name__
+                )
+            )
+        return dict(result)