tappay 0.5.0__py3-none-any.whl

tappay/__init__.py

@@ -0,0 +1,16 @@
+
+__version__ = "0.5.0"
+
+from tappay.client import Client
+from tappay.models import Models
+from tappay.exceptions import Exceptions, Error, ClientError, ServerError, AuthenticationError
+
+__all__ = [
+    "Client",
+    "Models",
+    "Exceptions",
+    "Error",
+    "ClientError",
+    "ServerError",
+    "AuthenticationError",
+]

tappay/client.py

@@ -0,0 +1,303 @@
+import logging
+import os
+from platform import python_version
+from typing import Optional, Dict, Any, Union
+
+import requests
+
+from tappay.models import Models
+from tappay.exceptions import Exceptions
+
+logger = logging.getLogger(__name__)
+
+# We need to access __version__ from somewhere, commonly from a package level or hardcoded here then imported.
+# For now I will hardcode it here or pass it in.
+# Better yet, I will define __version__ in __init__.py and import it here? No, circular import.
+# I will put __version__ in a separate file or keep it in __init__ and pass it to Client if needed,
+# or just duplicate/move it.
+# Let's define it in client.py for now to avoid circular dependency if __init__ imports client.
+# Actually, the original code used it in User-Agent.
+VERSION = "0.5.0"
+
+
+class Client:
+    """Client for interacting with the TapPay API."""
+
+    def __init__(
+        self,
+        is_sandbox: bool,
+        partner_key: Optional[str] = None,
+        merchant_id: Optional[str] = None,
+        app_name: Optional[str] = None,
+        app_version: Optional[str] = None,
+    ):
+        """
+        Create a Client object to start making calls to TapPay APIs.
+
+        :param bool is_sandbox: Define runtime environment (sandbox or production)
+        :param str partner_key: Your TapPay partner key (optional)
+        :param str merchant_id: Your TapPay merchant ID (optional)
+        :param str app_name: This optional value is added to the user-agent header
+        :param str app_version: This optional value is added to the user-agent header
+        """
+        if not isinstance(is_sandbox, bool):
+            raise TypeError(
+                f"expected bool for parameter `is_sandbox`, {type(is_sandbox)} found"
+            )
+
+        self.partner_key = partner_key or os.environ.get("TAPPAY_PARTNER_KEY")
+        self.merchant_id = merchant_id or os.environ.get("TAPPAY_MERCHANT_ID")
+
+        if self.partner_key is None:
+            raise ValueError("Missing required value for `partner_key`")
+        if self.merchant_id is None:
+            raise ValueError("Missing required value for `merchant_id`")
+
+        subdomain = "sandbox" if is_sandbox else "prod"
+        self.api_host = f"{subdomain}.tappaysdk.com"
+
+        user_agent = f"tappay-python/{VERSION} python/{python_version()}"
+
+        if app_name and app_version:
+            user_agent += f" {app_name}/{app_version}"
+
+        self.headers = {
+            "Content-Type": "application/json",
+            "User-Agent": user_agent,
+            "x-api-key": self.partner_key,
+        }
+
+    def pay_by_prime(
+        self,
+        prime: str,
+        amount: int,
+        details: str,
+        card_holder_data: Models.CardHolderData,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """
+        Make a payment using "prime" obtained from TapPay frontend SDK
+        Ref: https://docs.tappaysdk.com/tutorial/zh/back.html#pay-by-prime-api
+        """
+        if not isinstance(card_holder_data, Models.CardHolderData):
+            raise TypeError(
+                f"expected `CardHolderData` type for parameter `card_holder_data`, {type(card_holder_data)} found"
+            )
+
+        params = {
+            "prime": prime,
+            "amount": amount,
+            "currency": Models.Currencies.TWD,
+            "details": details,
+            "cardholder": card_holder_data.to_dict(),
+        }
+
+        if kwargs:
+            params.update(**kwargs)
+
+        return self.__post_with_partner_key_and_merchant_id(
+            "/tpc/payment/pay-by-prime", params
+        )
+
+    def pay_by_token(
+        self,
+        card_key: str,
+        card_token: str,
+        amount: int,
+        details: str,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """
+        Make a payment using previously obtained card secrets (key & token)
+        Ref: https://docs.tappaysdk.com/tutorial/zh/back.html#pay-by-card-token-api
+        """
+        params = {
+            "card_key": card_key,
+            "card_token": card_token,
+            "amount": amount,
+            "currency": Models.Currencies.TWD,
+            "details": details,
+        }
+
+        if kwargs:
+            params.update(**kwargs)
+
+        return self.__post_with_partner_key_and_merchant_id(
+            "/tpc/payment/pay-by-token", params
+        )
+
+    def refund(
+        self, rec_trade_id: str, amount: int, **kwargs: Any
+    ) -> Dict[str, Any]:
+        """
+        Refund a payment
+        Ref: https://docs.tappaysdk.com/tutorial/zh/back.html#refund-api
+        """
+        params = {
+            "rec_trade_id": rec_trade_id,
+            "amount": amount,
+        }
+
+        if kwargs:
+            params.update(**kwargs)
+
+        return self.__post_with_partner_key("/tpc/transaction/refund", params)
+
+    def get_records(
+        self,
+        filters_dict: Dict[str, Any],
+        page: int = 0,
+        records_per_page: int = 50,
+        order_by_dict: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Query historical records
+        Ref: https://docs.tappaysdk.com/tutorial/zh/back.html#record-api
+        """
+        params = {
+            "records_per_page": records_per_page,
+            "page": page,
+            "filters": filters_dict,
+        }
+
+        if order_by_dict:
+            params["order_by"] = order_by_dict
+
+        return self.__post_with_partner_key("/tpc/transaction/query", params)
+
+    def capture_today(self, rec_trade_id: str) -> Dict[str, Any]:
+        """
+        Capture specific payment record
+        Ref: https://docs.tappaysdk.com/tutorial/zh/advanced.html#cap-today-api
+        """
+        params = {
+            "rec_trade_id": rec_trade_id,
+        }
+
+        return self.__post_with_partner_key("/tpc/transaction/cap", params)
+
+    def cancel_capture(self, rec_trade_id: str) -> Dict[str, Any]:
+        """
+        Cancel a specific capture
+        Ref: https://docs.tappaysdk.com/tutorial/zh/advanced.html#cap-cancel-api
+        """
+        params = {
+            "rec_trade_id": rec_trade_id,
+        }
+
+        return self.__post_with_partner_key("/tpc/transaction/cap/cancel", params)
+
+    def get_trade_history(self, rec_trade_id: str) -> Dict[str, Any]:
+        """
+        Get record and status of a specific transaction
+        Ref: https://docs.tappaysdk.com/tutorial/zh/advanced.html#trade-history-api
+        """
+        params = {
+            "rec_trade_id": rec_trade_id,
+        }
+
+        return self.__post_with_partner_key(
+            "/tpc/transaction/trade-history", params
+        )
+
+    def bind_card(
+        self,
+        prime: str,
+        card_holder_data: Models.CardHolderData,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        """
+        Bind new credit card
+        Ref: https://docs.tappaysdk.com/tutorial/zh/advanced.html#bind-card-api
+        """
+        if not isinstance(card_holder_data, Models.CardHolderData):
+            raise TypeError(
+                f"expected `CardHolderData` type for parameter `card_holder_data`, {type(card_holder_data)} found"
+            )
+
+        params = {
+            "prime": prime,
+            "currency": Models.Currencies.TWD,
+            "cardholder": card_holder_data.to_dict(),
+        }
+
+        if kwargs:
+            params.update(**kwargs)
+
+        return self.__post_with_partner_key_and_merchant_id(
+            "/tpc/card/bind", params
+        )
+
+    def remove_card(self, card_key: str, card_token: str) -> Dict[str, Any]:
+        """
+        Remove bound credit card
+        Ref: https://docs.tappaysdk.com/tutorial/zh/advanced.html#remove-card-api
+        """
+        params = {
+            "card_key": card_key,
+            "card_token": card_token,
+        }
+
+        return self.__post_with_partner_key("/tpc/card/remove", params)
+
+    def cancel_refund(
+        self, rec_trade_id: str, **kwargs: Any
+    ) -> Dict[str, Any]:
+        """
+        Cancel a single refund
+        Ref: https://docs.tappaysdk.com/tutorial/zh/advanced.html#refund-cancel-api
+        """
+        params = {
+            "rec_trade_id": rec_trade_id,
+        }
+
+        if kwargs:
+            params.update(**kwargs)
+
+        return self.__post_with_partner_key(
+            "/tpc/transaction/refund/cancel", params
+        )
+
+    def __post_with_partner_key(
+        self, request_uri: str, params: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        params = dict(params, partner_key=self.partner_key)
+        return self.__post(request_uri, params)
+
+    def __post_with_partner_key_and_merchant_id(
+        self, request_uri: str, params: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        params = dict(params, merchant_id=self.merchant_id)
+        return self.__post_with_partner_key(request_uri, params)
+
+    def __post(self, request_uri: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        uri = f"https://{self.api_host}{request_uri}"
+        params = dict(params)
+
+        logger.debug(f"POST to: {uri}")
+        logger.debug(f"POST headers: {self.headers}")
+        logger.debug(f"POST params: {params}")
+
+        response = requests.post(uri, json=params, headers=self.headers)
+        return self.__parse(response)
+
+    def __parse(self, response: requests.Response) -> Optional[Dict[str, Any]]:
+        logger.debug(f"response status: {response.status_code}")
+        logger.debug(f"response content: {response.content}")
+
+        if response.status_code == 401:
+            raise Exceptions.AuthenticationError
+        elif response.status_code == 204:
+            return None
+        elif 200 <= response.status_code < 300:
+            return response.json()
+        elif 400 <= response.status_code < 500:
+            message = f"{response.status_code} response from {self.api_host}"
+            raise Exceptions.ClientError(message)
+        elif 500 <= response.status_code < 600:
+            message = f"{response.status_code} response from {self.api_host}"
+            raise Exceptions.ServerError(message)
+        
+        # Fallback for unexpected status codes
+        message = f"Unexpected status code {response.status_code} from {self.api_host}"
+        raise Exceptions.ServerError(message)

tappay/exceptions.py

@@ -0,0 +1,19 @@
+
+class Error(Exception):
+    """Base exception for all TapPay errors."""
+    pass
+
+
+class ClientError(Error):
+    """Error raised when the client sends an invalid request."""
+    pass
+
+
+class ServerError(Error):
+    """Error raised when the TapPay server encounters an issue."""
+    pass
+
+
+class AuthenticationError(ClientError):
+    """Error raised when authentication fails."""
+    pass

tappay/models.py

@@ -0,0 +1,50 @@
+from typing import Optional, Dict, Any
+
+class Models:
+    """Namespace for TapPay models."""
+
+    class Currencies:
+        """Currency constants."""
+        TWD = "TWD"
+
+    class CardHolderData:
+        """Card holder data model."""
+
+        phone_number: Optional[str] = None
+        name: Optional[str] = None
+        email: Optional[str] = None
+        zip_code: Optional[str] = None
+        address: Optional[str] = None
+        national_id: Optional[str] = None
+
+        def __init__(
+            self,
+            phone_number: str,
+            name: str,
+            email: str,
+            zip_code: Optional[str] = None,
+            address: Optional[str] = None,
+            national_id: Optional[str] = None,
+        ):
+            self.phone_number = phone_number
+            self.name = name
+            self.email = email
+            self.zip_code = zip_code
+            self.address = address
+            self.national_id = national_id
+
+        def to_dict(self) -> Dict[str, Any]:
+            result_dict = {
+                "phone_number": self.phone_number,
+                "name": self.name,
+                "email": self.email,
+            }
+
+            if self.zip_code:
+                result_dict["zip_code"] = self.zip_code
+            if self.address:
+                result_dict["address"] = self.address
+            if self.national_id:
+                result_dict["national_id"] = self.national_id
+
+            return result_dict

tappay-0.5.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: tappay
+Version: 0.5.0
+Summary: TapPay Client Library for Python
+Author-email: Shih Wei Chris Lo <shihwei@gmail.com>
+Project-URL: Homepage, https://github.com/shihweilo/tappay-python
+Project-URL: Bug Tracker, https://github.com/shihweilo/tappay-python/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: requests>=2.4.2
+Dynamic: license-file
+
+
+# TapPay Python SDK
+
+![CI](https://github.com/shihweilo/tappay-python/workflows/CI/badge.svg)
+[![PyPI version](https://badge.fury.io/py/tappay.svg)](https://badge.fury.io/py/tappay)
+[![Python Versions](https://img.shields.io/pypi/pyversions/tappay.svg)](https://pypi.org/project/tappay/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> [!IMPORTANT]
+> **Python 2 Support Dropped**: As of version 0.5.0, this library no longer supports Python 2.7. Please use Python 3.8 or newer.
+
+This is the unofficial Python client library for TapPay's Backend API. To use it you'll need a TapPay account. Sign up at [tappaysdk.com](https://www.tappaysdk.com).
+
+## Installation
+
+Install using pip:
+
+```bash
+pip install tappay
+```
+
+## Usage
+
+### Initialization
+
+```python
+import tappay
+
+# Initialize the client
+client = tappay.Client(
+    is_sandbox=True, 
+    partner_key="YOUR_PARTNER_KEY", 
+    merchant_id="YOUR_MERCHANT_ID"
+)
+```
+
+For production, you can set `TAPPAY_PARTNER_KEY` and `TAPPAY_MERCHANT_ID` environment variables and omit them in the constructor:
+
+```python
+client = tappay.Client(is_sandbox=False)
+```
+
+### Pay by Prime
+
+```python
+# Create cardholder data
+card_holder = tappay.Models.CardHolderData(
+    phone_number="0912345678",
+    name="Wang Xiao Ming",
+    email="test@example.com"
+)
+
+# Make payment
+response = client.pay_by_prime(
+    prime="prime_token_from_frontend",
+    amount=100,
+    details="Order #123",
+    card_holder_data=card_holder
+)
+print(response)
+```
+
+### Pay by Token
+
+```python
+response = client.pay_by_token(
+    card_key="card_key",
+    card_token="card_token",
+    amount=100,
+    details="Subscription"
+)
+```
+
+### Refunds
+
+```python
+response = client.refund(
+    rec_trade_id="rec_trade_id",
+    amount=100
+)
+```
+
+For more API details, please refer to the [TapPay Backend API Documentation](https://docs.tappaysdk.com/tutorial/zh/back.html).
+
+## Development
+
+### Setup
+
+```bash
+git clone https://github.com/shihweilo/tappay-python.git
+cd tappay-python
+pip install -e ".[dev]"
+```
+
+### Testing
+
+Run tests using pytest:
+
+```bash
+pytest
+```
+
+## Contributing
+
+Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

tappay-0.5.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+tappay/__init__.py,sha256=CFV-ZoZJR5DKe-vfABPMQOTLYQaYEfaJyOGZFpyqGV0,324
+tappay/client.py,sha256=8j_1yCGK5ZF3Eaqb1bn78dqgDw54As861HrRfNSVbbE,10131
+tappay/exceptions.py,sha256=_kfkoAuvsLVehkIZ4ucOu8zVWCB4PBTikmm8YgBmcik,389
+tappay/models.py,sha256=F364tteyUNB3ZBnBKgOOPwMv26BxVNoUOXQlaRIWS54,1461
+tappay-0.5.0.dist-info/licenses/LICENSE.txt,sha256=CpgTk30a7F04kGiQypkY-PXWUWAKwbzrE7qTO93roxE,1084
+tappay-0.5.0.dist-info/METADATA,sha256=4hVfermPUwkV7sWk6PKYEgOqmIhRoBv4AfgGBdxhR1E,3324
+tappay-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+tappay-0.5.0.dist-info/top_level.txt,sha256=GZaMpi1PiPG4IbGyB3mN0M0L-pNZDuaUTP3-5u8QQ3E,7
+tappay-0.5.0.dist-info/RECORD,,

tappay-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tappay-0.5.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,24 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Shih Wei Chris Lo
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

tappay-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tappay