irgateway 0.3.2__py3-none-any.whl

irgateway/__init__.py

@@ -0,0 +1,7 @@
+"""Iranian payment gateway SDK: Zarinpal and Zibal, sync and async."""
+
+__version__ = "0.3.2"
+
+from ._core import (
+    GatewayTransportError, GatewayHTTPError, GatewayProtocolError, PaymentAmountMismatch,
+)

irgateway/_core.py

@@ -0,0 +1,169 @@
+"""Shared transport, money and validation utilities for payment gateways.
+
+All amounts are integral; HTTP failures never cause an implicit retry.
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import fields, is_dataclass
+from datetime import datetime
+from typing import Any, TypeVar, get_args, get_origin, get_type_hints, Union
+from urllib.parse import urlsplit
+
+
+class GatewayTransportError(Exception):
+    """Request outcome is unknown. Reconcile via inquiry before retrying a mutation."""
+
+
+class GatewayProtocolError(Exception):
+    """The gateway returned a malformed or unrecognized response."""
+
+
+class GatewayHTTPError(GatewayTransportError):
+    """An unexpected HTTP status was returned by the gateway."""
+
+    def __init__(self, status: int):
+        self.status = status
+        super().__init__(f"Gateway HTTP status {status}")
+
+
+class PaymentAmountMismatch(Exception):
+    """The verified amount does not match the locally recorded payable amount."""
+
+    def __init__(self, expected_rials: int, actual_rials: int):
+        self.expected_rials = expected_rials
+        self.actual_rials = actual_rials
+        super().__init__(f"Payment amount mismatch: expected {expected_rials} IRR, received {actual_rials} IRR")
+
+
+def money(value: int, *, name: str = 'amount', zero: bool = False) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < (0 if zero else 1):
+        raise ValueError(f"{name} must be a {'non-negative' if zero else 'positive'} integer")
+    return value
+
+
+def rial(amount: int, currency: str = 'IRT') -> int:
+    money(amount)
+    if currency not in ('IRR', 'IRT'):
+        raise ValueError('currency must be IRR or IRT')
+    return amount * (10 if currency == 'IRT' else 1)
+
+
+def url(value: str, *, name: str = 'callback_url') -> str:
+    if not isinstance(value, str) or not value.strip() or any(c.isspace() for c in value):
+        raise ValueError(f'{name} must be a valid http(s) URL')
+    parts = urlsplit(value)
+    if parts.scheme not in ('https', 'http') or not parts.hostname or parts.username or parts.password:
+        raise ValueError(f'{name} must be a valid http(s) URL')
+    return value
+
+
+def required_string(value: str, *, name: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ValueError(f'{name} must not be blank')
+    return value
+
+
+def code_int(value: Any) -> int | None:
+    if type(value) is int:
+        return value
+    if isinstance(value, str) and value.strip().lstrip('-').isdigit():
+        return int(value)
+    return None
+
+
+def decode_json(data: Any) -> dict:
+    if not isinstance(data, dict):
+        raise GatewayProtocolError('Gateway response must be a JSON object')
+    return data
+
+
+def sync_post(session: Any, endpoint: str, payload: dict, timeout: int) -> dict:
+    import requests
+    try:
+        response = session.post(endpoint, json=payload, timeout=timeout)
+    except requests.RequestException as exc:
+        raise GatewayTransportError('Network error; payment outcome is unknown') from exc
+    try:
+        result = decode_json(response.json())
+    except (ValueError, TypeError) as exc:
+        if not 200 <= response.status_code < 300:
+            raise GatewayHTTPError(response.status_code) from exc
+        raise GatewayProtocolError('Gateway returned invalid JSON') from exc
+    if not 200 <= response.status_code < 300:
+        # Return valid gateway error payloads to the gateway-specific parser.
+        if not _has_gateway_error(result):
+            raise GatewayHTTPError(response.status_code)
+    return result
+
+
+async def async_post(session: Any, endpoint: str, payload: dict) -> dict:
+    import aiohttp
+    try:
+        async with session.post(endpoint, json=payload) as response:
+            try:
+                result = decode_json(await response.json(content_type=None))
+            except (ValueError, TypeError, UnicodeError) as exc:
+                if not 200 <= response.status < 300:
+                    raise GatewayHTTPError(response.status) from exc
+                raise GatewayProtocolError('Gateway returned invalid JSON') from exc
+            if not 200 <= response.status < 300 and not _has_gateway_error(result):
+                raise GatewayHTTPError(response.status)
+            return result
+    except (aiohttp.ClientError, asyncio.TimeoutError, OSError) as exc:
+        raise GatewayTransportError('Network error; payment outcome is unknown') from exc
+
+
+def _has_gateway_error(result: dict) -> bool:
+    errors = result.get('errors')
+    return ((isinstance(errors, dict) and bool(errors))
+            or code_int(result.get('result')) not in (None, 100)
+            or (isinstance(result.get('data'), dict)
+                and code_int(result['data'].get('code')) not in (None, 100)))
+
+
+T = TypeVar('T')
+
+
+def dataclass_from_dict(cls: type[T], data: dict) -> T:
+    """Recursively deserialize supported nested dataclass/Optional/List fields."""
+    if not isinstance(data, dict):
+        raise TypeError('data must be a mapping')
+    hints = get_type_hints(cls)
+    kwargs = {}
+    for field in fields(cls):
+        if field.name in data:
+            kwargs[field.name] = _coerce(hints.get(field.name), data[field.name])
+    return cls(**kwargs)
+
+
+def _coerce(hint: Any, value: Any) -> Any:
+    if value is None or hint is None:
+        return value
+    origin = get_origin(hint)
+    if origin in (Union, __import__('types').UnionType):
+        choices = [t for t in get_args(hint) if t is not type(None)]
+        return _coerce(choices[0], value) if len(choices) == 1 else value
+    if origin is list and isinstance(value, list):
+        (item_type,) = get_args(hint)
+        return [_coerce(item_type, item) for item in value]
+    if hint is datetime and isinstance(value, str):
+        return datetime.fromisoformat(value.replace('Z', '+00:00'))
+    if isinstance(hint, type) and is_dataclass(hint) and isinstance(value, dict):
+        return dataclass_from_dict(hint, value)
+    return value
+
+
+def legacy_buyer_fee(amount: int, *, gateway: str) -> int:
+    """Deterministic reproduction of the v0.2.11 default surcharge.
+
+    Kept ONLY for backwards-compatible omission of ``buyer_fee``; unlike an
+    authoritative gateway quote this is not a guarantee of the actual fee.
+    These rational integer operations avoid floating point drift.
+    """
+    money(amount)
+    if gateway == 'zarinpal':
+        return ((min(amount, 3_200_000) + 100_000) * 28) // 5_000
+    if gateway == 'zibal':
+        return (max(200_000, min(amount, 2_000_000)) * 28) // 2_500
+    raise ValueError('Unsupported gateway for legacy fee calculation')

irgateway/_models.py

@@ -0,0 +1,47 @@
+"""Lightweight serialization helpers shared by the gateway response models."""
+from __future__ import annotations
+from dataclasses import asdict, is_dataclass
+from datetime import datetime
+import json
+from ._core import dataclass_from_dict
+
+
+class DictMixin:
+    def to_dict(self, *, include_extended: bool = False) -> dict:
+        def convert(value):
+            if isinstance(value, datetime):
+                return value.isoformat()
+            if isinstance(value, dict):
+                return {k: convert(v) for k, v in value.items()}
+            if isinstance(value, list):
+                return [convert(v) for v in value]
+            return value
+        if not is_dataclass(self):
+            raise TypeError('to_dict only works with dataclasses')
+        result = convert(asdict(self))
+        if not include_extended:
+            model_name = type(self).__name__
+            if model_name == 'PaymentRequest':
+                for key in ('amount', 'payable_amount', 'amount_rials', 'buyer_fee'):
+                    result.pop(key, None)
+            elif model_name == 'PaymentVerification' and 'track_id' not in result and 'status' in result:
+                # Zibal's original PaymentVerification dictionary format.
+                result.pop('status', None)
+                result.pop('paid_at', None)
+            elif model_name == 'ZarinpalConfig':
+                result.pop('currency', None)
+            elif model_name == 'ZibalConfig':
+                for key in ('currency', 'fee_policy'):
+                    result.pop(key, None)
+        return result
+
+    @classmethod
+    def from_dict(cls, data: dict):
+        return dataclass_from_dict(cls, data)
+
+    def to_json(self, indent: int | None = None, ensure_ascii: bool = False, *,
+                include_extended: bool = False) -> str:
+        return json.dumps(self.to_dict(include_extended=include_extended), indent=indent, ensure_ascii=ensure_ascii)
+
+    def __str__(self) -> str:
+        return self.to_json(indent=4)

irgateway/zarinpal/__init__.py

@@ -0,0 +1,5 @@
+"""Python SDK for Zarinpal Payment Gateway with sync and async support."""
+
+from .client import ZarinpalClient, AsyncZarinpalClient
+from .types import ZarinpalConfig
+from .errors import ZarinpalException

irgateway/zarinpal/client.py

@@ -0,0 +1,394 @@
+"""Zarinpal v4 clients. Monetary inputs use config.currency (default IRT)."""
+from __future__ import annotations
+
+from datetime import datetime
+import re
+from typing import Optional, List, Literal
+from urllib.parse import urljoin
+
+from irgateway._core import (
+    GatewayProtocolError, code_int, decode_json, money, required_string, rial,
+    sync_post, async_post, url, legacy_buyer_fee, PaymentAmountMismatch,
+)
+from .errors import ERROR_MAP, ZarinpalException
+from .types import (
+    PaymentRequest, PaymentVerification, UnverifiedTransactions, UnverifiedTransaction,
+    PaymentMetadata, ZarinpalConfig, PaymentCartData, Wage, FeeCalculation,
+)
+from .enums import Environment, PaymentStatus
+
+
+class BaseClient:
+    def __init__(self, merchant_id: str, environment: Environment = Environment.PRODUCTION,
+                 config: Optional[ZarinpalConfig] = None):
+        self.merchant_id = required_string(merchant_id, name='merchant_id')
+        if not isinstance(environment, Environment):
+            raise ValueError('environment must be an Environment enum')
+        self.environment = environment
+        self.config = config if config is not None else ZarinpalConfig()
+        self._base_url = environment.value
+        self._recent_payments = {}  # best-effort convenience, NOT durable transaction storage
+        if self.config.startpay_endpoint:
+            url(self.config.startpay_endpoint, name='startpay_endpoint')
+
+    def _get_endpoint(self, path: str) -> str:
+        return urljoin(self._base_url, path)
+
+    def _get_custom_endpoint(self, authority: str) -> str:
+        if not re.fullmatch(r'[A-Za-z0-9_-]{1,128}', authority):
+            raise GatewayProtocolError('Invalid payment authority')
+        if self.config.startpay_endpoint:
+            return urljoin(self.config.startpay_endpoint.rstrip('/') + '/', authority)
+        return self._get_endpoint(f'pg/StartPay/{authority}')
+
+    @staticmethod
+    def _get_response(response: dict) -> tuple[int, dict]:
+        response = decode_json(response)
+        data = response.get('data')
+        if isinstance(data, dict) and 'code' in data:
+            code = code_int(data['code'])
+            if code is None:
+                raise GatewayProtocolError('Invalid Zarinpal response code')
+            return code, data
+        errors = response.get('errors')
+        if isinstance(errors, dict) and errors:
+            code = code_int(errors.get('code'))
+            if code is None:
+                # Example: {"errors": {"authority": ["Invalid authority", "-54"]}}
+                for value in errors.values():
+                    if isinstance(value, list):
+                        for item in reversed(value):
+                            code = code_int(item)
+                            if code is not None:
+                                break
+                    if code is not None:
+                        break
+            if code is None:
+                raise GatewayProtocolError(f"Zarinpal returned validation errors: {str(errors)[:250]}")
+            return code, errors
+        raise GatewayProtocolError('Zarinpal response missing data.code or errors.code')
+
+    @staticmethod
+    def _handle_error(code: int, data: dict | None = None):
+        exception = ERROR_MAP.get(code)
+        if exception:
+            raise exception()
+        message = data.get('message') if isinstance(data, dict) else None
+        raise ZarinpalException(code, message or 'Zarinpal returned an unknown error', '')
+
+    def _check(self, response: dict, *, allow_codes: tuple[int, ...] = (100,)) -> tuple[int, dict]:
+        code, data = self._get_response(response)
+        if code not in allow_codes:
+            self._handle_error(code, data)
+        return code, data
+
+    @staticmethod
+    def _add_fee(amount: int) -> int:
+        """Legacy v0.2.11 helper; returns gross amount in caller units."""
+        return money(amount) + legacy_buyer_fee(amount, gateway='zarinpal')
+
+    def _fee_amount(self, buyer_fee: int | Literal['auto'] | None) -> int:
+        """Validate a resolved fee. Auto quotes are fetched before building payload."""
+        if self.config.fee_type == 'BUYER':
+            if buyer_fee is None:
+                raise ValueError('Internal error: buyer_fee must be resolved before building the payment')
+            return money(buyer_fee, name='buyer_fee', zero=True)
+        if buyer_fee is not None:
+            raise ValueError('buyer_fee requires config.fee_type=BUYER')
+        return 0
+
+    def _auto_fee_from_quote(self, amount: int, quote: FeeCalculation) -> int:
+        """Prefer gateway's proposed gross amount; never guess missing quotes.
+
+        A Payer fee is already billed by Zarinpal, so adding a *second* local
+        surcharge would double charge the customer.
+        """
+        base_rials = rial(amount, self.config.currency)
+        quoted_base = code_int(quote.amount)
+        if quoted_base != base_rials:
+            raise GatewayProtocolError('Zarinpal fee quote amount does not match the order')
+        fee_type = quote.fee_type
+        if not isinstance(fee_type, str):
+            raise GatewayProtocolError('Zarinpal fee quote missing fee_type')
+        normalized = fee_type.strip().lower()
+        if normalized == 'payer':
+            return 0
+        if normalized != 'merchant':
+            raise GatewayProtocolError('Unexpected Zarinpal fee_type in fee quote')
+        suggested = code_int(quote.suggested_amount)
+        if suggested is None or suggested < base_rials:
+            raise GatewayProtocolError('Zarinpal fee quote missing valid suggested_amount')
+        # Round UP to avoid undercharging when the quote is not whole toman.
+        unit = 10 if self.config.currency == 'IRT' else 1
+        payable = (suggested + unit - 1) // unit
+        return payable - amount
+
+    def _request_payload(self, amount: int, callback_url: str, description: str,
+                         metadata: Optional[PaymentMetadata], cart_data: Optional[PaymentCartData],
+                         wages: Optional[List[Wage]], buyer_fee: int | None, referrer_id: Optional[str]) -> tuple[dict, int]:
+        money(amount)
+        url(callback_url)
+        required_string(description, name='description')
+        total = amount + self._fee_amount(buyer_fee)
+        gateway_amount = rial(total, self.config.currency)
+        # Send IRR explicitly. Zarinpal verify() always accepts amount in IRR.
+        payload = {'merchant_id': self.merchant_id, 'amount': gateway_amount,
+                   'currency': 'IRR', 'callback_url': callback_url, 'description': description}
+        if referrer_id is not None:
+            payload['referrer_id'] = required_string(referrer_id, name='referrer_id')
+        if metadata:
+            payload['metadata'] = {k: v for k, v in metadata.to_dict().items() if v is not None}
+        if cart_data:
+            cart = cart_data.to_dict()
+            factor = 10 if self.config.currency == 'IRT' else 1
+            for item in cart.get('items', []):
+                for key in ('item_amount', 'item_amount_sum'):
+                    if item.get(key) is not None:
+                        money(item[key], name=key, zero=True)
+                        item[key] *= factor
+            for section in ('added_costs', 'deductions'):
+                if cart.get(section):
+                    for k, val in cart[section].items():
+                        if val is not None:
+                            money(val, name=k, zero=True)
+                            cart[section][k] = val * factor
+            payload['cart_data'] = cart
+        if wages:
+            total_wages = sum(money(w.amount, name='wage.amount') for w in wages)
+            if total_wages > total:
+                raise ValueError('Sum of wages exceeds total payable amount')
+            payload['wages'] = [dict(w.to_dict(), amount=rial(w.amount, self.config.currency)) for w in wages]
+        return payload, total
+
+    def _request_result(self, response: dict, amount: int, total: int) -> PaymentRequest:
+        code, data = self._check(response)
+        authority = data.get('authority')
+        if not isinstance(authority, str) or not re.fullmatch(r'[A-Za-z0-9_-]{1,128}', authority):
+            raise GatewayProtocolError('Zarinpal response has invalid authority')
+        return PaymentRequest(authority=authority, code=code,
+                              payment_url=self._get_custom_endpoint(authority),
+                              fee_type=data.get('fee_type'), fee=data.get('fee'),
+                              amount=amount, payable_amount=total,
+                              amount_rials=rial(total, self.config.currency),
+                              buyer_fee=total - amount)
+
+    def _remember_payment(self, result: PaymentRequest) -> PaymentRequest:
+        self._recent_payments[result.authority] = (
+            result.amount, result.payable_amount, result.amount_rials)
+        if len(self._recent_payments) > 256:
+            self._recent_payments.pop(next(iter(self._recent_payments)))
+        return result
+
+    def _verify_payload(self, authority: str, amount: int, *, amount_is_rials: bool = False) -> dict:
+        authority = required_string(authority, name='authority')
+        money(amount)
+        if amount_is_rials:
+            if authority in self._recent_payments:
+                expected = self._recent_payments[authority][2]
+                if expected != amount:
+                    raise PaymentAmountMismatch(expected, amount)
+            gateway_amount = amount
+        elif authority in self._recent_payments:
+            original, payable, actual_rials = self._recent_payments[authority]
+            if amount not in (original, payable, actual_rials):
+                raise PaymentAmountMismatch(actual_rials, rial(amount, self.config.currency))
+            gateway_amount = actual_rials
+        else:
+            # No reliable way to infer an older order's original currency or
+            # surcharge without persistent order data. Retain the v0.3.x IRT
+            # contract, with a public explicit-IRR switch for legacy workarounds.
+            gateway_amount = rial(amount, self.config.currency)
+        return {'merchant_id': self.merchant_id,
+                'authority': authority, 'amount': gateway_amount}
+
+    def _verify_result(self, response: dict, allow_already_verified: bool) -> PaymentVerification:
+        code, data = self._check(response, allow_codes=(100, 101) if allow_already_verified else (100,))
+        wages = data.get('wages')
+        return PaymentVerification(code=code, ref_id=data.get('ref_id'),
+                                   card_pan=data.get('card_pan'), card_hash=data.get('card_hash'),
+                                   fee_type=data.get('fee_type'), fee=data.get('fee'),
+                                   wages=[Wage.from_dict(w) for w in wages] if isinstance(wages, list) else None)
+
+    def _unverified_result(self, response: dict) -> UnverifiedTransactions:
+        code, data = self._check(response)
+        authorities = []
+        for item in data.get('authorities', []):
+            if not isinstance(item, dict):
+                raise GatewayProtocolError('Invalid unverified transaction')
+            date = item.get('date')
+            if isinstance(date, str):
+                try:
+                    date = datetime.fromisoformat(date.replace('Z', '+00:00'))
+                except ValueError as exc:
+                    raise GatewayProtocolError('Invalid transaction date') from exc
+            authorities.append(UnverifiedTransaction(authority=item.get('authority'),
+                                                     amount=item.get('amount'),
+                                                     callback_url=item.get('callback_url'),
+                                                     referer=item.get('referer'), date=date))
+        return UnverifiedTransactions(code=code, authorities=authorities)
+
+    def _inquiry_result(self, response: dict) -> PaymentStatus:
+        _, data = self._check(response)
+        try:
+            return PaymentStatus(data['status'])
+        except (KeyError, ValueError) as exc:
+            raise GatewayProtocolError('Unknown Zarinpal transaction status') from exc
+
+    def _fee_result(self, response: dict) -> FeeCalculation:
+        _, data = self._check(response)
+        return FeeCalculation(amount=data.get('amount'), fee=data.get('fee'),
+                              fee_type=data.get('fee_type'), suggested_amount=data.get('suggested_amount'))
+
+    def _payload(self, authority: str) -> dict:
+        return {'merchant_id': self.merchant_id, 'authority': required_string(authority, name='authority')}
+
+
+class ZarinpalClient(BaseClient):
+    __type__ = 'SYNC'
+
+    def __init__(self, merchant_id: str, environment: Environment = Environment.PRODUCTION,
+                 config: Optional[ZarinpalConfig] = None):
+        import requests
+        super().__init__(merchant_id, environment, config)
+        self._session = requests.Session()
+        self._session.headers.update({'Content-Type': 'application/json', 'Accept': 'application/json'})
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def close(self):
+        self._session.close()
+
+    def _post(self, path: str, payload: dict) -> dict:
+        return sync_post(self._session, self._get_endpoint(path), payload, self.config.timeout)
+
+    def request(self, amount: int, callback_url: str, description: str,
+                metadata: Optional[PaymentMetadata] = None, cart_data: Optional[PaymentCartData] = None,
+                wages: Optional[List[Wage]] = None, *, buyer_fee: int | Literal['auto'] | None = None,
+                referrer_id: Optional[str] = None) -> PaymentRequest:
+        money(amount)
+        url(callback_url)
+        required_string(description, name='description')
+        if self.config.fee_type == 'BUYER' and buyer_fee is None:
+            buyer_fee = legacy_buyer_fee(amount, gateway='zarinpal')
+        if buyer_fee == 'auto':
+            if self.config.fee_type != 'BUYER':
+                raise ValueError('buyer_fee requires config.fee_type=BUYER')
+            buyer_fee = self.calculate_buyer_fee(amount)
+        payload, total = self._request_payload(amount, callback_url, description, metadata, cart_data, wages, buyer_fee, referrer_id)
+        return self._remember_payment(self._request_result(self._post('pg/v4/payment/request.json', payload), amount, total))
+
+    def verify(self, authority: str, amount: int, *, allow_already_verified: bool = False,
+               amount_is_rials: bool = False) -> PaymentVerification:
+        return self._verify_result(self._post('pg/v4/payment/verify.json',
+                                              self._verify_payload(authority, amount,
+                                                                   amount_is_rials=amount_is_rials)),
+                                   allow_already_verified)
+
+    def unverified(self) -> UnverifiedTransactions:
+        return self._unverified_result(self._post('pg/v4/payment/unVerified.json', {'merchant_id': self.merchant_id}))
+
+    def reverse(self, authority: str) -> bool:
+        # Legacy contract: gateway business rejection -> False; transport errors still raise.
+        code, _ = self._get_response(self._post('pg/v4/payment/reverse.json', self._payload(authority)))
+        return code == 100
+
+    def inquiry(self, authority: str) -> PaymentStatus:
+        return self._inquiry_result(self._post('pg/v4/payment/inquiry.json', self._payload(authority)))
+
+    def calculate_fee(self, amount: int, *, amount_currency: str | None = None) -> FeeCalculation:
+        """Fee quote. Legacy direct callers supply rials by default.
+
+        Set ``amount_currency='IRT'`` to supply tomans instead.
+        """
+        payload = {'merchant_id': self.merchant_id, 'amount': rial(amount, amount_currency or 'IRR')}
+        if amount_currency is not None:
+            payload['currency'] = 'IRR'
+        return self._fee_result(self._post('pg/v4/payment/feeCalculation.json', payload))
+
+    def calculate_buyer_fee(self, amount: int) -> int:
+        """Fetch authoritative fee quote and return the needed extra amount."""
+        money(amount)
+        return self._auto_fee_from_quote(amount, self.calculate_fee(amount, amount_currency=self.config.currency))
+
+
+class AsyncZarinpalClient(BaseClient):
+    __type__ = 'ASYNC'
+
+    def __init__(self, merchant_id: str, environment: Environment = Environment.PRODUCTION,
+                 config: Optional[ZarinpalConfig] = None):
+        try:
+            import aiohttp  # noqa: F401
+        except ImportError as exc:
+            raise ImportError('Install irgateway[async] for asynchronous clients') from exc
+        super().__init__(merchant_id, environment, config)
+        self._session = None
+
+    async def _ensure_session(self):
+        import aiohttp
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=self.config.timeout),
+                                                  headers={'Content-Type': 'application/json', 'Accept': 'application/json'})
+
+    async def __aenter__(self):
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()
+
+    async def close(self):
+        if self._session is not None and not self._session.closed:
+            await self._session.close()
+
+    async def _post(self, path: str, payload: dict) -> dict:
+        await self._ensure_session()
+        return await async_post(self._session, self._get_endpoint(path), payload)
+
+    async def request(self, amount: int, callback_url: str, description: str,
+                      metadata: Optional[PaymentMetadata] = None, cart_data: Optional[PaymentCartData] = None,
+                      wages: Optional[List[Wage]] = None, *, buyer_fee: int | Literal['auto'] | None = None,
+                      referrer_id: Optional[str] = None) -> PaymentRequest:
+        money(amount)
+        url(callback_url)
+        required_string(description, name='description')
+        if self.config.fee_type == 'BUYER' and buyer_fee is None:
+            buyer_fee = legacy_buyer_fee(amount, gateway='zarinpal')
+        if buyer_fee == 'auto':
+            if self.config.fee_type != 'BUYER':
+                raise ValueError('buyer_fee requires config.fee_type=BUYER')
+            buyer_fee = await self.calculate_buyer_fee(amount)
+        payload, total = self._request_payload(amount, callback_url, description, metadata, cart_data, wages, buyer_fee, referrer_id)
+        return self._remember_payment(self._request_result(await self._post('pg/v4/payment/request.json', payload), amount, total))
+
+    async def verify(self, authority: str, amount: int, *, allow_already_verified: bool = False,
+                     amount_is_rials: bool = False) -> PaymentVerification:
+        return self._verify_result(await self._post('pg/v4/payment/verify.json',
+                                                    self._verify_payload(authority, amount,
+                                                                         amount_is_rials=amount_is_rials)),
+                                   allow_already_verified)
+
+    async def unverified(self) -> UnverifiedTransactions:
+        return self._unverified_result(await self._post('pg/v4/payment/unVerified.json', {'merchant_id': self.merchant_id}))
+
+    async def reverse(self, authority: str) -> bool:
+        code, _ = self._get_response(await self._post('pg/v4/payment/reverse.json', self._payload(authority)))
+        return code == 100
+
+    async def inquiry(self, authority: str) -> PaymentStatus:
+        return self._inquiry_result(await self._post('pg/v4/payment/inquiry.json', self._payload(authority)))
+
+    async def calculate_fee(self, amount: int, *, amount_currency: str | None = None) -> FeeCalculation:
+        """Legacy direct callers supply rials by default; use amount_currency='IRT' for tomans."""
+        payload = {'merchant_id': self.merchant_id, 'amount': rial(amount, amount_currency or 'IRR')}
+        if amount_currency is not None:
+            payload['currency'] = 'IRR'
+        return self._fee_result(await self._post('pg/v4/payment/feeCalculation.json', payload))
+
+    async def calculate_buyer_fee(self, amount: int) -> int:
+        """Fetch authoritative fee quote and return the needed extra amount."""
+        money(amount)
+        return self._auto_fee_from_quote(amount, await self.calculate_fee(amount, amount_currency=self.config.currency))

irgateway/zarinpal/enums.py

@@ -0,0 +1,15 @@
+from enum import Enum
+
+
+class Environment(Enum):
+    SANDBOX = "https://sandbox.zarinpal.com/"
+    PRODUCTION = "https://payment.zarinpal.com/"
+
+
+class PaymentStatus(Enum):
+    PENDING = "PENDING"
+    VERIFIED = "VERIFIED"
+    FAILED = "FAILED"
+    REVERSED = "REVERSED"
+    IN_BANK = "IN_BANK"
+    PAID = "PAID"