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

pip install usdpay

Quick Start

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.

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

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

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.

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.

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

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
• Payment API documentation
• Webhook documentation
• Security
• Support

License

MIT © 2026 PIXELTIDE LLC.