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.
