kkhay 1.0.0__tar.gz

kkhay-1.0.0/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.env
+.venv
+env/
+venv/
+ENV/
+.pytest_cache/
+

kkhay-1.0.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 K Khay (https://kkhay.com)
+
+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.
+

kkhay-1.0.0/PKG-INFO

@@ -0,0 +1,183 @@
+Metadata-Version: 2.5
+Name: kkhay
+Version: 1.0.0
+Summary: Official Python SDK for K Khay Sovereign Crypto Payment Gateway
+Project-URL: Homepage, https://kkhay.com
+Project-URL: Documentation, https://docs.kkhay.com
+Project-URL: Repository, https://github.com/boboaungdev/kkhay-python
+Project-URL: Issues, https://github.com/boboaungdev/kkhay-python/issues
+Author-email: K Khay <dev@kkhay.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: arbitrum,base,blockchain,bnb,bsc,checkout,crypto,cryptocurrency,eth,invoice,ipn,kkhay,payment-gateway,payment-processor,payments,polygon,usdc,usdt,web3,webhook
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Point-Of-Sale
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# K Khay Python SDK 🐍
+
+Official Python SDK for the **[K Khay Sovereign Crypto Payment Gateway](https://kkhay.com)**.
+
+Accept non-custodial and custodial crypto payments (USDT, USDC, BNB, ETH, and native tokens across BSC, Polygon, Arbitrum, Base, and Ethereum) directly in your Python applications, Django, FastAPI, Flask, or background bots with **zero third-party dependencies**.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install kkhay
+```
+
+*(Requires Python 3.8 or newer)*
+
+---
+
+## ⚡ Quick Start
+
+### 1. Initialize Client
+
+```python
+from kkhay import KkhayClient
+
+client = KkhayClient(api_key="kkhay_live_your_api_key_here")
+```
+
+### 2. Create a Payment Invoice
+
+```python
+response = client.create_invoice(
+    price_amount=49.99,
+    price_currency="USD",
+    pay_network="bsc",
+    pay_token="USDT",
+    order_id="ORDER-9012",
+    title="Annual Premium Membership",
+    customer_email="merchant-customer@example.com",
+    redirect_url="https://myshop.com/orders/success",
+    cancel_url="https://myshop.com/cart",
+)
+
+invoice = response["invoice"]
+print("Invoice ID:", invoice.id)
+print("Deposit Address:", invoice.deposit_address)
+print("Customer Checkout URL:", invoice.hosted_url)
+```
+
+### 3. Retrieve Invoice Status & Blockchain Proofs
+
+```python
+data = client.get_invoice("inv_9f81a7b2")
+invoice = data.invoice
+
+print(f"Status: {invoice.status}")
+for payment in data.payments:
+    print(f"Received: {payment.amount_received} {invoice.pay_token}")
+    print(f"Tx Hash: {payment.tx_hash} ({payment.confirmations} confirmations)")
+```
+
+### 4. List & Paginate Invoices
+
+```python
+res = client.list_invoices(page=1, limit=10, status="FINISHED")
+print(f"Total Completed Invoices: {res.total_count}")
+for inv in res.items:
+    print(f"- {inv.id}: ${inv.price_amount} ({inv.status})")
+```
+
+---
+
+## 🔐 Webhook / IPN Verification
+
+K Khay cryptographically signs every webhook notification using HMAC-SHA256 with your secret IPN key.
+
+### FastAPI Example
+
+```python
+from fastapi import FastAPI, Header, HTTPException, Request
+from kkhay import SignatureVerificationError, parse_webhook_event
+
+app = FastAPI()
+IPN_SECRET = "whsec_your_secret_key"
+
+
+@app.post("/api/webhooks/kkhay")
+async def handle_kkhay_webhook(
+    request: Request,
+    x_kkhay_signature: str = Header(None),
+):
+    body = await request.body()
+
+    try:
+        event = parse_webhook_event(
+            raw_body=body,
+            signature=x_kkhay_signature,
+            ipn_secret=IPN_SECRET,
+        )
+    except SignatureVerificationError:
+        raise HTTPException(status_code=400, detail="Invalid signature")
+
+    if event.event == "payment.finished":
+        print(f"Order {event.order_id} was paid!")
+        print(f"Transaction Hash: {event.tx_hash}")
+
+    return {"status": "ok"}
+```
+
+### Flask / Django Example
+
+```python
+from flask import Flask, abort, request
+from kkhay import SignatureVerificationError, parse_webhook_event
+
+app = Flask(__name__)
+
+
+@app.route("/webhooks/kkhay", methods=["POST"])
+def webhook():
+    raw_body = request.get_data()
+    sig = request.headers.get("x-kkhay-signature")
+
+    try:
+        event = parse_webhook_event(raw_body, sig, "whsec_your_secret")
+    except SignatureVerificationError:
+        abort(400)
+
+    # Process order
+    return "OK", 200
+```
+
+---
+
+## 🛠️ Error Handling
+
+```python
+from kkhay import KkhayApiError, KkhayClient
+
+client = KkhayClient(api_key="invalid_key")
+
+try:
+    client.get_invoice("inv_not_exist")
+except KkhayApiError as e:
+    print(f"HTTP Status: {e.status}")
+    print(f"Error Code: {e.code}")
+    print(f"Message: {e.message}")
+```
+
+---
+
+## 📄 License
+
+MIT © [K Khay](https://kkhay.com)
+

kkhay-1.0.0/README.md

@@ -0,0 +1,155 @@
+# K Khay Python SDK 🐍
+
+Official Python SDK for the **[K Khay Sovereign Crypto Payment Gateway](https://kkhay.com)**.
+
+Accept non-custodial and custodial crypto payments (USDT, USDC, BNB, ETH, and native tokens across BSC, Polygon, Arbitrum, Base, and Ethereum) directly in your Python applications, Django, FastAPI, Flask, or background bots with **zero third-party dependencies**.
+
+---
+
+## 📦 Installation
+
+```bash
+pip install kkhay
+```
+
+*(Requires Python 3.8 or newer)*
+
+---
+
+## ⚡ Quick Start
+
+### 1. Initialize Client
+
+```python
+from kkhay import KkhayClient
+
+client = KkhayClient(api_key="kkhay_live_your_api_key_here")
+```
+
+### 2. Create a Payment Invoice
+
+```python
+response = client.create_invoice(
+    price_amount=49.99,
+    price_currency="USD",
+    pay_network="bsc",
+    pay_token="USDT",
+    order_id="ORDER-9012",
+    title="Annual Premium Membership",
+    customer_email="merchant-customer@example.com",
+    redirect_url="https://myshop.com/orders/success",
+    cancel_url="https://myshop.com/cart",
+)
+
+invoice = response["invoice"]
+print("Invoice ID:", invoice.id)
+print("Deposit Address:", invoice.deposit_address)
+print("Customer Checkout URL:", invoice.hosted_url)
+```
+
+### 3. Retrieve Invoice Status & Blockchain Proofs
+
+```python
+data = client.get_invoice("inv_9f81a7b2")
+invoice = data.invoice
+
+print(f"Status: {invoice.status}")
+for payment in data.payments:
+    print(f"Received: {payment.amount_received} {invoice.pay_token}")
+    print(f"Tx Hash: {payment.tx_hash} ({payment.confirmations} confirmations)")
+```
+
+### 4. List & Paginate Invoices
+
+```python
+res = client.list_invoices(page=1, limit=10, status="FINISHED")
+print(f"Total Completed Invoices: {res.total_count}")
+for inv in res.items:
+    print(f"- {inv.id}: ${inv.price_amount} ({inv.status})")
+```
+
+---
+
+## 🔐 Webhook / IPN Verification
+
+K Khay cryptographically signs every webhook notification using HMAC-SHA256 with your secret IPN key.
+
+### FastAPI Example
+
+```python
+from fastapi import FastAPI, Header, HTTPException, Request
+from kkhay import SignatureVerificationError, parse_webhook_event
+
+app = FastAPI()
+IPN_SECRET = "whsec_your_secret_key"
+
+
+@app.post("/api/webhooks/kkhay")
+async def handle_kkhay_webhook(
+    request: Request,
+    x_kkhay_signature: str = Header(None),
+):
+    body = await request.body()
+
+    try:
+        event = parse_webhook_event(
+            raw_body=body,
+            signature=x_kkhay_signature,
+            ipn_secret=IPN_SECRET,
+        )
+    except SignatureVerificationError:
+        raise HTTPException(status_code=400, detail="Invalid signature")
+
+    if event.event == "payment.finished":
+        print(f"Order {event.order_id} was paid!")
+        print(f"Transaction Hash: {event.tx_hash}")
+
+    return {"status": "ok"}
+```
+
+### Flask / Django Example
+
+```python
+from flask import Flask, abort, request
+from kkhay import SignatureVerificationError, parse_webhook_event
+
+app = Flask(__name__)
+
+
+@app.route("/webhooks/kkhay", methods=["POST"])
+def webhook():
+    raw_body = request.get_data()
+    sig = request.headers.get("x-kkhay-signature")
+
+    try:
+        event = parse_webhook_event(raw_body, sig, "whsec_your_secret")
+    except SignatureVerificationError:
+        abort(400)
+
+    # Process order
+    return "OK", 200
+```
+
+---
+
+## 🛠️ Error Handling
+
+```python
+from kkhay import KkhayApiError, KkhayClient
+
+client = KkhayClient(api_key="invalid_key")
+
+try:
+    client.get_invoice("inv_not_exist")
+except KkhayApiError as e:
+    print(f"HTTP Status: {e.status}")
+    print(f"Error Code: {e.code}")
+    print(f"Message: {e.message}")
+```
+
+---
+
+## 📄 License
+
+MIT © [K Khay](https://kkhay.com)
+

kkhay-1.0.0/kkhay/__init__.py

@@ -0,0 +1,35 @@
+"""
+Official Python SDK for K Khay Sovereign Crypto Payment Gateway.
+"""
+
+from .client import KkhayClient
+from .errors import KkhayApiError, SignatureVerificationError
+from .types import (
+    CreateInvoiceRequest,
+    GetInvoiceResponse,
+    InvoiceStatus,
+    KkhayInvoice,
+    KkhayPaymentRecord,
+    KkhayWebhookEvent,
+    ListInvoicesResponse,
+    PaymentNetwork,
+)
+from .webhook import parse_webhook_event, verify_webhook_signature
+
+__version__ = "1.0.0"
+__all__ = [
+    "KkhayClient",
+    "KkhayApiError",
+    "SignatureVerificationError",
+    "CreateInvoiceRequest",
+    "GetInvoiceResponse",
+    "KkhayInvoice",
+    "KkhayPaymentRecord",
+    "KkhayWebhookEvent",
+    "ListInvoicesResponse",
+    "InvoiceStatus",
+    "PaymentNetwork",
+    "verify_webhook_signature",
+    "parse_webhook_event",
+]
+

kkhay-1.0.0/kkhay/client.py

@@ -0,0 +1,212 @@
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional, Union
+
+from .errors import KkhayApiError
+from .types import (
+    CreateInvoiceRequest,
+    GetInvoiceResponse,
+    KkhayInvoice,
+    KkhayPaymentRecord,
+    ListInvoicesResponse,
+)
+
+
+class KkhayClient:
+    """
+    Official Python SDK client for the K Khay Sovereign Crypto Payment Gateway.
+
+    Example:
+    >>> from kkhay import KkhayClient
+    >>> client = KkhayClient(api_key="kkhay_live_...")
+    >>> res = client.create_invoice(
+    ...     price_amount=49.99,
+    ...     pay_network="bsc",
+    ...     pay_token="USDT",
+    ...     title="Pro Subscription",
+    ... )
+    >>> print("Pay URL:", res["invoice"].hosted_url)
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "https://api.kkhay.com",
+        timeout: float = 30.0,
+    ):
+        if not api_key or not isinstance(api_key, str) or not api_key.strip():
+            raise ValueError("KkhayClient: A valid 'api_key' string is required.")
+
+        self.api_key: str = api_key.strip()
+        self.base_url: str = base_url.rstrip("/")
+        self.timeout: float = float(timeout)
+
+    def _get_url(self, path: str) -> str:
+        clean_path = path if path.startswith("/") else f"/{path}"
+        if self.base_url.endswith("/api") or "api." in self.base_url:
+            return f"{self.base_url}{clean_path}"
+        return f"{self.base_url}/api{clean_path}"
+
+    def _request(
+        self,
+        path: str,
+        method: str = "GET",
+        data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        url = self._get_url(path)
+        headers = {
+            "Accept": "application/json",
+            "x-api-key": self.api_key,
+            "User-Agent": "kkhay-python/1.0.0",
+        }
+
+        body_bytes: Optional[bytes] = None
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+            body_bytes = json.dumps(data).encode("utf-8")
+
+        req = urllib.request.Request(url, data=body_bytes, headers=headers, method=method)
+
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                status = response.status
+                raw = response.read().decode("utf-8")
+                if not raw:
+                    return {}
+                try:
+                    return json.loads(raw)
+                except json.JSONDecodeError:
+                    return {"data": raw}
+        except urllib.error.HTTPError as e:
+            raw_err = e.read().decode("utf-8") if e.fp else ""
+            error_message = f"Request failed with HTTP {e.code}"
+            error_code = None
+            error_details = None
+
+            if raw_err:
+                try:
+                    err_json = json.loads(raw_err)
+                    error_message = err_json.get("message") or err_json.get("error") or error_message
+                    error_code = err_json.get("code")
+                    error_details = err_json.get("details")
+                except json.JSONDecodeError:
+                    error_message = raw_err
+
+            raise KkhayApiError(
+                status=e.code,
+                message=error_message,
+                code=error_code,
+                details=error_details,
+            ) from e
+        except urllib.error.URLError as e:
+            if "timed out" in str(e).lower():
+                raise KkhayApiError(408, f"Request timed out after {self.timeout}s") from e
+            raise KkhayApiError(500, f"Network connection error: {e.reason}") from e
+        except Exception as e:
+            raise KkhayApiError(500, f"Unexpected error: {e}") from e
+
+    def create_invoice(
+        self,
+        price_amount: float,
+        pay_network: str,
+        pay_token: str,
+        price_currency: str = "USD",
+        order_id: Optional[str] = None,
+        title: Optional[str] = None,
+        customer_name: Optional[str] = None,
+        customer_email: Optional[str] = None,
+        redirect_url: Optional[str] = None,
+        cancel_url: Optional[str] = None,
+        ipn_callback_url: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """
+        Creates a new sovereign crypto payment invoice.
+
+        :return: Dict with keys 'ok' (bool) and 'invoice' (KkhayInvoice)
+        """
+        if price_amount <= 0:
+            raise ValueError("create_invoice: 'price_amount' must be a positive number.")
+        if not pay_network:
+            raise ValueError("create_invoice: 'pay_network' is required (e.g. 'bsc', 'polygon').")
+        if not pay_token:
+            raise ValueError("create_invoice: 'pay_token' is required (e.g. 'USDT', 'USDC').")
+
+        payload = CreateInvoiceRequest(
+            price_amount=price_amount,
+            pay_network=pay_network,
+            pay_token=pay_token,
+            price_currency=price_currency,
+            order_id=order_id,
+            title=title,
+            customer_name=customer_name,
+            customer_email=customer_email,
+            redirect_url=redirect_url,
+            cancel_url=cancel_url,
+            ipn_callback_url=ipn_callback_url,
+            metadata=metadata,
+        ).to_dict()
+
+        res = self._request("/v1/merchant/invoices", method="POST", data=payload)
+        return {
+            "ok": bool(res.get("ok", True)),
+            "invoice": KkhayInvoice.from_dict(res.get("invoice", {})),
+        }
+
+    def get_invoice(self, invoice_id: str) -> GetInvoiceResponse:
+        """
+        Retrieve details and blockchain confirmations for an invoice by ID.
+        """
+        if not invoice_id or not str(invoice_id).strip():
+            raise ValueError("get_invoice: 'invoice_id' is required.")
+
+        res = self._request(f"/v1/merchant/invoices/{urllib.parse.quote(str(invoice_id).strip())}")
+        invoice_raw = res.get("invoice", {})
+        payments_raw = res.get("payments", [])
+
+        return GetInvoiceResponse(
+            ok=bool(res.get("ok", True)),
+            invoice=KkhayInvoice.from_dict(invoice_raw),
+            payments=[KkhayPaymentRecord.from_dict(p) for p in payments_raw],
+        )
+
+    def list_invoices(
+        self,
+        page: int = 1,
+        limit: int = 20,
+        status: Optional[str] = None,
+        search: Optional[str] = None,
+    ) -> ListInvoicesResponse:
+        """
+        List and paginate merchant invoices.
+        """
+        params: Dict[str, str] = {
+            "page": str(page),
+            "limit": str(limit),
+        }
+        if status:
+            params["status"] = status
+        if search:
+            params["search"] = search
+
+        query_str = urllib.parse.urlencode(params)
+        res = self._request(f"/v1/merchant/invoices?{query_str}")
+
+        items_raw = res.get("items", [])
+        return ListInvoicesResponse(
+            ok=bool(res.get("ok", True)),
+            items=[KkhayInvoice.from_dict(item) for item in items_raw],
+            total_count=int(res.get("totalCount", 0)),
+            total_pages=int(res.get("totalPages", 1)),
+            current_page=int(res.get("currentPage", page)),
+            limit=int(res.get("limit", limit)),
+        )
+
+    def check_health(self) -> Dict[str, Any]:
+        """
+        Check connectivity and health of the K Khay API gateway.
+        """
+        return self._request("/health")
+

kkhay-1.0.0/kkhay/errors.py

@@ -0,0 +1,31 @@
+from typing import Any, Optional
+
+
+class KkhayApiError(Exception):
+    """
+    Standard API error returned when a K Khay endpoint fails.
+    """
+
+    def __init__(
+        self,
+        status: int,
+        message: str,
+        code: Optional[str] = None,
+        details: Optional[Any] = None,
+    ):
+        super().__init__(f"KkhayApiError [HTTP {status}]: {message}")
+        self.status = status
+        self.message = message
+        self.code = code
+        self.details = details
+
+    def __repr__(self) -> str:
+        return f"<KkhayApiError status={self.status} code={self.code!r} message={self.message!r}>"
+
+
+class SignatureVerificationError(Exception):
+    """
+    Raised when an incoming IPN webhook payload fails HMAC signature verification.
+    """
+    pass
+

kkhay-1.0.0/kkhay/types.py

@@ -0,0 +1,182 @@
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Literal, Optional, Union
+
+InvoiceStatus = Literal[
+    "WAITING",
+    "DETECTING",
+    "CONFIRMING",
+    "SENDING",
+    "FINISHED",
+    "EXPIRED",
+    "CANCELED",
+    "FAILED",
+]
+
+PaymentNetwork = Literal["bsc", "polygon", "base", "arbitrum", "ethereum", str]
+
+
+@dataclass
+class CreateInvoiceRequest:
+    """Parameters required to generate a new crypto invoice."""
+    price_amount: float
+    pay_network: Union[str, PaymentNetwork]
+    pay_token: str
+    price_currency: str = "USD"
+    order_id: Optional[str] = None
+    title: Optional[str] = None
+    customer_name: Optional[str] = None
+    customer_email: Optional[str] = None
+    redirect_url: Optional[str] = None
+    cancel_url: Optional[str] = None
+    ipn_callback_url: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        data: Dict[str, Any] = {
+            "priceAmount": self.price_amount,
+            "payNetwork": self.pay_network,
+            "payToken": self.pay_token,
+            "priceCurrency": self.price_currency,
+        }
+        if self.order_id is not None:
+            data["orderId"] = self.order_id
+        if self.title is not None:
+            data["title"] = self.title
+        if self.customer_name is not None:
+            data["customerName"] = self.customer_name
+        if self.customer_email is not None:
+            data["customerEmail"] = self.customer_email
+        if self.redirect_url is not None:
+            data["redirectUrl"] = self.redirect_url
+        if self.cancel_url is not None:
+            data["cancelUrl"] = self.cancel_url
+        if self.ipn_callback_url is not None:
+            data["ipnCallbackUrl"] = self.ipn_callback_url
+        if self.metadata is not None:
+            data["metadata"] = self.metadata
+        return data
+
+
+@dataclass
+class KkhayPaymentRecord:
+    id: str
+    tx_hash: str
+    amount_received: str
+    confirmations: int
+    status: str
+    forwarded_tx_hash: Optional[str] = None
+    created_at: str = ""
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "KkhayPaymentRecord":
+        return cls(
+            id=data.get("id", ""),
+            tx_hash=data.get("txHash", ""),
+            amount_received=str(data.get("amountReceived", "0")),
+            confirmations=int(data.get("confirmations", 0)),
+            status=data.get("status", ""),
+            forwarded_tx_hash=data.get("forwardedTxHash"),
+            created_at=data.get("createdAt", ""),
+        )
+
+
+@dataclass
+class KkhayInvoice:
+    id: str
+    merchant_id: str
+    price_amount: float
+    price_currency: str
+    pay_amount: str
+    pay_token: str
+    pay_network: str
+    deposit_address: str
+    status: str
+    fee_amount: str
+    net_amount: str
+    hosted_url: str
+    expires_at: str
+    created_at: str
+    order_id: Optional[str] = None
+    title: Optional[str] = None
+    settlement_mode: Optional[str] = None
+    payment_method: Optional[str] = None
+    redirect_url: Optional[str] = None
+    cancel_url: Optional[str] = None
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "KkhayInvoice":
+        return cls(
+            id=data.get("id", ""),
+            merchant_id=data.get("merchantId", ""),
+            price_amount=float(data.get("priceAmount", 0)),
+            price_currency=data.get("priceCurrency", "USD"),
+            pay_amount=str(data.get("payAmount", "0")),
+            pay_token=data.get("payToken", ""),
+            pay_network=data.get("payNetwork", ""),
+            deposit_address=data.get("depositAddress", ""),
+            status=data.get("status", "WAITING"),
+            fee_amount=str(data.get("feeAmount", "0")),
+            net_amount=str(data.get("netAmount", "0")),
+            hosted_url=data.get("hostedUrl", ""),
+            expires_at=data.get("expiresAt", ""),
+            created_at=data.get("createdAt", ""),
+            order_id=data.get("orderId"),
+            title=data.get("title"),
+            settlement_mode=data.get("settlementMode"),
+            payment_method=data.get("paymentMethod"),
+            redirect_url=data.get("redirectUrl"),
+            cancel_url=data.get("cancelUrl"),
+        )
+
+
+@dataclass
+class GetInvoiceResponse:
+    ok: bool
+    invoice: KkhayInvoice
+    payments: List[KkhayPaymentRecord] = field(default_factory=list)
+
+
+@dataclass
+class ListInvoicesResponse:
+    ok: bool
+    items: List[KkhayInvoice]
+    total_count: int
+    total_pages: int
+    current_page: int
+    limit: int
+
+
+@dataclass
+class KkhayWebhookEvent:
+    event: str
+    invoice_id: str
+    order_id: Optional[str]
+    price_amount: float
+    price_currency: str
+    pay_amount: str
+    pay_token: str
+    pay_network: str
+    deposit_address: str
+    status: str
+    timestamp: str
+    tx_hash: Optional[str] = None
+    raw_data: Dict[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "KkhayWebhookEvent":
+        return cls(
+            event=data.get("event", ""),
+            invoice_id=data.get("invoice_id", ""),
+            order_id=data.get("order_id"),
+            price_amount=float(data.get("price_amount", 0)),
+            price_currency=data.get("price_currency", "USD"),
+            pay_amount=str(data.get("pay_amount", "0")),
+            pay_token=data.get("pay_token", ""),
+            pay_network=data.get("pay_network", ""),
+            deposit_address=data.get("deposit_address", ""),
+            status=data.get("status", ""),
+            timestamp=data.get("timestamp", ""),
+            tx_hash=data.get("tx_hash"),
+            raw_data=data,
+        )
+

kkhay-1.0.0/kkhay/webhook.py

@@ -0,0 +1,69 @@
+import hashlib
+import hmac
+import json
+import secrets
+from typing import Any, Dict, Optional, Union
+
+from .errors import SignatureVerificationError
+from .types import KkhayWebhookEvent
+
+
+def verify_webhook_signature(
+    payload: Union[str, bytes, Dict[str, Any]],
+    signature: Optional[str] = None,
+    ipn_secret: Optional[str] = None,
+) -> bool:
+    """
+    Verifies the cryptographic HMAC-SHA256 signature sent with incoming K Khay IPN webhooks.
+
+    :param payload: The raw request body string, bytes, or parsed dict
+    :param signature: The signature header value ('x-kkhay-signature')
+    :param ipn_secret: Your merchant IPN Secret Key
+    :return: True if valid, False otherwise
+    """
+    if not signature or not ipn_secret:
+        return False
+
+    if isinstance(payload, bytes):
+        raw_bytes = payload
+    elif isinstance(payload, str):
+        raw_bytes = payload.encode("utf-8")
+    else:
+        raw_bytes = json.dumps(payload, separators=(",", ":")).encode("utf-8")
+
+    try:
+        secret_bytes = ipn_secret.encode("utf-8")
+        computed_hex = hmac.new(secret_bytes, raw_bytes, hashlib.sha256).hexdigest()
+        return secrets.compare_digest(computed_hex, signature.strip())
+    except Exception:
+        return False
+
+
+def parse_webhook_event(
+    raw_body: Union[str, bytes],
+    signature: Optional[str],
+    ipn_secret: str,
+) -> KkhayWebhookEvent:
+    """
+    Validates and safely parses an incoming K Khay webhook event.
+    Raises SignatureVerificationError if signature does not match.
+
+    :param raw_body: The raw request body
+    :param signature: The 'x-kkhay-signature' header value
+    :param ipn_secret: Your merchant IPN Secret Key
+    :return: Typed KkhayWebhookEvent
+    """
+    if not verify_webhook_signature(raw_body, signature, ipn_secret):
+        raise SignatureVerificationError("Invalid K Khay webhook signature: Request rejected.")
+
+    try:
+        if isinstance(raw_body, bytes):
+            text = raw_body.decode("utf-8")
+        else:
+            text = raw_body
+        data = json.loads(text)
+        return KkhayWebhookEvent.from_dict(data)
+    except Exception as e:
+        if isinstance(e, SignatureVerificationError):
+            raise
+        raise ValueError(f"Failed to parse webhook JSON payload: {e}") from e

kkhay-1.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kkhay"
+version = "1.0.0"
+description = "Official Python SDK for K Khay Sovereign Crypto Payment Gateway"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.8"
+authors = [
+    { name = "K Khay", email = "dev@kkhay.com" },
+]
+keywords = [
+    "kkhay",
+    "crypto",
+    "cryptocurrency",
+    "payments",
+    "payment-gateway",
+    "payment-processor",
+    "web3",
+    "blockchain",
+    "invoice",
+    "checkout",
+    "webhook",
+    "ipn",
+    "usdt",
+    "usdc",
+    "bnb",
+    "eth",
+    "bsc",
+    "polygon",
+    "arbitrum",
+    "base",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Office/Business :: Financial :: Point-Of-Sale",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://kkhay.com"
+Documentation = "https://docs.kkhay.com"
+Repository = "https://github.com/boboaungdev/kkhay-python"
+Issues = "https://github.com/boboaungdev/kkhay-python/issues"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/kkhay",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["kkhay"]
+