payme-pkg 2.6.7__py3-none-any.whl → 3.0.17__py3-none-any.whl

payme/classes/receipts.py

@@ -0,0 +1,298 @@
+from typing import Union, Optional
+
+from payme.classes.cards import Cards
+from payme.classes.http import HttpClient
+from payme.types.response import receipts as response
+
+
+ALLOWED_METHODS = {
+    "receipts.create": response.CreateResponse,
+    "receipts.pay": response.PayResponse,
+    "receipts.send": response.SendResponse,
+    "receipts.cancel": response.CancelResponse,
+    "receipts.check": response.CheckResponse,
+    "receipts.get": response.GetResponse,
+    "receipts.get_all": response.GetAllResponse,
+}
+
+
+class Receipts:
+    """
+    The Receipts class provides methods to interact with the Payme Receipts.
+    """
+    def __init__(self, payme_id: str, payme_key: str, url: str) -> "Receipts":
+        """
+        Initialize the Receipts client.
+
+        :param payme_id: The Payme ID associated with your account.
+        :param payme_key: The Payme API key associated with your account.
+        :param url: The base URL for the Payme Receipts API.
+        """
+        self.__cards = Cards(url, payme_id)
+
+        headers = {
+            "X-Auth": f"{payme_id}:{payme_key}",
+            "Content-Type": "application/json"
+        }
+        self.http = HttpClient(url, headers)
+
+    def create(
+        self,
+        account: dict,
+        amount: Union[float, int],
+        description: Optional[str] = None,
+        detail: Optional[dict] = None,
+        timeout: int = 10
+    ) -> response.CreateResponse:
+        """
+        Create a new receipt.
+
+        :param account: The account details for the receipt.
+        :param amount: The amount of the receipt.
+        :param description: Optional description for the receipt.
+        :param detail: Optional additional details for the receipt.
+        :param timeout: The request timeout duration in seconds (default 10).
+        """
+        method = "receipts.create"
+        params = {
+            "amount": amount,
+            "account": account,
+            "description": description,
+            "detail": detail
+        }
+        return self._post_request(method, params, timeout)
+
+    def pay(
+        self, receipts_id: str, token: str, timeout: int = 10
+    ) -> response.PayResponse:
+        """
+        Pay the receipt using a cheque.
+
+        :param receipts_id: The ID of the cheque used for payment.
+        :param token: The token associated with the cheque.
+        :param timeout:
+            The request timeout duration in seconds (default is 10).
+        """
+        method = "receipts.pay"
+        params = {
+            "id": receipts_id,
+            "token": token
+        }
+        return self._post_request(method, params, timeout)
+
+    def send(
+        self, receipts_id: str, phone: str, timeout: int = 10
+    ) -> response.SendResponse:
+        """
+        Send the receipt to a mobile phone.
+
+        :param receipts_id: The ID of the cheque used for payment.
+        :param phone: The phone number to send the receipt to.
+        :param timeout: The request timeout duration in seconds (default 10).
+        """
+        method = "receipts.send"
+        params = {
+            "id": receipts_id,
+            "phone": phone
+        }
+        return self._post_request(method, params, timeout)
+
+    def cancel(
+        self, receipts_id: str, timeout: int = 10
+    ) -> response.CancelResponse:
+        """
+        Cancel the receipt.
+
+        :param receipts_id: The ID of the cheque used for payment.
+        :param timeout: The request timeout duration in seconds (default 10).
+        """
+        method = "receipts.cancel"
+        params = {
+            "id": receipts_id
+        }
+        return self._post_request(method, params, timeout)
+
+    def check(
+        self, receipts_id: str, timeout: int = 10
+    ) -> response.CheckResponse:
+        """
+        Check the status of a cheque.
+
+        :param receipts_id: The ID of the cheque used for payment.
+        :param timeout: The request timeout duration in seconds (default 10).
+        """
+        method = "receipts.check"
+        params = {
+            "id": receipts_id
+        }
+        return self._post_request(method, params, timeout)
+
+    def get(
+        self, receipts_id: str, timeout: int = 10
+    ) -> response.GetResponse:
+        """
+        Get the details of a specific cheque.
+
+        :param receipts_id: The ID of the cheque used for payment.
+        :param timeout: The request timeout duration in seconds (default 10).
+        """
+        method = "receipts.get"
+        params = {
+            "id": receipts_id
+        }
+        return self._post_request(method, params, timeout)
+
+    def get_all(
+        self, count: int, from_: int, to: int, offset: int, timeout: int = 10
+    ) -> response.GetAllResponse:
+        """
+        Get all cheques for a specific account.
+
+        :param count: The number of cheques to retrieve.
+        :param from_: The start index of the cheques to retrieve.
+        :param to: The end index of the cheques to retrieve.
+        :param offset: The offset for pagination.
+       :param timeout: The request timeout duration in seconds (default 10).
+        """
+        method = "receipts.get_all"
+        params = {
+            "count": count,
+            "from": from_,
+            "to": to,
+            "offset": offset
+        }
+        return self._post_request(method, params, timeout)
+
+    def _post_request(
+        self, method: str, params: dict, timeout: int = 10
+    ) -> response.Common:
+        """
+        Helper method to post requests to the HTTP client.
+
+        :param method: The API method to be called.
+        :param params: The parameters to be sent with the request.
+        :param timeout: The request timeout duration in seconds (default 10).
+        :return: A response object corresponding to the method called.
+        """
+        json = {"method": method, "params": params}
+        dict_result = self.http.post(json, timeout)
+        response_class = ALLOWED_METHODS[method]
+        return response_class.from_dict(dict_result)
+
+    def test(self):
+        """
+        Run a comprehensive suite of tests for the Receipts class,
+        covering creation, payment, sending, cancellation, status checks,
+        retrieval of a single receipt, and retrieval of multiple receipts.
+        """
+        # Helper to assert conditions with messaging
+        def assert_condition(condition, message, test_case):
+            self._assert_and_print(condition, message, test_case=test_case)
+
+        # Helper to create a receipt for reuse
+        def create_sample_receipt():
+            return self.create(
+                account={"id": 12345},
+                amount=1000,
+                description="Test receipt",
+                detail={"key": "value"}
+            )
+
+        # Test 1: Initialization check
+        assert_condition(
+            isinstance(self, Receipts),
+            "Initialized Receipts class successfully.",
+            test_case="Initialization Test"
+        )
+
+        # Test 2: Create and Pay Receipt
+        create_response = create_sample_receipt()
+        assert_condition(
+            isinstance(create_response, response.CreateResponse),
+            "Created a new receipt successfully.",
+            test_case="Receipt Creation Test"
+        )
+
+        # pylint: disable=W0212
+        assert_condition(
+            isinstance(create_response.result.receipt._id, str),
+            "Created a valid receipt ID.",
+            test_case="Receipt ID Test"
+        )
+
+        # Prepare card and verification
+        cards_create_response = self.__cards.create(
+            number="8600495473316478",
+            expire="0399",
+            save=True
+        )
+        token = cards_create_response.result.card.token
+        self.__cards.get_verify_code(token=token)
+        self.__cards.verify(token=token, code="666666")
+
+        # Pay receipt and verify payment state
+        receipt_id = create_response.result.receipt._id
+        pay_response = self.pay(receipts_id=receipt_id, token=token)
+        assert_condition(
+            pay_response.result.receipt.state == 4,
+            "Paid the receipt successfully.",
+            test_case="Payment Test"
+        )
+
+        # Test 3: Create and Send Receipt
+        create_response = create_sample_receipt()
+        receipt_id = create_response.result.receipt._id
+        send_response = self.send(receipts_id=receipt_id, phone="998901304527")
+        assert_condition(
+            send_response.result.success is True,
+            "Sent the receipt successfully.",
+            test_case="Send Test"
+        )
+
+        # Test 4: Create and Cancel Receipt
+        create_response = create_sample_receipt()
+        receipt_id = create_response.result.receipt._id
+        cancel_response = self.cancel(receipts_id=receipt_id)
+        assert_condition(
+            cancel_response.result.receipt.state == 50,
+            "Cancelled the receipt successfully.",
+            test_case="Cancel Test"
+        )
+
+        # Test 5: Check Receipt Status
+        check_response = self.check(receipts_id=receipt_id)
+        assert_condition(
+            check_response.result.state == 50,
+            "Checked the receipt status successfully.",
+            test_case="Check Test"
+        )
+
+        # Test 6: Get Receipt Details
+        get_response = self.get(receipts_id=receipt_id)
+        assert_condition(
+            get_response.result.receipt._id == receipt_id,
+            "Retrieved the receipt details successfully.",
+            test_case="Get Test"
+        )
+
+        # Test 7: Retrieve All Receipts
+        get_all_response = self.get_all(
+            count=1,
+            from_=1730322122000,
+            to=1730398982000,
+            offset=0
+        )
+        assert_condition(
+            isinstance(get_all_response.result, list),
+            "Retrieved all receipts successfully.",
+            test_case="Get All Test"
+        )
+
+    # pylint: disable=W0212
+    def _assert_and_print(
+        self,
+        condition: bool,
+        success_message: str,
+        test_case: Optional[str] = None
+    ):
+        self.__cards._assert_and_print(condition, success_message, test_case)

payme/const.py

@@ -0,0 +1,12 @@
+"""
+Payme enumerations
+"""
+from enum import Enum
+
+
+class Networks(str, Enum):
+    """
+    Payme networks
+    """
+    PROD_NET = "https://checkout.paycom.uz/api"
+    TEST_NET = "https://checkout.test.paycom.uz/api"

payme/exceptions/__init__.py

@@ -0,0 +1,5 @@
+"""
+init all payme exceptions
+"""
+from .general import * # noqa
+from .webhook import * # noqa

payme/exceptions/general.py

@@ -0,0 +1,275 @@
+import logging
+
+
+class BaseError(Exception):
+    """Base class for all errors in the payment system."""
+    logger = logging.getLogger(__name__)
+
+    def __init__(self, code, message, data=None):
+        super().__init__(message)
+        self.code = code
+        self.data = data
+
+        # pylint: disable=W1203
+        self.logger.error(f"Error {code}: {message}. Data: {data}")
+
+
+class CardError(BaseError):
+    """Base class for card-related errors."""
+
+
+class TransportError(CardError):
+    """Transport error occurred during card operation."""
+    message = "Transport error."
+
+    def __init__(self, data=None):
+        super().__init__(-32300, self.message, data)
+
+
+class ParseError(CardError):
+    """Parse error occurred during card operation."""
+    message = "Parse error."
+
+    def __init__(self, data=None):
+        super().__init__(-32700, self.message, data)
+
+
+class InvalidRequestError(CardError):
+    """Invalid request made during card operation."""
+    message = "Invalid Request."
+
+    def __init__(self, data=None):
+        super().__init__(-32600, self.message, data)
+
+
+class InvalidResponseError(CardError):
+    """Invalid response received during card operation."""
+    message = "Invalid Response."
+
+    def __init__(self, data=None):
+        super().__init__(-32600, self.message, data)
+
+
+class SystemError(CardError):
+    """System error occurred during card operation."""
+    message = "System error."
+
+    def __init__(self, data=None):
+        super().__init__(-32400, self.message, data)
+
+
+class MethodNotFoundError(CardError):
+    """Method not found during card operation."""
+    message = "Method not found."
+
+    def __init__(self, data=None):
+        super().__init__(-32601, self.message, data)
+
+
+class InvalidParamsError(CardError):
+    """Invalid parameters provided during card operation."""
+    message = "Invalid Params."
+
+    def __init__(self, data=None):
+        super().__init__(-32602, self.message, data)
+
+
+class InvalidTokenFormat(CardError):
+    """Invalid token format during card operation."""
+    message = "Invalid token format."
+
+    def __init__(self, data=None):
+        super().__init__(-32500, self.message, data)
+
+
+class AccessDeniedError(CardError):
+    """Access denied for the card operation."""
+    message = "Access denied."
+
+    def __init__(self, data=None):
+        super().__init__(-32504, self.message, data)
+
+
+class CardNotFoundError(CardError):
+    """Card not found during operation."""
+    message = "Card not found."
+
+    def __init__(self, data=None):
+        super().__init__(-31400, self.message, data)
+
+
+class SmsNotConnectedError(CardError):
+    """SMS notification not connected."""
+    message = "SMS notification not connected."
+
+    def __init__(self, data=None):
+        super().__init__(-31301, self.message, data)
+
+
+class CardExpiredError(CardError):
+    """Card has expired."""
+    message = "Card has expired."
+
+    def __init__(self, data=None):
+        super().__init__(-31301, self.message, data)
+
+
+class CardBlockedError(CardError):
+    """Card is blocked."""
+    message = "Card is blocked."
+
+    def __init__(self, data=None):
+        super().__init__(-31301, self.message, data)
+
+
+class CorporateCardError(CardError):
+    """Financial operations with corporate cards are not allowed."""
+    message = "Financial operations with corporate cards are not allowed."
+
+    def __init__(self, data=None):
+        super().__init__(-31300, self.message, data)
+
+
+class BalanceError(CardError):
+    """Unable to retrieve card balance. Please try again later."""
+    message = "Unable to retrieve card balance. Please try again later."
+
+    def __init__(self, data=None):
+        super().__init__(-31302, self.message, data)
+
+
+class InsufficientFundsError(CardError):
+    """Insufficient funds on the card."""
+    message = "Insufficient funds on the card."
+
+    def __init__(self, data=None):
+        super().__init__(-31303, self.message, data)
+
+
+class InsufficientFundsErrorV2(CardError):
+    """Insufficient funds on the card."""
+    message = "Insufficient funds on the card."
+
+    def __init__(self, data=None):
+        super().__init__(-31630, self.message, data)
+
+
+class InvalidCardNumberError(CardError):
+    """Invalid card number provided."""
+    message = "Invalid card number."
+
+    def __init__(self, data=None):
+        super().__init__(-31300, self.message, data)
+
+
+class CardNotFoundWithNumberError(CardError):
+    """Card with the provided number not found."""
+    message = "Card with this number not found."
+
+    def __init__(self, data=None):
+        super().__init__(-31300, self.message, data)
+
+
+class InvalidExpiryDateError(CardError):
+    """Invalid expiry date provided for the card."""
+    message = "Invalid expiry date for the card."
+
+    def __init__(self, data=None):
+        super().__init__(-31300, self.message, data)
+
+
+class ProcessingServerError(CardError):
+    """Processing center server is unavailable. Please try again later."""
+    message = \
+        "Processing center server is unavailable. Please try again later."
+
+    def __init__(self, data=None):
+        super().__init__(-31002, self.message, data)
+
+
+# OTP Module Errors
+
+class OtpError(BaseError):
+    """Base class for OTP-related errors."""
+
+
+class OtpSendError(OtpError):
+    """Error occurred while sending OTP."""
+    message = "Error occurred while sending SMS. Please try again."
+
+    def __init__(self, data=None):
+        super().__init__(-31110, self.message, data)
+
+
+class OtpCheckError(OtpError):
+    """Base class for OTP check errors."""
+
+
+class OtpExpiredError(OtpCheckError):
+    """OTP code has expired. Request a new code."""
+    message = "OTP code has expired. Request a new code."
+
+    def __init__(self, data=None):
+        super().__init__(-31101, self.message, data)
+
+
+class OtpAttemptsExceededError(OtpCheckError):
+    """
+    Number of attempts to enter the code has been exceeded. Request a new code.
+    """
+    message = "Number of attempts to enter the code has been exceeded."
+
+    def __init__(self, data=None):
+        super().__init__(-31102, self.message, data)
+
+
+class OtpInvalidCodeError(OtpCheckError):
+    """Invalid OTP code entered."""
+    message = "Invalid OTP code."
+
+    def __init__(self, data=None):
+        super().__init__(-31103, self.message, data)
+
+
+class PaymeNetworkError(BaseError):
+    """Network error occurred during request to Payme server."""
+    message = "Network error occurred during request to Payme server."
+
+    def __init__(self, data=None):
+        super().__init__(self.message, data)
+
+
+class ReceiptsNotFoundError(BaseException):
+    """No receipts found for the given transaction ID."""
+    def __init__(self, message="No receipts found for the given transaction ID.", data=None):
+        super().__init__(message, data)
+
+
+class UnknownPartnerError(BaseException):
+    """The given partner ID is unknown."""
+    def __init__(self, message="Unknown partner or ID and Key not active", data=None):
+        super().__init__(message, data)
+
+
+errors_map = {
+    -32300: TransportError,
+    -32700: ParseError,
+    -32600: InvalidRequestError,
+    -32601: MethodNotFoundError,
+    -32602: InvalidParamsError,
+    -32504: AccessDeniedError,
+    -31400: CardNotFoundError,
+    -31301: SmsNotConnectedError,
+    -31302: BalanceError,
+    -31303: InsufficientFundsError,
+    -31630: InsufficientFundsErrorV2,
+    -31300: InvalidCardNumberError,
+    -31002: ProcessingServerError,
+    -31110: OtpSendError,
+    -31101: OtpExpiredError,
+    -31102: OtpAttemptsExceededError,
+    -31103: OtpInvalidCodeError,
+    -31602: ReceiptsNotFoundError,
+    -32500: InvalidTokenFormat,
+    -31601: UnknownPartnerError,
+}