tingee-sdk 0.4.0__tar.gz

tingee_sdk-0.4.0/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: tingee-sdk
+Version: 0.4.0
+Summary: Tingee Open API SDK for Python
+Author-email: Tingee <developer@heno.vn>
+License: ISC
+Project-URL: Homepage, https://developers.tingee.vn
+Project-URL: Documentation, https://developers.tingee.vn/docs/sdk
+Project-URL: Repository, https://github.com/tingeehub/tingee-python
+Project-URL: Issues, https://github.com/tingeehub/tingee-python/issues
+Keywords: tingee,sdk,payment,api
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# tingee-sdk (Python)
+
+> SDK chính thức tích hợp **Tingee Open API** cho Python
+
+Python ≥ 3.8, không phụ thuộc thư viện ngoài.
+
+---
+
+## Cài đặt
+
+```bash
+pip install tingee-sdk
+```
+
+---
+
+## Bắt đầu nhanh
+
+```python
+import os
+from tingee_sdk import TingeeClient, is_success_response
+
+client = TingeeClient(
+    secret_key=os.environ["TINGEE_SECRET_KEY"],
+    client_id=os.environ["TINGEE_CLIENT_ID"],
+    environment="uat",  # hoặc "production" (mặc định)
+)
+
+result = client.bank.get_banks()
+if is_success_response(result):
+    print(result["data"])
+
+result = client.bank.generate_viet_qr({
+    "bankName": "OCB",
+    "accountNumber": "0123456789",
+    "amount": 100000,
+    "content": "Thanh toan don hang",
+})
+```
+
+- Method được nhóm theo path: `/v1/bank/create-va` → `client.bank.create_va(body)`, `/v1/deep-link/generate` → `client.deep_link.generate(body)`.
+- Body và query truyền dạng `dict`, tên field giữ nguyên như API (camelCase). Kiểu DTO (TypedDict) nằm trong `tingee_sdk.models`.
+- SDK tự ký request (`x-signature`, `x-request-timestamp`, `x-client-id`).
+
+> **Lưu ý:** SDK trả về `dict` có `code` và `message`. Kiểm tra `code == "00"` hoặc `is_success_response(result)` để xác định thành công — SDK **không tự raise** khi `code != "00"`. Lỗi HTTP (non-2xx), lỗi mạng và timeout raise `TingeeHttpError`.
+
+---
+
+## Xác thực Webhook
+
+```python
+# Flask
+from flask import Flask, request
+
+app = Flask(__name__)
+
+@app.post("/webhook/tingee")
+def tingee_webhook():
+    result = client.verify_webhook_signature(
+        request.headers.get("x-signature"),
+        request.headers.get("x-request-timestamp"),
+        request.get_data(),  # raw body
+    )
+    if result["code"] != "00":
+        return {"error": result["message"]}, 401
+
+    body = request.get_json()
+    # Xử lý giao dịch...
+    return {"received": True}
+```
+
+Hoặc dùng hàm `verify_webhook_signature(secret_token, signature, timestamp, body)` với secret token riêng.
+
+---
+
+## Xác thực URL webhook
+
+Khi lưu URL webhook trên Tingee, hệ thống gửi một request xác thực vào URL đó:
+
+```json
+{ "event": "url-validation", "plainToken": "<chuỗi ngẫu nhiên>", "timestamp": 1730000000000 }
+```
+
+Endpoint phải trả về HTTP 200 với `{ "plainToken": "...", "encryptedToken": "..." }`, trong đó `encryptedToken = HMAC-SHA256(secretToken, plainToken)` dạng hex. `secretToken` là secret của **API Key loại Xác thực webhook** đang bật (tạo trong mục API Credentials).
+
+SDK làm sẵn bước này: hàm trả về body cần phản hồi, hoặc `None` nếu không phải request xác thực. Gọi **trước** khi verify chữ ký, vì body xác thực không có các trường giao dịch.
+
+```python
+from tingee_sdk import create_url_validation_response
+
+@app.post("/webhook/tingee")
+def tingee_webhook():
+    validation = create_url_validation_response(os.environ["TINGEE_WEBHOOK_SECRET"], request.get_data())
+    if validation is not None:
+        return validation
+
+    # Verify chữ ký & xử lý giao dịch như bình thường...
+```
+
+Nếu dùng chung khóa với client: `client.create_url_validation_response(request.get_data())`.
+
+---
+
+## Bank Constants
+
+```python
+from tingee_sdk import BankNameEnum, get_bank_code, get_bank_short_name, get_bank_bin
+
+get_bank_code("970436")                 # BankNameEnum.VCB
+get_bank_short_name("970436")           # 'Vietcombank'
+get_bank_bin(BankNameEnum.VCB)          # '970436'
+```
+
+---
+
+## Liên hệ & Hỗ trợ
+
+📧 **Email:** [developer@heno.vn](mailto:developer@heno.vn)
+💬 **Telegram:** [@tingeesupport](https://t.me/tingeesupport)
+🌐 **Website:** [tingee.vn](https://tingee.vn)
+
+---
+
+## Xem thêm
+
+- [CHANGELOG](./CHANGELOG.md)
+- [Tài liệu Tingee Open API](https://open-api.tingee.vn)
+- [Tài liệu Tingee Developer](https://developers.tingee.vn)
+- [Trang chủ Tingee](https://tingee.vn)

tingee_sdk-0.4.0/README.md

@@ -0,0 +1,129 @@
+# tingee-sdk (Python)
+
+> SDK chính thức tích hợp **Tingee Open API** cho Python
+
+Python ≥ 3.8, không phụ thuộc thư viện ngoài.
+
+---
+
+## Cài đặt
+
+```bash
+pip install tingee-sdk
+```
+
+---
+
+## Bắt đầu nhanh
+
+```python
+import os
+from tingee_sdk import TingeeClient, is_success_response
+
+client = TingeeClient(
+    secret_key=os.environ["TINGEE_SECRET_KEY"],
+    client_id=os.environ["TINGEE_CLIENT_ID"],
+    environment="uat",  # hoặc "production" (mặc định)
+)
+
+result = client.bank.get_banks()
+if is_success_response(result):
+    print(result["data"])
+
+result = client.bank.generate_viet_qr({
+    "bankName": "OCB",
+    "accountNumber": "0123456789",
+    "amount": 100000,
+    "content": "Thanh toan don hang",
+})
+```
+
+- Method được nhóm theo path: `/v1/bank/create-va` → `client.bank.create_va(body)`, `/v1/deep-link/generate` → `client.deep_link.generate(body)`.
+- Body và query truyền dạng `dict`, tên field giữ nguyên như API (camelCase). Kiểu DTO (TypedDict) nằm trong `tingee_sdk.models`.
+- SDK tự ký request (`x-signature`, `x-request-timestamp`, `x-client-id`).
+
+> **Lưu ý:** SDK trả về `dict` có `code` và `message`. Kiểm tra `code == "00"` hoặc `is_success_response(result)` để xác định thành công — SDK **không tự raise** khi `code != "00"`. Lỗi HTTP (non-2xx), lỗi mạng và timeout raise `TingeeHttpError`.
+
+---
+
+## Xác thực Webhook
+
+```python
+# Flask
+from flask import Flask, request
+
+app = Flask(__name__)
+
+@app.post("/webhook/tingee")
+def tingee_webhook():
+    result = client.verify_webhook_signature(
+        request.headers.get("x-signature"),
+        request.headers.get("x-request-timestamp"),
+        request.get_data(),  # raw body
+    )
+    if result["code"] != "00":
+        return {"error": result["message"]}, 401
+
+    body = request.get_json()
+    # Xử lý giao dịch...
+    return {"received": True}
+```
+
+Hoặc dùng hàm `verify_webhook_signature(secret_token, signature, timestamp, body)` với secret token riêng.
+
+---
+
+## Xác thực URL webhook
+
+Khi lưu URL webhook trên Tingee, hệ thống gửi một request xác thực vào URL đó:
+
+```json
+{ "event": "url-validation", "plainToken": "<chuỗi ngẫu nhiên>", "timestamp": 1730000000000 }
+```
+
+Endpoint phải trả về HTTP 200 với `{ "plainToken": "...", "encryptedToken": "..." }`, trong đó `encryptedToken = HMAC-SHA256(secretToken, plainToken)` dạng hex. `secretToken` là secret của **API Key loại Xác thực webhook** đang bật (tạo trong mục API Credentials).
+
+SDK làm sẵn bước này: hàm trả về body cần phản hồi, hoặc `None` nếu không phải request xác thực. Gọi **trước** khi verify chữ ký, vì body xác thực không có các trường giao dịch.
+
+```python
+from tingee_sdk import create_url_validation_response
+
+@app.post("/webhook/tingee")
+def tingee_webhook():
+    validation = create_url_validation_response(os.environ["TINGEE_WEBHOOK_SECRET"], request.get_data())
+    if validation is not None:
+        return validation
+
+    # Verify chữ ký & xử lý giao dịch như bình thường...
+```
+
+Nếu dùng chung khóa với client: `client.create_url_validation_response(request.get_data())`.
+
+---
+
+## Bank Constants
+
+```python
+from tingee_sdk import BankNameEnum, get_bank_code, get_bank_short_name, get_bank_bin
+
+get_bank_code("970436")                 # BankNameEnum.VCB
+get_bank_short_name("970436")           # 'Vietcombank'
+get_bank_bin(BankNameEnum.VCB)          # '970436'
+```
+
+---
+
+## Liên hệ & Hỗ trợ
+
+📧 **Email:** [developer@heno.vn](mailto:developer@heno.vn)
+💬 **Telegram:** [@tingeesupport](https://t.me/tingeesupport)
+🌐 **Website:** [tingee.vn](https://tingee.vn)
+
+---
+
+## Xem thêm
+
+- [CHANGELOG](./CHANGELOG.md)
+- [Tài liệu Tingee Open API](https://open-api.tingee.vn)
+- [Tài liệu Tingee Developer](https://developers.tingee.vn)
+- [Trang chủ Tingee](https://tingee.vn)

tingee_sdk-0.4.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tingee-sdk"
+version = "0.4.0"
+description = "Tingee Open API SDK for Python"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "ISC" }
+authors = [{ name = "Tingee", email = "developer@heno.vn" }]
+keywords = ["tingee", "sdk", "payment", "api"]
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://developers.tingee.vn"
+Documentation = "https://developers.tingee.vn/docs/sdk"
+Repository = "https://github.com/tingeehub/tingee-python"
+Issues = "https://github.com/tingeehub/tingee-python/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+tingee_sdk = ["py.typed"]

tingee_sdk-0.4.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tingee_sdk-0.4.0/src/tingee_sdk/__init__.py

@@ -0,0 +1,53 @@
+"""
+Tingee SDK for Python
+
+Official SDK for Tingee Open API. DTO types are in ``tingee_sdk.models``.
+"""
+
+from .bank_constants import (
+    BANKS,
+    BANKS_OBJECT,
+    BankAccountTypeEnum,
+    BankBinEnum,
+    BankNameEnum,
+    get_bank_bin,
+    get_bank_code,
+    get_bank_short_name,
+)
+from .client import ENVIRONMENT_URLS, TingeeClient, TingeeEnvironment
+from .http import TingeeHttpError
+from .response import TingeeApiResponse, is_error_response, is_success_response
+from .signature import (
+    URL_VALIDATION_EVENT,
+    create_url_validation_response,
+    format_timestamp,
+    generate_signature,
+    verify_webhook_signature,
+)
+from .version import SDK_VERSION
+
+__version__ = SDK_VERSION
+
+__all__ = [
+    "TingeeClient",
+    "TingeeEnvironment",
+    "ENVIRONMENT_URLS",
+    "TingeeHttpError",
+    "TingeeApiResponse",
+    "is_success_response",
+    "is_error_response",
+    "generate_signature",
+    "format_timestamp",
+    "verify_webhook_signature",
+    "create_url_validation_response",
+    "URL_VALIDATION_EVENT",
+    "BankNameEnum",
+    "BankBinEnum",
+    "BankAccountTypeEnum",
+    "BANKS",
+    "BANKS_OBJECT",
+    "get_bank_code",
+    "get_bank_short_name",
+    "get_bank_bin",
+    "SDK_VERSION",
+]

tingee_sdk-0.4.0/src/tingee_sdk/bank_constants.py

@@ -0,0 +1,92 @@
+"""Bank constants (same as the other SDKs)."""
+
+from enum import Enum
+from typing import Dict, List, Optional, TypedDict
+
+__all__ = [
+    "BankNameEnum",
+    "BankBinEnum",
+    "BankAccountTypeEnum",
+    "BankInfo",
+    "BANKS_OBJECT",
+    "BANKS",
+    "get_bank_code",
+    "get_bank_short_name",
+    "get_bank_bin",
+]
+
+
+class BankNameEnum(str, Enum):
+    OCB = "OCB"
+    BIDV = "BIDV"
+    MBB = "MBB"
+    ACB = "ACB"
+    VPB = "VPB"
+    PGB = "PGB"
+    VIB = "VIB"
+    STB = "STB"
+    CTG = "CTG"
+    VCB = "VCB"
+    AGRIBANK = "AGRIBANK"
+    SHINHAN = "SHINHAN"
+    COB = "COB"
+
+
+class BankBinEnum(str, Enum):
+    OCB = "970448"
+    BIDV = "970418"
+    MBB = "970422"
+    ACB = "970416"
+    VPB = "970432"
+    PGB = "970430"
+    VIB = "970441"
+    STB = "970403"
+    CTG = "970415"
+    VCB = "970436"
+    AGRIBANK = "970405"
+    SHINHAN = "970424"
+    COB = "970446"
+
+
+class BankAccountTypeEnum(str, Enum):
+    PersonalAccount = "personal-account"
+    BusinessAccount = "business-account"
+    BusinessHouseHoldAccount = "business-household-account"
+
+
+class BankInfo(TypedDict):
+    code: BankNameEnum
+    name: str
+    shortName: str
+    bin: str
+
+
+BANKS_OBJECT: Dict[BankNameEnum, BankInfo] = {
+    BankNameEnum.VCB: {"code": BankNameEnum.VCB, "name": "Ngân hàng TMCP Ngoại Thương Việt Nam", "bin": "970436", "shortName": "Vietcombank"},
+    BankNameEnum.CTG: {"code": BankNameEnum.CTG, "name": "Ngân hàng TMCP Công thương Việt Nam", "bin": "970415", "shortName": "VietinBank"},
+    BankNameEnum.BIDV: {"code": BankNameEnum.BIDV, "name": "Ngân hàng TMCP Đầu tư và Phát triển Việt Nam", "bin": "970418", "shortName": "BIDV"},
+    BankNameEnum.AGRIBANK: {"code": BankNameEnum.AGRIBANK, "name": "Ngân hàng Nông nghiệp và Phát triển Nông thôn Việt Nam", "bin": "970405", "shortName": "Agribank"},
+    BankNameEnum.MBB: {"code": BankNameEnum.MBB, "name": "Ngân hàng TMCP Quân đội", "bin": "970422", "shortName": "MB Bank"},
+    BankNameEnum.ACB: {"code": BankNameEnum.ACB, "name": "Ngân hàng TMCP Á Châu", "bin": "970416", "shortName": "ACB"},
+    BankNameEnum.OCB: {"code": BankNameEnum.OCB, "name": "Ngân hàng TMCP Phương Đông", "bin": "970448", "shortName": "OCB Bank"},
+    BankNameEnum.VPB: {"code": BankNameEnum.VPB, "name": "Ngân hàng TMCP Việt Nam Thịnh Vượng", "bin": "970432", "shortName": "VPBank"},
+    BankNameEnum.STB: {"code": BankNameEnum.STB, "name": "Ngân hàng TMCP Sài Gòn Thương Tín", "bin": "970403", "shortName": "Sacombank"},
+    BankNameEnum.VIB: {"code": BankNameEnum.VIB, "name": "Ngân hàng TMCP Quốc tế Việt Nam", "bin": "970441", "shortName": "VIB"},
+    BankNameEnum.PGB: {"code": BankNameEnum.PGB, "name": "Ngân Hàng TMCP Thịnh vượng và Phát triển", "bin": "970430", "shortName": "PGBank"},
+    BankNameEnum.SHINHAN: {"code": BankNameEnum.SHINHAN, "name": "Ngân hàng TNHH MTV Shinhan Việt Nam", "bin": "970424", "shortName": "Shinhan Bank"},
+    BankNameEnum.COB: {"code": BankNameEnum.COB, "name": "Ngân hàng Hợp tác Xã Việt Nam", "bin": "970446", "shortName": "Co-opBank"},
+}
+
+BANKS: List[BankInfo] = list(BANKS_OBJECT.values())
+
+
+def get_bank_code(bank_bin: str) -> Optional[BankNameEnum]:
+    return next((x["code"] for x in BANKS if x["bin"] == bank_bin), None)
+
+
+def get_bank_short_name(bank_bin: str) -> Optional[str]:
+    return next((x["shortName"] for x in BANKS if x["bin"] == bank_bin), None)
+
+
+def get_bank_bin(bank_name: BankNameEnum) -> Optional[str]:
+    return next((x["bin"] for x in BANKS if x["code"] == bank_name), None)

tingee_sdk-0.4.0/src/tingee_sdk/client.py

@@ -0,0 +1,76 @@
+from typing import Any, Dict, Literal, Optional, Union
+
+from .generated_methods import GeneratedMethods
+from .http import TingeeHttpClient
+from .signature import create_url_validation_response, verify_webhook_signature
+
+__all__ = ["TingeeClient", "TingeeEnvironment", "ENVIRONMENT_URLS"]
+
+TingeeEnvironment = Literal["production", "uat"]
+
+ENVIRONMENT_URLS: Dict[str, str] = {
+    "production": "https://open-api.tingee.vn",
+    "uat": "https://uat-open-api.tingee.vn",
+}
+
+
+class TingeeClient(GeneratedMethods):
+    """
+    Tingee Open API client.
+
+    Example::
+
+        client = TingeeClient(secret_key="...", client_id="...", environment="uat")
+        result = client.bank.get_banks()
+        if result["code"] == "00":
+            print(result["data"])
+    """
+
+    def __init__(
+        self,
+        secret_key: str,
+        client_id: str,
+        environment: TingeeEnvironment = "production",
+        timeout: float = 90,
+        base_url: Optional[str] = None,
+    ) -> None:
+        """
+        :param secret_key: Secret key for generating request signature
+        :param client_id: Client ID for API authentication
+        :param environment: ``production`` (default) or ``uat``
+        :param timeout: Request timeout in seconds (default 90)
+        :param base_url: Custom base URL (overrides environment)
+        """
+        if not secret_key:
+            raise ValueError("secret_key is required")
+        if not client_id:
+            raise ValueError("client_id is required")
+        if environment not in ENVIRONMENT_URLS and not base_url:
+            raise ValueError("environment must be one of: {0}".format(", ".join(ENVIRONMENT_URLS)))
+
+        self._secret_key = secret_key
+        self._base_url = base_url or ENVIRONMENT_URLS[environment]
+        super().__init__(TingeeHttpClient(self._base_url, secret_key, client_id, timeout))
+
+    def get_base_url(self) -> str:
+        return self._base_url
+
+    def verify_webhook_signature(
+        self,
+        signature: Optional[str],
+        timestamp: Optional[str],
+        body: Union[Dict[str, Any], str, bytes, None],
+    ) -> Dict[str, str]:
+        """Verify an incoming Tingee webhook signature using this client's secret_key."""
+        return verify_webhook_signature(self._secret_key, signature, timestamp, body)
+
+    def create_url_validation_response(
+        self,
+        body: Union[Dict[str, Any], str, bytes, None],
+        secret_token: Optional[str] = None,
+    ) -> Optional[Dict[str, str]]:
+        """
+        Build the response for a webhook URL validation request, ``None`` if body is not one.
+        Pass ``secret_token`` when your "Webhook verification" credential differs from this client's.
+        """
+        return create_url_validation_response(secret_token or self._secret_key, body)