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

sep_sdk/__init__.py

@@ -0,0 +1,90 @@
+"""sep-python-sdk: an unofficial, typed Python SDK for the Saman Electronic Payment gateway.
+
+Not affiliated with or endorsed by Saman Electronic Payment (SEP).
+"""
+
+from __future__ import annotations
+
+import logging
+
+from sep_sdk._version import __version__
+from sep_sdk.async_client import AsyncSepClient
+from sep_sdk.callback import parse_callback
+from sep_sdk.client import SepClient
+from sep_sdk.constants import NO_PURCHASE_ID
+from sep_sdk.endpoints import Endpoints
+from sep_sdk.enums import Language, ResultCode, TransactionState, TransactionStatus
+from sep_sdk.errors import (
+    AmountMismatchError,
+    IPNotAllowedError,
+    PaymentNotCompletedError,
+    SepAPIError,
+    SepConfigurationError,
+    SepConnectionError,
+    SepError,
+    SepHTTPError,
+    SepResponseError,
+    SepTimeoutError,
+    SepTokenError,
+    SepTransactionError,
+    SepTransportError,
+    SepValidationError,
+    TerminalError,
+    TransactionNotFoundError,
+    TransactionReversedError,
+    VerifyWindowExpiredError,
+)
+from sep_sdk.redirect import build_send_token_url, redirect_form_fields, render_redirect_form
+from sep_sdk.requests import CallbackMethod, SettlementItem, TokenRequest
+from sep_sdk.responses import CallbackData, Token, TransactionDetail, TransactionResult
+from sep_sdk.retry import RetryPolicy
+from sep_sdk.security import derive_session_key, generate_session_key, hash_card_number
+from sep_sdk.validation import iban_checksum_ok
+
+logging.getLogger("sep_sdk").addHandler(logging.NullHandler())
+
+__all__ = [
+    "NO_PURCHASE_ID",
+    "AmountMismatchError",
+    "AsyncSepClient",
+    "CallbackData",
+    "CallbackMethod",
+    "Endpoints",
+    "IPNotAllowedError",
+    "Language",
+    "PaymentNotCompletedError",
+    "ResultCode",
+    "RetryPolicy",
+    "SepAPIError",
+    "SepClient",
+    "SepConfigurationError",
+    "SepConnectionError",
+    "SepError",
+    "SepHTTPError",
+    "SepResponseError",
+    "SepTimeoutError",
+    "SepTokenError",
+    "SepTransactionError",
+    "SepTransportError",
+    "SepValidationError",
+    "SettlementItem",
+    "TerminalError",
+    "Token",
+    "TokenRequest",
+    "TransactionDetail",
+    "TransactionNotFoundError",
+    "TransactionResult",
+    "TransactionReversedError",
+    "TransactionState",
+    "TransactionStatus",
+    "VerifyWindowExpiredError",
+    "__version__",
+    "build_send_token_url",
+    "derive_session_key",
+    "generate_session_key",
+    "hash_card_number",
+    "iban_checksum_ok",
+    "parse_callback",
+    "redirect_form_fields",
+    "render_redirect_form",
+]

sep_sdk/_base.py

@@ -0,0 +1,174 @@
+"""Everything the sync and async clients share: configuration and pure decisions.
+
+Nothing in this module performs I/O. The two client classes add only "send this
+request and give me the response", so the rules live in exactly one place.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, ClassVar, Final
+
+import httpx
+
+from sep_sdk._parsing import (
+    error_for_http_status,
+    json_object,
+    parse_token,
+    parse_transaction,
+)
+from sep_sdk._version import __version__
+from sep_sdk.endpoints import Endpoints
+from sep_sdk.enums import Language
+from sep_sdk.errors import (
+    AmountMismatchError,
+    PaymentNotCompletedError,
+    SepConfigurationError,
+    SepConnectionError,
+    SepResponseError,
+    SepTimeoutError,
+    SepTransportError,
+    SepValidationError,
+)
+from sep_sdk.redirect import render_redirect_form
+from sep_sdk.requests import TokenRequest
+from sep_sdk.responses import CallbackData, Token, TransactionResult
+from sep_sdk.retry import RetryPolicy
+from sep_sdk.validation import require_int, to_ascii_digits
+
+logger = logging.getLogger("sep_sdk")
+
+DEFAULT_TIMEOUT: Final = httpx.Timeout(20.0, connect=5.0)
+#: Operations that are safe to repeat: Saman answers a repeat with "duplicate request".
+IDEMPOTENT_OPERATIONS: Final = frozenset({"verify", "reverse"})
+
+
+class ClientBase:
+    """Configuration, request building and response interpretation."""
+
+    USER_AGENT: ClassVar[str] = f"sep-python-sdk/{__version__}"
+
+    def __init__(
+        self,
+        terminal_id: str | int,
+        *,
+        endpoints: Endpoints | None,
+        retry: RetryPolicy | None,
+        endpoint_fallback: bool,
+    ) -> None:
+        digits = to_ascii_digits(str(terminal_id).strip())
+        if not digits.isascii() or not digits.isdigit():
+            raise SepConfigurationError("terminal_id must be the numeric terminal number.")
+        self.terminal_id: Final = digits
+        self.endpoints = endpoints or Endpoints()
+        self.retry = retry or RetryPolicy()
+        self._urls = {
+            "token": self.endpoints.token_url,
+            "verify": self.endpoints.verify_url,
+            "reverse": self.endpoints.reverse_url,
+        }
+        self._fallbacks: dict[str, str | None] = {
+            "verify": self.endpoints.verify_fallback_url if endpoint_fallback else None,
+            "reverse": self.endpoints.reverse_fallback_url if endpoint_fallback else None,
+        }
+        self._headers = {"Accept": "application/json", "User-Agent": self.USER_AGENT}
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(terminal_id={self.terminal_id!r})"
+
+    # --- request building -------------------------------------------------
+
+    def _token_payload(self, request: TokenRequest) -> dict[str, Any]:
+        if not isinstance(request, TokenRequest):
+            raise SepValidationError("create_token() needs a TokenRequest.")
+        return request.to_payload(self.terminal_id)
+
+    def _reference_payload(self, ref_num: str, session_key: str | None) -> dict[str, Any]:
+        if not isinstance(ref_num, str) or not ref_num.strip():
+            raise SepValidationError("ref_num must be the receipt string from the callback.")
+        payload: dict[str, Any] = {"RefNum": ref_num, "TerminalNumber": int(self.terminal_id)}
+        if session_key is not None:
+            payload["TxnRandomSessionKey"] = session_key
+        return payload
+
+    # --- endpoint selection ----------------------------------------------
+
+    def _url(self, operation: str) -> str:
+        return self._urls[operation]
+
+    def _switch_to_fallback(self, operation: str) -> bool:
+        """Swap to the alternate spelling once; ``True`` if there was one to try."""
+        fallback = self._fallbacks.get(operation)
+        if fallback is None:
+            return False
+        logger.warning("sep_sdk: %s answered 404; trying %s", operation, fallback)
+        self._urls[operation] = fallback
+        self._fallbacks[operation] = None
+        return True
+
+    # --- retry decisions --------------------------------------------------
+
+    def _may_retry_exception(self, error: httpx.TransportError, operation: str) -> bool:
+        """A connection that never opened is always safe to retry; the rest only if idempotent."""
+        if isinstance(error, httpx.ConnectError | httpx.ConnectTimeout):
+            return True
+        return operation in IDEMPOTENT_OPERATIONS
+
+    def _may_retry_status(self, status_code: int, operation: str) -> bool:
+        return operation in IDEMPOTENT_OPERATIONS and status_code in self.retry.retry_statuses
+
+    @staticmethod
+    def _transport_error(error: httpx.TransportError, operation: str) -> SepTransportError:
+        if isinstance(error, httpx.TimeoutException):
+            return SepTimeoutError(f"{operation}: the gateway did not answer in time.")
+        return SepConnectionError(
+            f"{operation}: could not talk to the gateway ({type(error).__name__})."
+        )
+
+    # --- response interpretation -----------------------------------------
+
+    def _body(self, response: httpx.Response, operation: str) -> dict[str, Any]:
+        if not response.is_success:
+            raise error_for_http_status(response, operation)
+        return json_object(response, operation)
+
+    def _finish_token(self, request: TokenRequest, response: httpx.Response) -> Token:
+        body = self._body(response, "token")
+        return parse_token(request, body, response.headers, self.endpoints)
+
+    def _finish_transaction(self, response: httpx.Response, operation: str) -> TransactionResult:
+        return parse_transaction(self._body(response, operation), operation)
+
+    # --- callback verification -------------------------------------------
+
+    def _ready_to_verify(self, callback: CallbackData, expected_amount: int) -> None:
+        require_int("expected_amount", expected_amount, minimum=1)
+        if not callback.is_ok:
+            raise PaymentNotCompletedError(
+                f"The payment was not completed: {callback.state.message('en')}",
+                state=callback.state,
+            )
+        if callback.terminal_id and callback.terminal_id != self.terminal_id:
+            raise SepValidationError("The callback belongs to a different terminal.")
+
+    def _check_result(self, callback: CallbackData, result: TransactionResult) -> None:
+        if result.ref_num != callback.ref_num:
+            raise SepResponseError("verify: the gateway answered for a different receipt.")
+        if result.detail.terminal_number != int(self.terminal_id):
+            raise SepResponseError("verify: the gateway answered for a different terminal.")
+
+    @staticmethod
+    def _amount_mismatch(expected: int, actual: int, *, was_reversed: bool) -> AmountMismatchError:
+        return AmountMismatchError(
+            f"The gateway took {actual} rials but the order is {expected}.",
+            expected=expected,
+            actual=actual,
+            was_reversed=was_reversed,
+        )
+
+    @staticmethod
+    def render_redirect_form(
+        token: Token, *, language: Language = "en", nonce: str | None = None
+    ) -> str:
+        """See :func:`sep_sdk.render_redirect_form`."""
+        return render_redirect_form(token, language=language, nonce=nonce)

sep_sdk/_parsing.py

@@ -0,0 +1,184 @@
+"""Turning the gateway's JSON into typed values or precise exceptions.
+
+Pure functions only: no I/O, so the sync and async clients share them and they can
+be tested exhaustively without a network.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Any
+
+import httpx
+
+from sep_sdk.constants import DEFAULT_TOKEN_EXPIRY_MINUTES, IPG_URL_HEADER
+from sep_sdk.endpoints import Endpoints
+from sep_sdk.enums import ResultCode
+from sep_sdk.errors import (
+    IPNotAllowedError,
+    SepHTTPError,
+    SepResponseError,
+    SepTokenError,
+    SepTransactionError,
+    TerminalError,
+    TransactionNotFoundError,
+    TransactionReversedError,
+    VerifyWindowExpiredError,
+)
+from sep_sdk.redirect import build_send_token_url
+from sep_sdk.requests import TokenRequest
+from sep_sdk.responses import Token, TransactionDetail, TransactionResult
+
+_TOKEN_PATTERN = re.compile(r"[A-Za-z0-9._~+/=-]{8,512}")
+_TRANSACTION_ERRORS: dict[ResultCode, type[SepTransactionError]] = {
+    ResultCode.TRANSACTION_NOT_FOUND: TransactionNotFoundError,
+    ResultCode.VERIFY_WINDOW_EXPIRED: VerifyWindowExpiredError,
+    ResultCode.TRANSACTION_REVERSED: TransactionReversedError,
+    ResultCode.TERMINAL_INACTIVE: TerminalError,
+    ResultCode.TERMINAL_NOT_FOUND: TerminalError,
+    ResultCode.IP_NOT_ALLOWED: IPNotAllowedError,
+}
+
+
+def json_object(response: httpx.Response, operation: str) -> dict[str, Any]:
+    """The JSON body as a dict, or :class:`SepResponseError`."""
+    try:
+        body = response.json()
+    except (json.JSONDecodeError, UnicodeDecodeError):
+        raise SepResponseError(f"{operation}: the gateway did not answer with JSON.") from None
+    if not isinstance(body, dict):
+        raise SepResponseError(f"{operation}: expected a JSON object.")
+    return {str(key).strip(): value for key, value in body.items()}
+
+
+def error_for_http_status(
+    response: httpx.Response, operation: str
+) -> SepHTTPError | SepTransactionError:
+    """The best exception for a non-2xx answer.
+
+    A body that carries a ``ResultCode`` (Saman sometimes does this with a 4xx) is
+    mapped to the same exceptions as a 200 answer; anything else is :class:`SepHTTPError`.
+    """
+    if operation != "token":
+        try:
+            body = json_object(response, operation)
+        except SepResponseError:
+            body = {}
+        code = _integer(body.get("ResultCode"))
+        if code is not None:
+            return transaction_error(code, str(body.get("ResultDescription", "")), operation)
+    return SepHTTPError(
+        f"{operation}: the gateway answered HTTP {response.status_code}.",
+        status_code=response.status_code,
+    )
+
+
+def parse_token(
+    request: TokenRequest, body: Mapping[str, Any], headers: Mapping[str, str], endpoints: Endpoints
+) -> Token:
+    """Interpret a token response (``status`` 1 with a ``token``, or -1 with an error)."""
+    if _integer(body.get("status")) != 1:
+        code = _integer(body.get("errorCode"))
+        description = str(body.get("errorDesc", ""))
+        raise SepTokenError(
+            f"token: the gateway refused the request (errorCode={code}).",
+            code=code,
+            description=description,
+            operation="token",
+        )
+    token = body.get("token")
+    if not isinstance(token, str) or _TOKEN_PATTERN.fullmatch(token) is None:
+        raise SepResponseError("token: the gateway returned an unusable token.")
+
+    ipg_url = headers.get(IPG_URL_HEADER) or None
+    if ipg_url is not None and not ipg_url.startswith("https://"):
+        raise SepResponseError(f"token: the {IPG_URL_HEADER} header is not an https URL.")
+    return Token(
+        token=token,
+        res_num=request.res_num,
+        form_action=ipg_url or endpoints.form_action_url,
+        get_url=None if ipg_url else build_send_token_url(token, base_url=endpoints.send_token_url),
+        ipg_url=ipg_url,
+        get_method=request.callback_method == "GET",
+        expires_in_minutes=request.token_expiry_minutes or DEFAULT_TOKEN_EXPIRY_MINUTES,
+    )
+
+
+def parse_transaction(body: Mapping[str, Any], operation: str) -> TransactionResult:
+    """Interpret a verify or reverse answer, raising on any non-success code."""
+    code = _integer(body.get("ResultCode"))
+    if code is None:
+        raise SepResponseError(f"{operation}: the answer has no ResultCode.")
+    if code not in {ResultCode.SUCCESS, ResultCode.DUPLICATE_REQUEST}:
+        raise transaction_error(code, str(body.get("ResultDescription", "")), operation)
+
+    detail = body.get("TransactionDetail")
+    if not isinstance(detail, Mapping):
+        raise SepResponseError(f"{operation}: the answer has no TransactionDetail.")
+    return TransactionResult(
+        detail=_detail(detail, operation),
+        result_code=ResultCode.from_wire(code),
+        description=str(body.get("ResultDescription", "")),
+        is_duplicate=code == ResultCode.DUPLICATE_REQUEST,
+    )
+
+
+def transaction_error(code: int, description: str, operation: str) -> SepTransactionError:
+    """Map a failing ``ResultCode`` to the most specific exception."""
+    known = ResultCode.from_wire(code)
+    error_type = (
+        _TRANSACTION_ERRORS.get(known, SepTransactionError)
+        if isinstance(known, ResultCode)
+        else SepTransactionError
+    )
+    message = f"{operation}: the gateway refused the request (ResultCode={code})."
+    return error_type(message, result_code=known, description=description, operation=operation)
+
+
+def _detail(detail: Mapping[str, Any], operation: str) -> TransactionDetail:
+    fields = {str(key).strip(): value for key, value in detail.items()}
+    original = _integer(fields.get("OrginalAmount", fields.get("OriginalAmount")))
+    terminal = _integer(fields.get("TerminalNumber"))
+    ref_num = fields.get("RefNum")
+    if (
+        original is None
+        or original <= 0
+        or terminal is None
+        or not isinstance(ref_num, str)
+        or not ref_num
+    ):
+        raise SepResponseError(f"{operation}: TransactionDetail is incomplete.")
+    affective = _integer(fields.get("AffectiveAmount"))
+    return TransactionDetail(
+        ref_num=ref_num,
+        rrn=str(fields.get("RRN", "")),
+        masked_pan=str(fields.get("MaskedPan", "")),
+        hashed_pan=str(fields.get("HashedPan", "")),
+        terminal_number=terminal,
+        original_amount=original,
+        affective_amount=original if affective is None else affective,
+        trace_date=_trace_date(fields.get("StraceDate")),
+        trace_no=str(fields.get("StraceNo", "")),
+    )
+
+
+def _trace_date(value: object) -> datetime | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.strptime(value.strip(), "%Y-%m-%d %H:%M:%S")
+    except ValueError:
+        return None
+
+
+def _integer(value: object) -> int | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str) and re.fullmatch(r"-?\d{1,18}", value.strip()):
+        return int(value.strip())
+    return None

sep_sdk/_version.py

@@ -0,0 +1,3 @@
+"""The single place the package version is written down."""
+
+__version__ = "0.1.0"

sep_sdk/async_client.py

@@ -0,0 +1,137 @@
+"""The asyncio client. Same behaviour as :class:`SepClient`, with ``await``."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+from sep_sdk._base import DEFAULT_TIMEOUT, ClientBase
+from sep_sdk.endpoints import Endpoints
+from sep_sdk.errors import SepError
+from sep_sdk.requests import TokenRequest
+from sep_sdk.responses import CallbackData, Token, TransactionResult
+from sep_sdk.retry import RetryPolicy
+
+logger = logging.getLogger("sep_sdk")
+
+
+class AsyncSepClient(ClientBase):
+    """Talk to the Saman online gateway from ``async`` code (FastAPI, aiohttp, Django async).
+
+    ::
+
+        async with AsyncSepClient(terminal_id="12345678") as sep:
+            token = await sep.create_token(TokenRequest(amount=100_000, res_num="order-1", ...))
+    """
+
+    def __init__(
+        self,
+        terminal_id: str | int,
+        *,
+        endpoints: Endpoints | None = None,
+        timeout: float | httpx.Timeout = DEFAULT_TIMEOUT,
+        retry: RetryPolicy | None = None,
+        endpoint_fallback: bool = True,
+        transport: httpx.AsyncBaseTransport | None = None,
+        http_client: httpx.AsyncClient | None = None,
+    ) -> None:
+        super().__init__(
+            terminal_id, endpoints=endpoints, retry=retry, endpoint_fallback=endpoint_fallback
+        )
+        self._owns_client = http_client is None
+        self._http = http_client or httpx.AsyncClient(timeout=timeout, transport=transport)
+
+    async def __aenter__(self) -> AsyncSepClient:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        """Release the connection pool (a client you passed in is left open)."""
+        if self._owns_client:
+            await self._http.aclose()
+
+    async def create_token(self, request: TokenRequest) -> Token:
+        """Ask for a payment token for one order (guide step 1)."""
+        response = await self._post("token", self._token_payload(request))
+        return self._finish_token(request, response)
+
+    async def verify_transaction(
+        self, ref_num: str, *, session_key: str | None = None
+    ) -> TransactionResult:
+        """Confirm a receipt with the gateway (guide step 9). Do this within 30 minutes."""
+        response = await self._post("verify", self._reference_payload(ref_num, session_key))
+        return self._finish_transaction(response, "verify")
+
+    async def reverse_transaction(
+        self, ref_num: str, *, session_key: str | None = None
+    ) -> TransactionResult:
+        """Ask for the money back, up to 50 minutes after a verified payment (guide step 10)."""
+        response = await self._post("reverse", self._reference_payload(ref_num, session_key))
+        return self._finish_transaction(response, "reverse")
+
+    async def verify_callback(
+        self,
+        callback: CallbackData,
+        *,
+        expected_amount: int,
+        session_key: str | None = None,
+        reverse_on_mismatch: bool = False,
+    ) -> TransactionResult:
+        """The whole safe check in one call. See :meth:`SepClient.verify_callback`."""
+        self._ready_to_verify(callback, expected_amount)
+        result = await self.verify_transaction(callback.ref_num, session_key=session_key)
+        self._check_result(callback, result)
+        if result.amount != expected_amount:
+            reversed_ = False
+            if reverse_on_mismatch:
+                try:
+                    await self.reverse_transaction(callback.ref_num, session_key=session_key)
+                    reversed_ = True
+                except SepError:
+                    logger.exception("sep_sdk: could not reverse a mismatched payment")
+            raise self._amount_mismatch(expected_amount, result.amount, was_reversed=reversed_)
+        return result
+
+    async def _post(self, operation: str, payload: dict[str, Any]) -> httpx.Response:
+        attempt = 0
+        while True:
+            attempt += 1
+            url = self._url(operation)
+            logger.debug("sep_sdk: %s attempt %d", operation, attempt)
+            try:
+                response = await self._http.post(url, json=payload, headers=self._headers)
+            except httpx.TransportError as error:
+                if attempt < self.retry.max_attempts and self._may_retry_exception(
+                    error, operation
+                ):
+                    await self._pause(attempt, operation)
+                    continue
+                raise self._transport_error(error, operation) from error
+            if response.status_code == 404 and self._switch_to_fallback(operation):
+                attempt -= 1
+                continue
+            if attempt < self.retry.max_attempts and self._may_retry_status(
+                response.status_code, operation
+            ):
+                await self._pause(attempt, operation)
+                continue
+            return response
+
+    async def _pause(self, attempt: int, operation: str) -> None:
+        delay = self.retry.delay(attempt)
+        logger.warning(
+            "sep_sdk: %s failed (attempt %d); retrying in %.1fs", operation, attempt, delay
+        )
+        if delay:
+            await asyncio.sleep(delay)

sep_sdk/callback.py

@@ -0,0 +1,52 @@
+"""Reading the request Saman sends to your ``redirect_url``."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from sep_sdk.enums import TransactionState, TransactionStatus
+from sep_sdk.responses import CallbackData
+
+
+def parse_callback(params: Mapping[str, object]) -> CallbackData:
+    """Turn the callback's form fields or query string into :class:`CallbackData`.
+
+    ``params`` can be anything mapping-like: ``request.POST``, ``request.args``,
+    ``await request.form()``, a plain dict, or ``parse_qs`` output (lists are
+    flattened to their first value). Parameter names are matched case-insensitively
+    because web frameworks differ; values are never executed or evaluated.
+
+    This function **does not trust** its input and makes no network call. See
+    :meth:`SepClient.verify_callback` for the step that actually proves payment.
+    """
+    folded = {str(key).casefold(): value for key, value in params.items()}
+
+    def text(name: str) -> str:
+        value = folded.get(name.casefold())
+        if isinstance(value, Sequence) and not isinstance(value, str | bytes):
+            value = value[0] if value else ""
+        return "" if value is None else str(value).strip()
+
+    state_raw = text("State")
+    return CallbackData(
+        state=TransactionState.from_wire(state_raw),
+        state_raw=state_raw,
+        status=TransactionStatus.from_wire(text("Status")),
+        ref_num=text("RefNum"),
+        res_num=text("ResNum"),
+        terminal_id=text("TerminalId") or text("MID"),
+        trace_no=text("TraceNo"),
+        rrn=text("RRN"),
+        amount=_integer(text("Amount")),
+        wage=_integer(text("Wage")),
+        affective_amount=_integer(text("AffectiveAmount")),
+        token=text("Token"),
+        secure_pan=text("SecurePan"),
+        hashed_card_number=text("HashedCardNumber"),
+        raw={str(key): str(value) for key, value in params.items()},
+    )
+
+
+def _integer(value: str) -> int | None:
+    cleaned = value.replace(",", "")
+    return int(cleaned) if cleaned.isascii() and cleaned.isdigit() else None