usdpay 1.0.0__tar.gz

usdpay-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,55 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install test dependencies
+        run: python -m pip install --upgrade pip pytest ruff
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+          cache: pip
+      - name: Install build tools
+        run: python -m pip install --upgrade pip build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Check distributions
+        run: python -m twine check dist/*
+      - name: Test clean wheel install
+        run: |
+          python -m venv /tmp/usdpay-wheel-test
+          /tmp/usdpay-wheel-test/bin/python -m pip install --no-deps dist/usdpay-1.0.0-py3-none-any.whl
+          /tmp/usdpay-wheel-test/bin/python -c "from usdpay import UsdpayClient, UsdpayApiError, verify_webhook_signature; assert UsdpayClient and UsdpayApiError and verify_webhook_signature"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error

usdpay-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+      - name: Build and validate distributions
+        run: |
+          python -m pip install --upgrade pip build twine
+          python -m build
+          python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

usdpay-1.0.0/.gitignore

@@ -0,0 +1,17 @@
+.env
+.env.*
+.venv/
+venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+*.egg-info/
+.DS_Store
+.idea/
+.vscode/

usdpay-1.0.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 1.0.0
+
+- Initial public release.
+- Create USDPAY invoices.
+- Retrieve invoice details.
+- List invoices.
+- Idempotency-Key support.
+- Structured API errors.
+- HMAC-SHA256 webhook signature verification.
+- Inline Python type hints.

usdpay-1.0.0/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.

usdpay-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,172 @@
+# 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/RELEASE_REPORT.md

@@ -0,0 +1,19 @@
+# Release report — 1.0.0
+
+This report is completed from local and GitHub Actions results before publishing the release.
+
+| Check | Status |
+| --- | --- |
+| Python 3.10 | PASS — 21 tests |
+| Python 3.11 | PASS — 21 tests |
+| Python 3.12 | PASS — 21 tests |
+| Python 3.13 | PASS — 21 tests |
+| Python 3.14 | PASS — 21 tests |
+| pytest | PASS |
+| ruff | PASS |
+| build | PASS — sdist and universal wheel |
+| twine check | PASS |
+| wheel install | PASS — clean virtual environment, no dependencies |
+| secret scan | PASS — Gitleaks and targeted patterns |
+
+Publication requires a PyPI Pending Trusted Publisher for project `usdpay`, owner `probizi`, repository `usdpay-python`, workflow `release.yml`, and environment `pypi`.

usdpay-1.0.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling>=1.27,<1.32"]
+build-backend = "hatchling.build"
+
+[project]
+name = "usdpay"
+version = "1.0.0"
+description = "Python SDK for accepting USDT payments directly to your wallet with automatic payment verification and webhooks."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "USDPAY" }
+]
+keywords = [
+  "usdpay",
+  "usdt",
+  "payments",
+  "payment-gateway",
+  "crypto-payments",
+  "payment-api",
+  "usdt-api",
+  "webhook",
+  "tron",
+  "trc20",
+  "ton",
+  "bep20",
+  "bsc"
+]
+classifiers = [
+  "Development Status :: 5 - Production/Stable",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "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",
+  "Typing :: Typed"
+]
+
+[project.urls]
+Homepage = "https://usdpay.me/"
+Documentation = "https://usdpay.me/docs/payments"
+Webhooks = "https://usdpay.me/webhooks"
+Security = "https://usdpay.me/security"
+Support = "https://usdpay.me/contact"
+Source = "https://github.com/probizi/usdpay-python"
+Issues = "https://github.com/probizi/usdpay-python/issues"
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2,<2",
+  "pytest>=8,<10",
+  "ruff>=0.9,<1",
+  "twine>=6,<7"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/usdpay"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

usdpay-1.0.0/src/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"