paytechuz 0.2.19__py3-none-any.whl → 0.2.20__py3-none-any.whl

gateways/click/webhook.py

@@ -0,0 +1,227 @@
+"""
+Click webhook handler.
+"""
+import hashlib
+import logging
+from typing import Dict, Any, Callable
+
+from paytechuz.core.base import BaseWebhookHandler
+from paytechuz.core.constants import ClickActions
+from paytechuz.core.exceptions import (
+    PermissionDenied,
+    InvalidAmount,
+    TransactionNotFound,
+    UnsupportedMethod,
+    AccountNotFound
+)
+from paytechuz.core.utils import handle_exceptions
+
+logger = logging.getLogger(__name__)
+
+class ClickWebhookHandler(BaseWebhookHandler):
+    """
+    Click webhook handler.
+
+    This class handles webhook requests from the Click payment system,
+    including transaction preparation and completion.
+    """
+
+    def __init__(
+        self,
+        service_id: str,
+        secret_key: str,
+        find_transaction_func: Callable[[str], Dict[str, Any]],
+        find_account_func: Callable[[str], Dict[str, Any]],
+        create_transaction_func: Callable[[Dict[str, Any]], Dict[str, Any]],
+        complete_transaction_func: Callable[[str, bool], Dict[str, Any]],
+        commission_percent: float = 0.0
+    ):
+        """
+        Initialize the Click webhook handler.
+
+        Args:
+            service_id: Click service ID
+            secret_key: Secret key for authentication
+            find_transaction_func: Function to find a transaction by ID
+            find_account_func: Function to find an account by ID
+            create_transaction_func: Function to create a transaction
+            complete_transaction_func: Function to complete a transaction
+            commission_percent: Commission percentage
+        """
+        self.service_id = service_id
+        self.secret_key = secret_key
+        self.find_transaction = find_transaction_func
+        self.find_account = find_account_func
+        self.create_transaction = create_transaction_func
+        self.complete_transaction = complete_transaction_func
+        self.commission_percent = commission_percent
+
+    def _check_auth(self, params: Dict[str, Any]) -> None:
+        """
+        Check authentication using signature.
+
+        Args:
+            params: Request parameters
+
+        Raises:
+            PermissionDenied: If authentication fails
+        """
+        if str(params.get('service_id')) != self.service_id:
+            raise PermissionDenied("Invalid service ID")
+
+        # Check signature if secret key is provided
+        if self.secret_key:
+            sign_string = params.get('sign_string')
+            sign_time = params.get('sign_time')
+
+            if not sign_string or not sign_time:
+                raise PermissionDenied("Missing signature parameters")
+
+            # Create string to sign
+            to_sign = f"{params.get('click_trans_id')}{params.get('service_id')}"
+            to_sign += f"{self.secret_key}{params.get('merchant_trans_id')}"
+            to_sign += f"{params.get('amount')}{params.get('action')}"
+            to_sign += f"{sign_time}"
+
+            # Generate signature
+            signature = hashlib.md5(to_sign.encode('utf-8')).hexdigest()
+
+            if signature != sign_string:
+                raise PermissionDenied("Invalid signature")
+
+    def _validate_amount(
+        self,
+        received_amount: float,
+        expected_amount: float
+    ) -> None:
+        """
+        Validate payment amount.
+
+        Args:
+            received_amount: Amount received from Click
+            expected_amount: Expected amount
+
+        Raises:
+            InvalidAmount: If amounts don't match
+        """
+        # Add commission if needed
+        if self.commission_percent > 0:
+            expected_amount = expected_amount * (1 + self.commission_percent / 100)
+            expected_amount = round(expected_amount, 2)
+
+        # Allow small difference due to floating point precision
+        if abs(received_amount - expected_amount) > 0.01:
+            raise InvalidAmount(f"Incorrect amount. Expected: {expected_amount}, received: {received_amount}")
+
+    @handle_exceptions
+    def handle_webhook(self, data: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Handle webhook data from Click.
+
+        Args:
+            data: The webhook data received from Click
+
+        Returns:
+            Dict containing the response to be sent back to Click
+
+        Raises:
+            PermissionDenied: If authentication fails
+            UnsupportedMethod: If the requested action is not supported
+        """
+        # Check authentication
+        self._check_auth(data)
+
+        # Extract parameters
+        click_trans_id = data.get('click_trans_id')
+        merchant_trans_id = data.get('merchant_trans_id')
+        amount = float(data.get('amount', 0))
+        action = int(data.get('action', -1))
+        error = int(data.get('error', 0))
+
+        # Find account
+        try:
+            account = self.find_account(merchant_trans_id)
+        except AccountNotFound:
+            logger.error(f"Account not found: {merchant_trans_id}")
+            return {
+                'click_trans_id': click_trans_id,
+                'merchant_trans_id': merchant_trans_id,
+                'error': -5,
+                'error_note': "User not found"
+            }
+
+        # Validate amount
+        try:
+            self._validate_amount(amount, float(account.get('amount', 0)))
+        except InvalidAmount as e:
+            logger.error(f"Invalid amount: {e}")
+            return {
+                'click_trans_id': click_trans_id,
+                'merchant_trans_id': merchant_trans_id,
+                'error': -2,
+                'error_note': str(e)
+            }
+
+        # Check if transaction already exists
+        try:
+            transaction = self.find_transaction(click_trans_id)
+
+            # If transaction is already completed, return success
+            if transaction.get('state') == 2:  # SUCCESSFULLY
+                return {
+                    'click_trans_id': click_trans_id,
+                    'merchant_trans_id': merchant_trans_id,
+                    'merchant_prepare_id': transaction.get('id'),
+                    'error': 0,
+                    'error_note': "Success"
+                }
+
+            # If transaction is cancelled, return error
+            if transaction.get('state') == -2:  # CANCELLED
+                return {
+                    'click_trans_id': click_trans_id,
+                    'merchant_trans_id': merchant_trans_id,
+                    'merchant_prepare_id': transaction.get('id'),
+                    'error': -9,
+                    'error_note': "Transaction cancelled"
+                }
+        except TransactionNotFound:
+            # Transaction doesn't exist, continue with the flow
+            pass
+
+        # Handle different actions
+        if action == ClickActions.PREPARE:
+            # Create transaction
+            transaction = self.create_transaction({
+                'click_trans_id': click_trans_id,
+                'merchant_trans_id': merchant_trans_id,
+                'amount': amount,
+                'account': account
+            })
+
+            return {
+                'click_trans_id': click_trans_id,
+                'merchant_trans_id': merchant_trans_id,
+                'merchant_prepare_id': transaction.get('id'),
+                'error': 0,
+                'error_note': "Success"
+            }
+
+        elif action == ClickActions.COMPLETE:
+            # Check if error is negative (payment failed)
+            is_successful = error >= 0
+
+            # Complete transaction
+            transaction = self.complete_transaction(click_trans_id, is_successful)
+
+            return {
+                'click_trans_id': click_trans_id,
+                'merchant_trans_id': merchant_trans_id,
+                'merchant_prepare_id': transaction.get('id'),
+                'error': 0,
+                'error_note': "Success"
+            }
+
+        else:
+            logger.error(f"Unsupported action: {action}")
+            raise UnsupportedMethod(f"Unsupported action: {action}")

gateways/payme/cards.py

@@ -0,0 +1,222 @@
+"""
+Payme cards operations.
+"""
+import logging
+from typing import Dict, Any
+
+from paytechuz.core.http import HttpClient
+from paytechuz.core.constants import PaymeEndpoints
+from paytechuz.core.utils import handle_exceptions
+
+logger = logging.getLogger(__name__)
+
+class PaymeCards:
+    """
+    Payme cards operations.
+
+    This class provides methods for working with cards in the Payme payment system,
+    including creating cards, verifying cards, and removing cards.
+    """
+
+    def __init__(self, http_client: HttpClient, payme_id: str):
+        """
+        Initialize the Payme cards component.
+
+        Args:
+            http_client: HTTP client for making requests
+            payme_id: Payme merchant ID
+        """
+        self.http_client = http_client
+        self.payme_id = payme_id
+
+    @handle_exceptions
+    def create(
+        self,
+        card_number: str,
+        expire_date: str,
+        save: bool = True,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Create a new card.
+
+        Args:
+            card_number: Card number
+            expire_date: Card expiration date in format "MM/YY"
+            save: Whether to save the card for future use
+            **kwargs: Additional parameters
+                - phone: Customer phone number
+                - language: Language code (uz, ru, en)
+
+        Returns:
+            Dict containing card creation response
+        """
+        # Extract additional parameters
+        phone = kwargs.get('phone')
+        language = kwargs.get('language', 'uz')
+
+        # Prepare request data
+        data = {
+            "method": PaymeEndpoints.CARDS_CREATE,
+            "params": {
+                "card": {
+                    "number": card_number,
+                    "expire": expire_date
+                },
+                "save": save,
+                "merchant_id": self.payme_id
+            }
+        }
+
+        # Add optional parameters
+        if phone:
+            data["params"]["phone"] = phone
+
+        # Add language header
+        headers = {"Accept-Language": language}
+
+        # Make request
+        response = self.http_client.post(
+            endpoint="",
+            json_data=data,
+            headers=headers
+        )
+
+        return response
+
+    @handle_exceptions
+    def verify(
+        self,
+        token: str,
+        code: str,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Verify a card with the verification code.
+
+        Args:
+            token: Card token received from create method
+            code: Verification code sent to the card owner
+            **kwargs: Additional parameters
+                - language: Language code (uz, ru, en)
+
+        Returns:
+            Dict containing card verification response
+        """
+        # Extract additional parameters
+        language = kwargs.get('language', 'uz')
+
+        # Prepare request data
+        data = {
+            "method": PaymeEndpoints.CARDS_VERIFY,
+            "params": {
+                "token": token,
+                "code": code
+            }
+        }
+
+        # Add language header
+        headers = {"Accept-Language": language}
+
+        # Make request
+        response = self.http_client.post(
+            endpoint="",
+            json_data=data,
+            headers=headers
+        )
+
+        return response
+
+    @handle_exceptions
+    def check(self, token: str) -> Dict[str, Any]:
+        """
+        Check if a card exists and is active.
+
+        Args:
+            token: Card token
+
+        Returns:
+            Dict containing card check response
+        """
+        # Prepare request data
+        data = {
+            "method": PaymeEndpoints.CARDS_CHECK,
+            "params": {
+                "token": token
+            }
+        }
+
+        # Make request
+        response = self.http_client.post(
+            endpoint="",
+            json_data=data
+        )
+
+        return response
+
+    @handle_exceptions
+    def remove(self, token: str) -> Dict[str, Any]:
+        """
+        Remove a card.
+
+        Args:
+            token: Card token
+
+        Returns:
+            Dict containing card removal response
+        """
+        # Prepare request data
+        data = {
+            "method": PaymeEndpoints.CARDS_REMOVE,
+            "params": {
+                "token": token
+            }
+        }
+
+        # Make request
+        response = self.http_client.post(
+            endpoint="",
+            json_data=data
+        )
+
+        return response
+
+    @handle_exceptions
+    def get_verify_code(
+        self,
+        token: str,
+        **kwargs
+    ) -> Dict[str, Any]:
+        """
+        Get a new verification code for a card.
+
+        Args:
+            token: Card token
+            **kwargs: Additional parameters
+                - language: Language code (uz, ru, en)
+
+        Returns:
+            Dict containing verification code response
+        """
+        # Extract additional parameters
+        language = kwargs.get('language', 'uz')
+
+        # Prepare request data
+        data = {
+            "method": PaymeEndpoints.CARDS_GET_VERIFY_CODE,
+            "params": {
+                "token": token
+            }
+        }
+
+        # Add language header
+        headers = {"Accept-Language": language}
+
+        # Make request
+        response = self.http_client.post(
+            endpoint="",
+            json_data=data,
+            headers=headers
+        )
+
+        return response

gateways/payme/client.py

@@ -0,0 +1,262 @@
+"""
+Payme payment gateway client.
+"""
+import logging
+from typing import Dict, Any, Optional, Union
+import base64
+
+from paytechuz.core.base import BasePaymentGateway
+from paytechuz.core.http import HttpClient
+from paytechuz.core.constants import PaymeNetworks
+from paytechuz.core.utils import format_amount, handle_exceptions
+from paytechuz.gateways.payme.cards import PaymeCards
+from paytechuz.gateways.payme.receipts import PaymeReceipts
+
+logger = logging.getLogger(__name__)
+
+
+class PaymeGateway(BasePaymentGateway):
+    """
+    Payme payment gateway implementation.
+
+    This class provides methods for interacting with the Payme payment gateway,
+    including creating payments, checking payment status, and canceling payments.
+    """
+
+    def __init__(
+        self,
+        payme_id: str,
+        payme_key: Optional[str] = None,
+        fallback_id: Optional[str] = None,
+        is_test_mode: bool = False
+    ):
+        """
+        Initialize the Payme gateway.
+
+        Args:
+            payme_id: Payme merchant ID
+            payme_key: Payme merchant key for authentication
+            fallback_id: Fallback merchant ID
+            is_test_mode: Whether to use the test environment
+        """
+        super().__init__(is_test_mode)
+        self.payme_id = payme_id
+        self.payme_key = payme_key
+        self.fallback_id = fallback_id
+
+        # Set the API URL based on the environment
+        url = PaymeNetworks.TEST_NET if is_test_mode else PaymeNetworks.PROD_NET
+
+        # Initialize HTTP client
+        self.http_client = HttpClient(base_url=url)
+
+        # Initialize components
+        self.cards = PaymeCards(http_client=self.http_client, payme_id=payme_id)
+        self.receipts = PaymeReceipts(
+            http_client=self.http_client,
+            payme_id=payme_id,
+            payme_key=payme_key
+        )
+
+    def generate_pay_link(
+        self,
+        id: Union[int, str],
+        amount: Union[int, float, str],
+        return_url: str,
+        account_field_name: str = "order_id"
+    ) -> str:
+        """
+        Generate a payment link for a specific order.
+
+        Parameters
+        ----------
+        id : Union[int, str]
+            Unique identifier for the account/order.
+        amount : Union[int, float, str]
+            Payment amount in som.
+        return_url : str
+            URL to redirect after payment completion.
+        account_field_name : str, optional
+            Field name for account identifier (default: "order_id").
+
+        Returns
+        -------
+        str
+            Payme checkout URL with encoded parameters.
+
+        References
+        ----------
+        https://developer.help.paycom.uz/initsializatsiya-platezhey/
+        """
+        # Convert amount to tiyin (1 som = 100 tiyin)
+        amount_tiyin = int(float(amount) * 100)
+
+        # Build parameters
+        params = (
+            f'm={self.payme_id};'
+            f'ac.{account_field_name}={id};'
+            f'a={amount_tiyin};'
+            f'c={return_url}'
+        )
+        encoded_params = base64.b64encode(params.encode("utf-8")).decode("utf-8")
+
+        # Return URL based on environment
+        base_url = "https://test.paycom.uz" if self.is_test_mode else "https://checkout.paycom.uz"
+        return f"{base_url}/{encoded_params}"
+
+    async def generate_pay_link_async(
+        self,
+        id: Union[int, str],
+        amount: Union[int, float, str],
+        return_url: str,
+        account_field_name: str = "order_id"
+    ) -> str:
+        """
+        Async version of generate_pay_link.
+
+        Parameters
+        ----------
+        id : Union[int, str]
+            Unique identifier for the account/order.
+        amount : Union[int, float, str]
+            Payment amount in som.
+        return_url : str
+            URL to redirect after payment completion.
+        account_field_name : str, optional
+            Field name for account identifier (default: "order_id").
+
+        Returns
+        -------
+        str
+            Payme checkout URL with encoded parameters.
+        """
+        return self.generate_pay_link(
+            id=id,
+            amount=amount,
+            return_url=return_url,
+            account_field_name=account_field_name
+        )
+
+    @handle_exceptions
+    def create_payment(
+        self,
+        id: Union[int, str],
+        amount: Union[int, float, str],
+        return_url: str = "",
+        account_field_name: str = "order_id"
+    ) -> str:
+        """
+        Create a payment using Payme.
+
+        Args:
+            id: Account or order ID
+            amount: Payment amount in som
+            return_url: Return URL after payment (default: "")
+            account_field_name: Field name for account ID (default: "order_id")
+
+        Returns:
+            str: Payme payment URL
+        """
+        return self.generate_pay_link(
+            id=id,
+            amount=amount,
+            return_url=return_url,
+            account_field_name=account_field_name
+        )
+
+    @handle_exceptions
+    async def create_payment_async(
+        self,
+        id: Union[int, str],
+        amount: Union[int, float, str],
+        return_url: str = "",
+        account_field_name: str = "order_id"
+    ) -> str:
+        """
+        Async version of create_payment.
+
+        Args:
+            id: Account or order ID
+            amount: Payment amount in som
+            return_url: Return URL after payment (default: "")
+            account_field_name: Field name for account ID (default: "order_id")
+
+        Returns:
+            str: Payme payment URL
+        """
+        return await self.generate_pay_link_async(
+            id=id,
+            amount=amount,
+            return_url=return_url,
+            account_field_name=account_field_name
+        )
+
+    @handle_exceptions
+    def check_payment(self, transaction_id: str) -> Dict[str, Any]:
+        """
+        Check payment status using Payme receipts.
+
+        Args:
+            transaction_id: The receipt ID to check
+
+        Returns:
+            Dict containing payment status and details
+        """
+        receipt_data = self.receipts.check(receipt_id=transaction_id)
+
+        # Extract receipt status
+        receipt = receipt_data.get('receipt', {})
+        status = receipt.get('state')
+
+        # Map Payme status to our status
+        status_mapping = {
+            0: 'created',
+            1: 'waiting',
+            2: 'paid',
+            3: 'cancelled',
+            4: 'refunded'
+        }
+
+        mapped_status = status_mapping.get(status, 'unknown')
+
+        return {
+            'transaction_id': transaction_id,
+            'status': mapped_status,
+            'amount': receipt.get('amount') / 100,  # Convert from tiyin to som
+            'paid_at': receipt.get('pay_time'),
+            'created_at': receipt.get('create_time'),
+            'cancelled_at': receipt.get('cancel_time'),
+            'raw_response': receipt_data
+        }
+
+    @handle_exceptions
+    def cancel_payment(
+        self,
+        transaction_id: str,
+        reason: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Cancel payment using Payme receipts.
+
+        Args:
+            transaction_id: The receipt ID to cancel
+            reason: Optional reason for cancellation
+
+        Returns:
+            Dict containing cancellation status and details
+        """
+        receipt_data = self.receipts.cancel(
+            receipt_id=transaction_id,
+            reason=reason or "Cancelled by merchant"
+        )
+
+        # Extract receipt status
+        receipt = receipt_data.get('receipt', {})
+        status = receipt.get('state')
+
+        return {
+            'transaction_id': transaction_id,
+            'status': 'cancelled' if status == 3 else 'unknown',
+            'cancelled_at': receipt.get('cancel_time'),
+            'raw_response': receipt_data
+        }