usdpay 1.0.0__py3-none-any.whl

usdpay/__init__.py

@@ -0,0 +1,13 @@
+"""Official Python SDK for the USDPAY Payments API."""
+
+from .client import UsdpayClient
+from .exceptions import UsdpayApiError
+from .webhook import verify_webhook_signature
+
+__all__ = [
+    "UsdpayClient",
+    "UsdpayApiError",
+    "verify_webhook_signature",
+]
+
+__version__ = "1.0.0"

usdpay/client.py

@@ -0,0 +1,266 @@
+"""Synchronous client for the public USDPAY Payments API."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from typing import Any
+from urllib.parse import quote, urlsplit
+
+from .exceptions import UsdpayApiError
+from .transport import HttpResponse, HttpTransport, Transport, TransportError, TransportTimeout
+
+SDK_VERSION = "1.0.0"
+DEFAULT_BASE_URL = "https://usdpay.me"
+DEFAULT_TIMEOUT = 10.0
+DEFAULT_CONNECT_TIMEOUT = 5.0
+
+_IDEMPOTENCY_KEY = re.compile(r"^[A-Za-z0-9._:-]{1,160}$")
+_SENSITIVE_KEY = re.compile(r"authorization|api.?key|secret|token|password", re.IGNORECASE)
+
+
+class UsdpayClient:
+    """A typed, synchronous client for creating and inspecting invoices."""
+
+    def __init__(
+        self,
+        secret_key: str,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        connect_timeout: float = DEFAULT_CONNECT_TIMEOUT,
+        *,
+        _transport: Transport | None = None,
+    ) -> None:
+        if not isinstance(secret_key, str) or not secret_key.strip():
+            raise ValueError("secret_key is required")
+        if "\r" in secret_key or "\n" in secret_key:
+            raise ValueError("secret_key must not contain line breaks")
+
+        self._secret_key = secret_key
+        self.base_url = _normalize_base_url(base_url)
+        self.timeout = _positive_timeout(timeout, "timeout")
+        self.connect_timeout = _positive_timeout(connect_timeout, "connect_timeout")
+        self._transport = _transport or HttpTransport()
+
+    def __repr__(self) -> str:
+        return (
+            f"UsdpayClient(base_url={self.base_url!r}, timeout={self.timeout!r}, "
+            f"connect_timeout={self.connect_timeout!r})"
+        )
+
+    def create_invoice(
+        self,
+        payload: Mapping[str, Any],
+        idempotency_key: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a payment invoice with an optional stable idempotency key."""
+
+        if not isinstance(payload, Mapping):
+            raise TypeError("payload must be a mapping")
+        amount = payload.get("amount")
+        if not isinstance(amount, str) or not amount.strip():
+            raise ValueError("amount must be a non-empty decimal string")
+
+        headers: dict[str, str] = {}
+        if idempotency_key is not None:
+            if not isinstance(idempotency_key, str) or not _IDEMPOTENCY_KEY.fullmatch(
+                idempotency_key
+            ):
+                raise ValueError(
+                    "idempotency_key must contain 1-160 letters, digits, dots, "
+                    "underscores, colons, or hyphens"
+                )
+            headers["Idempotency-Key"] = idempotency_key
+
+        try:
+            body = json.dumps(
+                dict(payload),
+                ensure_ascii=False,
+                separators=(",", ":"),
+                allow_nan=False,
+            ).encode("utf-8")
+        except (TypeError, ValueError) as exc:
+            raise ValueError("payload must contain JSON-serializable values") from exc
+
+        return self._request(
+            "POST",
+            "/api/invoices",
+            body=body,
+            authenticated=True,
+            extra_headers=headers,
+        )
+
+    def get_invoice(self, invoice_id: str) -> dict[str, Any]:
+        """Retrieve public checkout status without sending the secret key."""
+
+        if not isinstance(invoice_id, str) or not invoice_id.strip():
+            raise ValueError("invoice_id is required")
+        return self._request(
+            "GET",
+            "/api/invoices/" + quote(invoice_id.strip(), safe=""),
+            authenticated=False,
+        )
+
+    def list_invoices(self) -> dict[str, Any]:
+        """List invoices that belong to the store selected by the secret key."""
+
+        return self._request("GET", "/api/invoices", authenticated=True)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        body: bytes | None = None,
+        authenticated: bool,
+        extra_headers: Mapping[str, str] | None = None,
+    ) -> dict[str, Any]:
+        headers = {
+            "Accept": "application/json",
+            "User-Agent": f"usdpay-python/{SDK_VERSION}",
+        }
+        if authenticated:
+            headers["Authorization"] = "Bearer " + self._secret_key
+        if body is not None:
+            headers["Content-Type"] = "application/json"
+        if extra_headers:
+            headers.update(extra_headers)
+
+        try:
+            response = self._transport.send(
+                method,
+                self.base_url + path,
+                headers,
+                body,
+                self.timeout,
+                self.connect_timeout,
+            )
+        except TransportTimeout:
+            raise UsdpayApiError(
+                "USDPAY request timed out",
+                code="request_timeout",
+            ) from None
+        except TransportError:
+            raise UsdpayApiError(
+                "Could not reach USDPAY",
+                code="network_error",
+            ) from None
+        except Exception:
+            # Custom transports are permitted for tests, but their internals and
+            # request headers must never leak through a public exception.
+            raise UsdpayApiError(
+                "Could not reach USDPAY",
+                code="network_error",
+            ) from None
+
+        if not 200 <= response.status < 300:
+            raise self._http_error(response)
+        return self._decode_success(response)
+
+    def _decode_success(self, response: HttpResponse) -> dict[str, Any]:
+        if not response.body:
+            return {}
+        decoded = _decode_json_object(response.body)
+        if decoded is None:
+            raise UsdpayApiError(
+                "USDPAY returned invalid JSON",
+                status=response.status,
+                code="invalid_response",
+                request_id=_clean_header(response.header("X-Request-ID"), self._secret_key),
+            )
+        return decoded
+
+    def _http_error(self, response: HttpResponse) -> UsdpayApiError:
+        decoded = _decode_json_object(response.body) if response.body else None
+        redacted = _redact(decoded, self._secret_key) if decoded is not None else None
+
+        code = "request_failed"
+        if decoded is not None and isinstance(decoded.get("error"), str):
+            candidate = decoded["error"].strip()
+            if candidate and self._secret_key not in candidate:
+                code = candidate
+
+        request_id = _clean_header(response.header("X-Request-ID"), self._secret_key)
+        if decoded is not None and isinstance(decoded.get("requestId"), str):
+            candidate_request_id = _clean_header(decoded["requestId"], self._secret_key)
+            if candidate_request_id:
+                request_id = candidate_request_id
+
+        retry_after = _retry_after(response.header("Retry-After"), self._secret_key)
+        return UsdpayApiError(
+            f"USDPAY request failed with HTTP {response.status} ({code})",
+            status=response.status,
+            code=code,
+            details=redacted,
+            retry_after=retry_after,
+            request_id=request_id,
+        )
+
+
+def _normalize_base_url(base_url: str) -> str:
+    if not isinstance(base_url, str):
+        raise TypeError("base_url must be a string")
+    normalized = base_url.strip().rstrip("/")
+    target = urlsplit(normalized)
+    if (
+        not normalized
+        or target.scheme != "https"
+        or not target.hostname
+        or target.username is not None
+        or target.password is not None
+        or target.query
+        or target.fragment
+        or target.path not in ("", "/")
+    ):
+        raise ValueError("base_url must be an HTTPS origin")
+    return normalized
+
+
+def _positive_timeout(value: float, name: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise TypeError(f"{name} must be a number")
+    number = float(value)
+    if not math.isfinite(number) or number <= 0:
+        raise ValueError(f"{name} must be greater than zero")
+    return number
+
+
+def _decode_json_object(body: bytes) -> dict[str, Any] | None:
+    try:
+        decoded = json.loads(body.decode("utf-8"))
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return None
+    return decoded if isinstance(decoded, dict) else None
+
+
+def _clean_header(value: str | None, secret: str) -> str | None:
+    if value is None:
+        return None
+    cleaned = value.strip()
+    if not cleaned or secret in cleaned:
+        return None
+    return cleaned
+
+
+def _retry_after(value: str | None, secret: str) -> int | str | None:
+    cleaned = _clean_header(value, secret)
+    if cleaned is None:
+        return None
+    return int(cleaned) if cleaned.isdigit() else cleaned
+
+
+def _redact(value: Any, secret: str, key: str | None = None) -> Any:
+    if key is not None and _SENSITIVE_KEY.search(key):
+        return "[REDACTED]"
+    if isinstance(value, str):
+        return value.replace(secret, "[REDACTED]")
+    if isinstance(value, list):
+        return [_redact(item, secret) for item in value]
+    if isinstance(value, dict):
+        return {
+            item_key: _redact(item_value, secret, str(item_key))
+            for item_key, item_value in value.items()
+        }
+    return value

usdpay/exceptions.py

@@ -0,0 +1,26 @@
+"""Exceptions raised by the USDPAY SDK."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class UsdpayApiError(RuntimeError):
+    """A structured HTTP, transport, or response error from the USDPAY API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: str = "request_failed",
+        details: Any = None,
+        retry_after: int | str | None = None,
+        request_id: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.details = details
+        self.retry_after = retry_after
+        self.request_id = request_id

usdpay/py.typed

@@ -0,0 +1 @@
+

usdpay/transport.py

@@ -0,0 +1,109 @@
+"""Small HTTPS transport used by the synchronous USDPAY client."""
+
+from __future__ import annotations
+
+import http.client
+import ssl
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Protocol
+from urllib.parse import SplitResult, urlsplit
+
+
+@dataclass(frozen=True)
+class HttpResponse:
+    """Transport response consumed by :class:`usdpay.UsdpayClient`."""
+
+    status: int
+    body: bytes
+    headers: Mapping[str, str]
+
+    def header(self, name: str) -> str | None:
+        return self.headers.get(name.lower())
+
+
+class Transport(Protocol):
+    """Internal transport interface used to keep HTTP behavior testable."""
+
+    def send(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        timeout: float,
+        connect_timeout: float,
+    ) -> HttpResponse: ...
+
+
+class TransportError(Exception):
+    """The remote service could not be reached."""
+
+
+class TransportTimeout(TransportError):
+    """The connection or response exceeded its configured timeout."""
+
+
+class HttpTransport:
+    """Zero-dependency HTTPS transport with certificate verification enabled."""
+
+    def __init__(self, *, ssl_context: ssl.SSLContext | None = None) -> None:
+        self._ssl_context = ssl_context or ssl.create_default_context()
+
+    def send(
+        self,
+        method: str,
+        url: str,
+        headers: Mapping[str, str],
+        body: bytes | None,
+        timeout: float,
+        connect_timeout: float,
+    ) -> HttpResponse:
+        target = _validated_https_url(url)
+        host = target.hostname
+        if host is None:  # Kept explicit for static type checkers.
+            raise TransportError("HTTPS URL has no hostname")
+
+        connection = http.client.HTTPSConnection(
+            host,
+            target.port or 443,
+            timeout=connect_timeout,
+            context=self._ssl_context,
+        )
+        request_target = target.path or "/"
+        if target.query:
+            request_target += "?" + target.query
+
+        try:
+            connection.request(method, request_target, body=body, headers=dict(headers))
+            if connection.sock is not None:
+                connection.sock.settimeout(timeout)
+            response = connection.getresponse()
+            response_body = response.read()
+            response_headers: dict[str, str] = {}
+            for name, value in response.getheaders():
+                normalized = name.lower()
+                if normalized in response_headers:
+                    response_headers[normalized] += ", " + value
+                else:
+                    response_headers[normalized] = value
+            return HttpResponse(response.status, response_body, response_headers)
+        except TimeoutError as exc:
+            raise TransportTimeout("HTTPS request timed out") from exc
+        except (OSError, http.client.HTTPException) as exc:
+            raise TransportError("HTTPS request failed") from exc
+        finally:
+            connection.close()
+
+
+def _validated_https_url(url: str) -> SplitResult:
+    target = urlsplit(url)
+    if (
+        target.scheme != "https"
+        or not target.hostname
+        or target.username is not None
+        or target.password is not None
+        or target.fragment
+    ):
+        raise TransportError("transport requires an HTTPS URL without credentials or fragment")
+    return target

usdpay/webhook.py

@@ -0,0 +1,40 @@
+"""Helpers for authenticating USDPAY webhook deliveries."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+
+
+def verify_webhook_signature(
+    raw_body: bytes | bytearray | memoryview | str,
+    signature: str,
+    secret: bytes | str,
+) -> bool:
+    """Return whether ``signature`` is the HMAC-SHA256 of the unparsed body.
+
+    USDPAY sends signatures as ``sha256=<lowercase hex digest>``. Call this
+    function before decoding JSON, and pass the exact bytes received over HTTP.
+    """
+
+    if isinstance(raw_body, str):
+        body = raw_body.encode("utf-8")
+    elif isinstance(raw_body, (bytes, bytearray, memoryview)):
+        body = bytes(raw_body)
+    else:
+        raise TypeError("raw_body must be bytes-like or str")
+
+    if isinstance(secret, str):
+        secret_bytes = secret.encode("utf-8")
+    elif isinstance(secret, bytes):
+        secret_bytes = secret
+    else:
+        raise TypeError("secret must be bytes or str")
+    if not secret_bytes:
+        raise ValueError("webhook secret is required")
+
+    received = signature.strip() if isinstance(signature, str) else ""
+    expected = "sha256=" + hmac.new(secret_bytes, body, hashlib.sha256).hexdigest()
+    if len(received) != len(expected):
+        return False
+    return hmac.compare_digest(received, expected)

usdpay-1.0.0.dist-info/METADATA

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: usdpay
+Version: 1.0.0
+Summary: Python SDK for accepting USDT payments directly to your wallet with automatic payment verification and webhooks.
+Project-URL: Homepage, https://usdpay.me/
+Project-URL: Documentation, https://usdpay.me/docs/payments
+Project-URL: Webhooks, https://usdpay.me/webhooks
+Project-URL: Security, https://usdpay.me/security
+Project-URL: Support, https://usdpay.me/contact
+Project-URL: Source, https://github.com/probizi/usdpay-python
+Project-URL: Issues, https://github.com/probizi/usdpay-python/issues
+Author: USDPAY
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bep20,bsc,crypto-payments,payment-api,payment-gateway,payments,ton,trc20,tron,usdpay,usdt,usdt-api,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.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: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Requires-Dist: twine<7,>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# USDPAY Python SDK
+
+Official Python SDK for USDPAY.
+
+Accept USDT directly to your wallet. USDPAY verifies the payment on-chain and notifies your application automatically with signed webhooks.
+
+## Requirements
+
+- Python 3.10 or newer
+- A USDPAY store secret key for authenticated methods
+- A server-side application; never expose the secret key in browser or mobile code
+
+## Installation
+
+```bash
+pip install usdpay
+```
+
+## Quick Start
+
+```python
+import os
+
+from usdpay import UsdpayClient
+
+client = UsdpayClient(
+    secret_key=os.environ["USDPAY_SECRET"]
+)
+
+result = client.create_invoice(
+    {
+        "amount": "49.00",
+        "orderId": "ORDER-1042",
+        "network": "TRC20",
+        "callbackUrl": "https://merchant.example/usdpay/webhook",
+        "returnUrl": "https://merchant.example/orders/1042",
+    },
+    idempotency_key="ORDER-1042-create",
+)
+
+print(result["invoice"]["checkoutUrl"])
+```
+
+## Create an Invoice
+
+`create_invoice()` sends `POST /api/invoices`. JSON field names match the REST API exactly.
+
+```python
+result = client.create_invoice(
+    {
+        "amount": "49.00",
+        "orderId": "ORDER-1042",
+        "network": "TRC20",
+        "expiresInMinutes": 30,
+        "callbackUrl": "https://merchant.example/usdpay/webhook",
+        "returnUrl": "https://merchant.example/orders/1042",
+    },
+    idempotency_key="ORDER-1042-create",
+)
+```
+
+Omit `network` to let the customer choose an enabled network in the hosted checkout.
+
+## Get an Invoice
+
+```python
+result = client.get_invoice("inv_7Fq2xK9")
+print(result["invoice"]["status"])
+```
+
+The production API exposes this status endpoint to anyone who has the unguessable invoice ID. The SDK therefore does not send your Bearer key with `get_invoice()`.
+
+## List Invoices
+
+```python
+result = client.list_invoices()
+for invoice in result["invoices"]:
+    print(invoice["id"], invoice["status"])
+```
+
+`list_invoices()` is authenticated and returns invoices for the store selected by the secret key. The current API does not define filtering or pagination parameters, so the SDK does not invent any.
+
+## Fiat Order Amounts
+
+Keep monetary values as decimal strings. USDPAY performs the currency conversion; the SDK does not use floating-point math or calculate FX rates.
+
+```python
+result = client.create_invoice(
+    {
+        "amount": "49.00",
+        "currency": "EUR",
+        "orderId": "ORDER-1042",
+        "callbackUrl": "https://merchant.example/usdpay/webhook",
+    },
+    idempotency_key="ORDER-1042-create",
+)
+```
+
+## Idempotency
+
+Pass one stable `idempotency_key` for a logical create operation. If a timeout, `429`, or retryable `5xx` occurs, retry with the same key. Do not generate a new key for each attempt.
+
+USDPAY accepts 1–160 letters, digits, dots, underscores, colons, or hyphens. The SDK validates the key but does not automatically retry requests.
+
+## Verify Webhooks
+
+Verify the signature against the exact raw request body before parsing JSON.
+
+```python
+import os
+
+from usdpay import verify_webhook_signature
+
+raw_body = request_body_bytes
+signature = request_headers.get("X-USDPAY-Signature", "")
+
+if not verify_webhook_signature(
+    raw_body,
+    signature,
+    os.environ["USDPAY_WEBHOOK_SECRET"],
+):
+    # Return HTTP 401.
+    ...
+```
+
+The signature format is `sha256=<hex HMAC-SHA256>`. Store `X-USDPAY-Idempotency-Key` under a unique database constraint before fulfilling an order, and acknowledge an already processed delivery with a `2xx` response.
+
+## Error Handling
+
+```python
+from usdpay import UsdpayApiError
+
+try:
+    client.create_invoice(
+        {"amount": "49.00", "orderId": "ORDER-1042"},
+        idempotency_key="ORDER-1042-create",
+    )
+except UsdpayApiError as exc:
+    print(exc.status)
+    print(exc.code)
+    print(exc.retry_after)
+    print(exc.request_id)
+```
+
+`UsdpayApiError` covers HTTP failures, timeouts, network failures, and malformed JSON. Its public attributes are:
+
+- `status`: HTTP status, or `0` when no HTTP response was received
+- `code`: stable API or SDK error code
+- `details`: redacted response object when available
+- `retry_after`: parsed `Retry-After` seconds or HTTP-date
+- `request_id`: response request identifier for support
+
+## Security
+
+- Keep `USDPAY_SECRET` and the webhook signing secret on your server.
+- The default transport accepts HTTPS only and uses Python's verified system trust store with hostname verification.
+- Requests have finite connect and response timeouts; configure them with `connect_timeout` and `timeout`.
+- The client does not follow redirects or make network calls when imported.
+- Secrets are not included in `repr(client)`, public exception messages, or exception details.
+- Never disable TLS verification.
+
+## Documentation
+
+- [Official website](https://usdpay.me/)
+- [Payment API documentation](https://usdpay.me/docs/payments)
+- [Webhook documentation](https://usdpay.me/webhooks)
+- [Security](https://usdpay.me/security)
+- [Support](https://usdpay.me/contact)
+
+## License
+
+[MIT](LICENSE) © 2026 PIXELTIDE LLC.

usdpay-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+usdpay/__init__.py,sha256=7L0w5VZTuHH0yhyWPGBQj95I12TIicVRpDWBunMijow,286
+usdpay/client.py,sha256=cllUU3RMtL3Clo2fc_lJpNJXLKq1t_LS84NdHikFbgk,9341
+usdpay/exceptions.py,sha256=NAEt-P9O2rR7WKijxc75_dht7AbrwaznWMJpXd683ps,673
+usdpay/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+usdpay/transport.py,sha256=vuEXnsKtEifD9BLTTGYOTQUqqs6JYD2fndwQeL3AYlE,3421
+usdpay/webhook.py,sha256=GGbBZZT2Li8uxCxuEGIIHInNzThZvPfbK8TMbrvB0jc,1304
+usdpay-1.0.0.dist-info/METADATA,sha256=21n-1vui61OeGivhkq2beozEi2PbTcxTYAXV49gA5Uw,6485
+usdpay-1.0.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+usdpay-1.0.0.dist-info/licenses/LICENSE,sha256=kTY14J2FROteaZgWL09PFrUFdbYohOnJVAI3YVe5EDQ,1070
+usdpay-1.0.0.dist-info/RECORD,,

usdpay-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

usdpay-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PIXELTIDE LLC
+
+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.