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

sep_sdk/requests.py

@@ -0,0 +1,194 @@
+"""What you send to the gateway: the token request and its settlement lines."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from typing import Any, Literal
+
+from sep_sdk.constants import (
+    MAX_ALLOWED_CARDS,
+    MAX_EXTRA_DATA_ITEMS,
+    MAX_EXTRA_DATA_LENGTH,
+    MAX_REDIRECT_URL_LENGTH,
+    MAX_REDIRECT_URL_LENGTH_GET,
+    MAX_SETTLEMENT_ITEMS,
+    MAX_TOKEN_EXPIRY_MINUTES,
+    MIN_TOKEN_EXPIRY_MINUTES,
+    NO_PURCHASE_ID,
+    PURCHASE_ID_LENGTH,
+)
+from sep_sdk.errors import SepValidationError
+from sep_sdk.validation import (
+    normalize_card_hash,
+    normalize_cell_number,
+    normalize_iban,
+    require_http_url,
+    require_int,
+    require_text,
+    to_ascii_digits,
+)
+
+CallbackMethod = Literal["POST", "GET"]
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class SettlementItem:
+    """One destination of a multi-account (``MultiSettle``) or government payment.
+
+    ``purchase_id`` is the 30-digit government identifier. Leave it ``None`` for an
+    ordinary line; in a government request it is filled with thirty zeros for you.
+    """
+
+    iban: str
+    amount: int
+    purchase_id: str | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "iban", normalize_iban(self.iban))
+        require_int("settlement amount", self.amount, minimum=1)
+        if self.purchase_id is not None:
+            digits = to_ascii_digits(require_text("purchase_id", self.purchase_id))
+            if len(digits) != PURCHASE_ID_LENGTH or not digits.isdigit():
+                raise SepValidationError(f"purchase_id must be {PURCHASE_ID_LENGTH} digits.")
+            object.__setattr__(self, "purchase_id", digits)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class TokenRequest:
+    """Everything the guide lets you send when asking for a payment token.
+
+    Required: ``amount`` (rials), ``res_num`` (your unique order id) and
+    ``redirect_url`` (your callback). Everything else is optional.
+
+    ``amount`` is in **rials** and an integer. ``res_num`` should be unique per
+    attempt: it is the only handle you will have if the customer paid and your
+    server never heard back.
+    """
+
+    amount: int
+    res_num: str
+    redirect_url: str
+    wage: int | None = None
+    cell_number: str | int | None = None
+    token_expiry_minutes: int | None = None
+    #: MD5 digests (see :func:`sep_sdk.hash_card_number`) of the only cards allowed to pay.
+    allowed_cards: Sequence[str] = ()
+    #: Up to four free-form strings (50 chars each), visible only in Saman's report panel.
+    extra_data: Sequence[str] = ()
+    #: ``TxnRandomSessionKey``: ties the later verify call to this payment.
+    session_key: str | None = None
+    #: Multi-account settlement lines (at most nine).
+    settlement: Sequence[SettlementItem] = ()
+    #: A government purchase: the first settlement line must carry the government IBAN
+    #: and its 30-digit purchase id. Requires the terminal to be enabled for it.
+    government: bool = False
+    #: How Saman returns the customer: ``POST`` (default) or ``GET`` with a query string.
+    callback_method: CallbackMethod = "POST"
+
+    def __post_init__(self) -> None:
+        require_int("amount", self.amount, minimum=1)
+        require_text("res_num", self.res_num)
+        limit = (
+            MAX_REDIRECT_URL_LENGTH_GET
+            if self.callback_method == "GET"
+            else MAX_REDIRECT_URL_LENGTH
+        )
+        require_http_url("redirect_url", self.redirect_url, max_length=limit)
+        if self.callback_method not in {"POST", "GET"}:
+            raise SepValidationError("callback_method must be 'POST' or 'GET'.")
+        if self.wage is not None:
+            require_int("wage", self.wage, minimum=0)
+        if self.cell_number is not None:
+            object.__setattr__(self, "cell_number", normalize_cell_number(self.cell_number))
+        if self.token_expiry_minutes is not None:
+            require_int(
+                "token_expiry_minutes",
+                self.token_expiry_minutes,
+                minimum=MIN_TOKEN_EXPIRY_MINUTES,
+                maximum=MAX_TOKEN_EXPIRY_MINUTES,
+            )
+        if self.session_key is not None:
+            require_text("session_key", self.session_key)
+        self._normalize_cards()
+        self._normalize_extra_data()
+        self._normalize_settlement()
+
+    def _normalize_cards(self) -> None:
+        cards = tuple(
+            normalize_card_hash(card) for card in _as_sequence("allowed_cards", self.allowed_cards)
+        )
+        if len(cards) > MAX_ALLOWED_CARDS:
+            raise SepValidationError(f"allowed_cards accepts at most {MAX_ALLOWED_CARDS} cards.")
+        object.__setattr__(self, "allowed_cards", cards)
+
+    def _normalize_extra_data(self) -> None:
+        extra = tuple(
+            require_text("extra_data item", item, max_length=MAX_EXTRA_DATA_LENGTH)
+            for item in _as_sequence("extra_data", self.extra_data)
+        )
+        if len(extra) > MAX_EXTRA_DATA_ITEMS:
+            raise SepValidationError(f"extra_data accepts at most {MAX_EXTRA_DATA_ITEMS} items.")
+        object.__setattr__(self, "extra_data", extra)
+
+    def _normalize_settlement(self) -> None:
+        lines = tuple(_as_sequence("settlement", self.settlement))
+        if len(lines) > MAX_SETTLEMENT_ITEMS:
+            raise SepValidationError(f"settlement accepts at most {MAX_SETTLEMENT_ITEMS} lines.")
+        if not all(isinstance(line, SettlementItem) for line in lines):
+            raise SepValidationError("settlement items must be SettlementItem instances.")
+        if self.government:
+            if not lines:
+                raise SepValidationError("A government payment needs at least one settlement line.")
+            if lines[0].purchase_id is None or set(lines[0].purchase_id) == {"0"}:
+                raise SepValidationError(
+                    "The first settlement line of a government payment needs its 30-digit "
+                    "government purchase_id."
+                )
+        object.__setattr__(self, "settlement", lines)
+
+    def to_payload(self, terminal_id: str) -> dict[str, Any]:
+        """The JSON body of the token request, exactly as the guide names the fields."""
+        payload: dict[str, Any] = {
+            "action": "token",
+            "TerminalId": terminal_id,
+            "Amount": self.amount,
+            "ResNum": self.res_num,
+            "RedirectUrl": self.redirect_url,
+        }
+        if self.wage is not None:
+            payload["Wage"] = self.wage
+        if self.cell_number is not None:
+            payload["CellNumber"] = self.cell_number
+        if self.token_expiry_minutes is not None:
+            payload["TokenExpiryInMin"] = self.token_expiry_minutes
+        if self.allowed_cards:
+            payload["HashedCardNumber"] = "|".join(self.allowed_cards)
+        for index, item in enumerate(self.extra_data, start=1):
+            payload[f"ResNum{index}"] = item
+        if self.session_key is not None:
+            payload["TxnRandomSessionKey"] = self.session_key
+        if self.government:
+            payload["TranType"] = "Government"
+        if self.settlement:
+            payload["SettlementIbanInfo"] = [
+                {
+                    "IBAN": line.iban,
+                    "Amount": line.amount,
+                    "PurchaseId": line.purchase_id
+                    if line.purchase_id is not None
+                    else (NO_PURCHASE_ID if self.government else None),
+                }
+                for line in self.settlement
+            ]
+            for entry in payload["SettlementIbanInfo"]:
+                if entry["PurchaseId"] is None:
+                    del entry["PurchaseId"]
+        return payload
+
+
+def _as_sequence(name: str, value: object) -> Sequence[Any]:
+    """Refuse a bare ``str`` where a list of strings is meant (it would iterate characters)."""
+    if isinstance(value, str | bytes) or not isinstance(value, Sequence):
+        raise SepValidationError(f"{name} must be a list or tuple.")
+    return value

sep_sdk/responses.py

@@ -0,0 +1,113 @@
+"""What comes back from the gateway, as immutable, typed values."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from sep_sdk.enums import ResultCode, TransactionState, TransactionStatus
+
+
+@dataclass(frozen=True, slots=True)
+class Token:
+    """A payment token and everything needed to send the customer to the bank.
+
+    Prefer :func:`sep_sdk.render_redirect_form` (a POST form) for the hand-off: it
+    works for every terminal. :attr:`get_url` is the simple link form and exists only
+    for classic terminals; terminals moved to ``neo-pg`` get :attr:`ipg_url` and must
+    use the form.
+    """
+
+    token: str
+    res_num: str
+    #: Where the HTML form posts the token (the ``X-IPG-Url`` header on ``neo-pg``).
+    form_action: str
+    #: ``https://…/SendToken?token=…`` for classic terminals; ``None`` on ``neo-pg``.
+    get_url: str | None
+    #: The ``X-IPG-Url`` header Saman sent, when the terminal is on ``neo-pg``.
+    ipg_url: str | None
+    #: Whether Saman will return the customer by ``GET`` (query string) instead of ``POST``.
+    get_method: bool
+    expires_in_minutes: int
+
+    def __repr__(self) -> str:
+        # The token is a one-time payment handle; keep it out of logs and tracebacks.
+        return (
+            f"Token(res_num={self.res_num!r}, token='***', "
+            f"expires_in_minutes={self.expires_in_minutes})"
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class CallbackData:
+    """The parameters Saman sends to your ``redirect_url``, parsed but **not trusted**.
+
+    Anyone can send your callback URL any parameters. Use this to learn *which* order
+    to check and whether the customer even tried; the only proof of payment is
+    :meth:`SepClient.verify_transaction` (or :meth:`SepClient.verify_callback`).
+    """
+
+    state: TransactionState
+    state_raw: str
+    status: TransactionStatus | None
+    ref_num: str
+    res_num: str
+    terminal_id: str
+    trace_no: str
+    rrn: str
+    amount: int | None
+    wage: int | None
+    affective_amount: int | None
+    token: str
+    #: Masked card number, e.g. ``621986****8080``. Hidden from ``repr``.
+    secure_pan: str = field(repr=False)
+    #: SHA-256 of the card number. Hidden from ``repr``.
+    hashed_card_number: str = field(repr=False)
+    raw: Mapping[str, str] = field(repr=False)
+
+    @property
+    def is_ok(self) -> bool:
+        """``State`` is ``OK``, a receipt exists, and ``Status`` (if sent) agrees."""
+        return (
+            self.state.is_ok and bool(self.ref_num) and self.status in (None, TransactionStatus.OK)
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class TransactionDetail:
+    """The ``TransactionDetail`` block of a verify or reverse answer."""
+
+    ref_num: str
+    rrn: str
+    masked_pan: str = field(repr=False)
+    hashed_pan: str = field(repr=False)
+    terminal_number: int
+    #: The amount sent to the gateway (``OrginalAmount`` in Saman's spelling).
+    original_amount: int
+    #: The amount actually deducted from the card (differs on discount terminals).
+    affective_amount: int
+    #: ``StraceDate`` parsed; Saman does not state a timezone, so it is naive.
+    trace_date: datetime | None
+    trace_no: str
+
+
+@dataclass(frozen=True, slots=True)
+class TransactionResult:
+    """The outcome of a successful verify or reverse call."""
+
+    detail: TransactionDetail
+    result_code: ResultCode | int
+    description: str
+    #: ``True`` when Saman answered "duplicate request" (``2``): the same call had
+    #: already been processed, typically because an earlier reply was lost.
+    is_duplicate: bool
+
+    @property
+    def ref_num(self) -> str:
+        return self.detail.ref_num
+
+    @property
+    def amount(self) -> int:
+        """The amount to compare with your order total (``original_amount``)."""
+        return self.detail.original_amount

sep_sdk/retry.py

@@ -0,0 +1,39 @@
+"""When and how long to wait before asking the gateway again."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from sep_sdk.errors import SepConfigurationError
+
+
+@dataclass(frozen=True, slots=True)
+class RetryPolicy:
+    """Exponential backoff for failed calls.
+
+    ``verify`` and ``reverse`` are idempotent on Saman's side (a repeat is answered
+    "duplicate request"), so they are retried on timeouts, resets and 5xx answers.
+    Token creation is **not** retried after the request may have reached the bank,
+    because that could create two payment sessions for one order; it is retried only
+    when the connection could not even be opened.
+    """
+
+    max_attempts: int = 3
+    backoff_factor: float = 0.5
+    max_backoff: float = 8.0
+    retry_statuses: frozenset[int] = frozenset({408, 425, 429, 500, 502, 503, 504})
+
+    def __post_init__(self) -> None:
+        if self.max_attempts < 1:
+            raise SepConfigurationError("max_attempts must be at least 1.")
+        if self.backoff_factor < 0 or self.max_backoff < 0:
+            raise SepConfigurationError("backoff values must not be negative.")
+
+    @classmethod
+    def none(cls) -> RetryPolicy:
+        """Make every call exactly once."""
+        return cls(max_attempts=1)
+
+    def delay(self, failed_attempts: int) -> float:
+        """Seconds to wait after the given number of failed attempts (``>= 1``)."""
+        return float(min(self.max_backoff, self.backoff_factor * (2 ** (failed_attempts - 1))))

sep_sdk/security.py

@@ -0,0 +1,50 @@
+"""Helpers for the two values the guide asks you to handle carefully."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+import secrets
+
+from sep_sdk.errors import SepValidationError
+from sep_sdk.validation import require_text, to_ascii_digits
+
+_CARD_PATTERN = re.compile(r"\d{16}")
+
+
+def hash_card_number(card_number: str) -> str:
+    """The MD5 digest (upper-case hex) Saman expects in ``allowed_cards``.
+
+    The guide requires an *irreversible* hash and forbids storing the card number.
+    This function never logs or stores its input; call it, keep only the digest.
+    MD5 is mandated by the protocol, not chosen here.
+    """
+    digits = to_ascii_digits(re.sub(r"[\s-]", "", require_text("card_number", card_number)))
+    if _CARD_PATTERN.fullmatch(digits) is None:
+        raise SepValidationError("card_number must be 16 digits.")
+    return hashlib.md5(digits.encode("ascii"), usedforsecurity=False).hexdigest().upper()
+
+
+def generate_session_key() -> str:
+    """A fresh random ``TxnRandomSessionKey`` (32 hex characters).
+
+    Store it with the order, pass it as ``session_key`` when you create the token,
+    and again when you verify. Saman then refuses a receipt that was not issued for
+    that session, so one customer's receipt cannot be replayed on another order.
+    """
+    return secrets.token_hex(16)
+
+
+def derive_session_key(secret: str | bytes, res_num: str) -> str:
+    """A ``TxnRandomSessionKey`` computed from a server secret and the order id.
+
+    Use this instead of :func:`generate_session_key` when you would rather not
+    store a key per order: recompute it at verify time from the same two inputs.
+    Rotating ``secret`` between token and verify makes that payment unverifiable.
+    """
+    key = secret.encode("utf-8") if isinstance(secret, str) else secret
+    if not key:
+        raise SepValidationError("secret must not be empty.")
+    message = f"sep-session:{require_text('res_num', res_num)}".encode()
+    return hmac.new(key, message, hashlib.sha256).hexdigest()[:32]

sep_sdk/testing.py

@@ -0,0 +1,272 @@
+"""An in-memory Saman gateway for your own tests: no network, no terminal, no IP list.
+
+::
+
+    fake = FakeSepGateway(terminal_id="12345678")
+    sep = SepClient("12345678", endpoints=fake.endpoints, transport=fake.transport)
+
+    token = sep.create_token(TokenRequest(amount=100_000, res_num="order-1", redirect_url=...))
+    params = fake.complete_payment(token.token)       # what the bank would POST back
+    callback = parse_callback(params)
+    result = sep.verify_callback(callback, expected_amount=100_000)
+
+The fake follows the guide, not Saman's private behaviour, so treat it as a way to
+exercise *your* code paths (success, cancellation, outages, amount tampering), and
+still run one real small payment before going live.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+import httpx
+
+from sep_sdk.endpoints import Endpoints
+from sep_sdk.enums import ResultCode, TransactionState, TransactionStatus
+
+Spelling = Literal["transaction", "transcation", "both"]
+
+_STATUS_FOR_STATE = {
+    TransactionState.OK: TransactionStatus.OK,
+    TransactionState.CANCELED_BY_USER: TransactionStatus.CANCELED_BY_USER,
+    TransactionState.FAILED: TransactionStatus.FAILED,
+    TransactionState.SESSION_IS_NULL: TransactionStatus.SESSION_IS_NULL,
+    TransactionState.INVALID_PARAMETERS: TransactionStatus.INVALID_PARAMETERS,
+    TransactionState.MERCHANT_IP_ADDRESS_IS_INVALID: (
+        TransactionStatus.MERCHANT_IP_ADDRESS_IS_INVALID
+    ),
+    TransactionState.TOKEN_NOT_FOUND: TransactionStatus.TOKEN_NOT_FOUND,
+    TransactionState.TOKEN_REQUIRED: TransactionStatus.TOKEN_REQUIRED,
+    TransactionState.TERMINAL_NOT_FOUND: TransactionStatus.TERMINAL_NOT_FOUND,
+    TransactionState.MULTISETTLE_POLICY_ERRORS: TransactionStatus.MULTISETTLE_POLICY_ERRORS,
+}
+
+
+@dataclass(slots=True)
+class _Session:
+    res_num: str
+    amount: int
+    redirect_url: str
+    session_key: str | None
+    ref_num: str = ""
+    paid_amount: int = 0
+    verified: bool = False
+    reversed: bool = False
+    expired: bool = False
+
+
+@dataclass(slots=True)
+class RecordedCall:
+    """One request the fake received, for assertions."""
+
+    operation: str
+    url: str
+    body: dict[str, Any]
+
+
+@dataclass(slots=True)
+class _Failure:
+    operation: str | None
+    status_code: int | None
+    drop: bool
+
+
+@dataclass(slots=True)
+class FakeSepGateway:
+    """Simulates token, verify and reverse, and the bank's redirect parameters."""
+
+    terminal_id: str = "12345678"
+    #: Which verify/reverse path spelling answers; the other one gets a 404.
+    spelling: Spelling = "transaction"
+    #: Send the ``X-IPG-Url`` header, like a terminal that moved to ``neo-pg``.
+    neo_pg_url: str | None = None
+    #: Refuse token requests as an unregistered server IP would (``MerchantIpAddressIsInvalid``).
+    reject_ip: bool = False
+    calls: list[RecordedCall] = field(default_factory=list)
+    _sessions: dict[str, _Session] = field(default_factory=dict)
+    _by_ref: dict[str, _Session] = field(default_factory=dict)
+    _failures: list[_Failure] = field(default_factory=list)
+
+    @property
+    def endpoints(self) -> Endpoints:
+        """Endpoints that point at this fake. Pass them to the client."""
+        base = "https://fake.sep.test"
+        return Endpoints(
+            token_url=f"{base}/onlinepg/onlinepg",
+            form_action_url=f"{base}/OnlinePG/OnlinePG",
+            send_token_url=f"{base}/OnlinePG/SendToken",
+            verify_url=f"{base}/ipg/VerifyTransaction",
+            reverse_url=f"{base}/ipg/ReverseTransaction",
+            verify_fallback_url=f"{base}/ipg/VerifyTranscation",
+            reverse_fallback_url=f"{base}/ipg/ReverseTranscation",
+        )
+
+    @property
+    def transport(self) -> httpx.MockTransport:
+        """A transport for :class:`SepClient` and :class:`AsyncSepClient` alike."""
+        return httpx.MockTransport(self._handle)
+
+    # --- scripting the world ---------------------------------------------
+
+    def complete_payment(self, token: str, *, paid_amount: int | None = None) -> dict[str, str]:
+        """The customer pays. Returns the form fields the bank would POST to your callback.
+
+        ``paid_amount`` lets a test simulate a tampered or partial payment.
+        """
+        session = self._session(token)
+        session.ref_num = "REF" + secrets.token_hex(12)
+        session.paid_amount = session.amount if paid_amount is None else paid_amount
+        self._by_ref[session.ref_num] = session
+        return self._callback_fields(token, session, TransactionState.OK)
+
+    def end_payment(
+        self, token: str, state: TransactionState = TransactionState.CANCELED_BY_USER
+    ) -> dict[str, str]:
+        """The customer does not pay (cancel, failure, timeout). Returns the callback fields."""
+        session = self._session(token)
+        return self._callback_fields(token, session, state)
+
+    def expire(self, ref_num: str) -> None:
+        """Pretend 30 minutes passed without a verify: the next verify answers ``-6``."""
+        self._by_ref[ref_num].expired = True
+
+    def fail_next(self, *, status_code: int = 503, operation: str | None = None) -> None:
+        """Answer the next matching call with an HTTP error."""
+        self._failures.append(_Failure(operation, status_code, drop=False))
+
+    def drop_next(self, *, operation: str | None = None) -> None:
+        """Lose the next matching call: the client sees a connection error."""
+        self._failures.append(_Failure(operation, None, drop=True))
+
+    # --- the fake server --------------------------------------------------
+
+    def _handle(self, request: httpx.Request) -> httpx.Response:
+        operation = self._operation(request.url.path)
+        body: dict[str, Any] = json.loads(request.content or b"{}")
+        self.calls.append(RecordedCall(operation, str(request.url), body))
+
+        failure = self._take_failure(operation)
+        if failure is not None:
+            if failure.drop:
+                raise httpx.ConnectError("fake: connection dropped", request=request)
+            return httpx.Response(failure.status_code or 503, json={"error": "injected"})
+        if operation == "unknown" or not self._path_allowed(operation, request.url.path):
+            return httpx.Response(404, json={"error": "not found"})
+        if operation == "token":
+            return self._token(body)
+        return self._transaction(operation, body)
+
+    def _operation(self, path: str) -> str:
+        lowered = path.lower()
+        if lowered.endswith("/onlinepg"):
+            return "token"
+        for name in ("verify", "reverse"):
+            if lowered.endswith((f"/{name}transaction", f"/{name}transcation")):
+                return name
+        return "unknown"
+
+    def _path_allowed(self, operation: str, path: str) -> bool:
+        if operation == "token" or self.spelling == "both":
+            return True
+        legacy = path.lower().endswith("transcation")
+        return legacy == (self.spelling == "transcation")
+
+    def _take_failure(self, operation: str) -> _Failure | None:
+        for index, failure in enumerate(self._failures):
+            if failure.operation in (None, operation):
+                return self._failures.pop(index)
+        return None
+
+    def _token(self, body: dict[str, Any]) -> httpx.Response:
+        if self.reject_ip:
+            return httpx.Response(
+                200, json={"status": -1, "errorCode": "8", "errorDesc": "merchant ip is invalid"}
+            )
+        if str(body.get("TerminalId")) != self.terminal_id:
+            return httpx.Response(
+                200, json={"status": -1, "errorCode": "12", "errorDesc": "terminal not found"}
+            )
+        token = secrets.token_hex(16)
+        self._sessions[token] = _Session(
+            res_num=str(body.get("ResNum", "")),
+            amount=int(body.get("Amount", 0)),
+            redirect_url=str(body.get("RedirectUrl", "")),
+            session_key=body.get("TxnRandomSessionKey"),
+        )
+        headers = {"X-IPG-Url": self.neo_pg_url} if self.neo_pg_url else {}
+        return httpx.Response(200, json={"status": 1, "token": token}, headers=headers)
+
+    def _transaction(self, operation: str, body: dict[str, Any]) -> httpx.Response:
+        session = self._by_ref.get(str(body.get("RefNum")))
+        if str(body.get("TerminalNumber")) != self.terminal_id:
+            return self._result(ResultCode.TERMINAL_NOT_FOUND)
+        if session is None or (
+            session.session_key is not None
+            and body.get("TxnRandomSessionKey") != session.session_key
+        ):
+            return self._result(ResultCode.TRANSACTION_NOT_FOUND)
+        return self._reverse(session) if operation == "reverse" else self._verify(session)
+
+    def _reverse(self, session: _Session) -> httpx.Response:
+        if session.reversed:
+            return self._result(ResultCode.DUPLICATE_REQUEST, session)
+        session.reversed = True
+        return self._result(ResultCode.SUCCESS, session)
+
+    def _verify(self, session: _Session) -> httpx.Response:
+        if session.reversed:
+            return self._result(ResultCode.TRANSACTION_REVERSED)
+        if session.expired and not session.verified:
+            return self._result(ResultCode.VERIFY_WINDOW_EXPIRED)
+        duplicate = session.verified
+        session.verified = True
+        return self._result(
+            ResultCode.DUPLICATE_REQUEST if duplicate else ResultCode.SUCCESS, session
+        )
+
+    def _result(self, code: ResultCode, session: _Session | None = None) -> httpx.Response:
+        body: dict[str, Any] = {
+            "ResultCode": int(code),
+            "ResultDescription": code.message("en"),
+            "Success": code is ResultCode.SUCCESS,
+        }
+        if session is not None:
+            body["TransactionDetail"] = {
+                "RRN": "14226761817",
+                "RefNum": session.ref_num,
+                "MaskedPan": "621986****8080",
+                "HashedPan": "b96a14400c3a59249e87c300ecc06e5920327e70220213b5bbb7d7b2410f7e0d",
+                "TerminalNumber": int(self.terminal_id),
+                "OrginalAmount": session.paid_amount,
+                "AffectiveAmount": session.paid_amount,
+                "StraceDate": "2026-01-01 12:00:00",
+                "StraceNo": "100428",
+            }
+        return httpx.Response(200, json=body)
+
+    def _session(self, token: str) -> _Session:
+        try:
+            return self._sessions[token]
+        except KeyError:
+            raise KeyError("Unknown token: create it with the client first.") from None
+
+    def _callback_fields(
+        self, token: str, session: _Session, state: TransactionState
+    ) -> dict[str, str]:
+        ok = state is TransactionState.OK
+        return {
+            "MID": self.terminal_id,
+            "TerminalId": self.terminal_id,
+            "State": state.value,
+            "Status": str(int(_STATUS_FOR_STATE[state])),
+            "RRN": "14226761817" if ok else "",
+            "RefNum": session.ref_num if ok else "",
+            "ResNum": session.res_num,
+            "TraceNo": "100428" if ok else "",
+            "Amount": str(session.paid_amount if ok else session.amount),
+            "SecurePan": "621986****8080" if ok else "",
+            "Token": token,
+        }