Documentation/Python SDK
PYTHON 3.9+ CLIENT

PayCow
Python SDK

Official zero-dependency Python client for the PayCow non-custodial USDT payment API, using standard library urllib, hmac, and typed exceptions.

PY

paycow (Python)

Zero-dependency package with pyproject.toml and unit tests.

PYTHON 3.9+ZERO DEPENDENCIESHMAC WEBHOOKS

Installation

Extract the archive and install the package into your Python environment.

cd paycow-python-sdk
pip install .

To run the included unit tests:

python3 -m unittest discover -s tests -v

Store your API key and API secret in server-side environment variables.

Create a payment

create_payment calls POST /api/payment/create and returns the PayCow session payload including paymentUrl, payableAmount, and depositAddress.

import os
from paycow import PayCowClient

client = PayCowClient(
    api_key=os.environ["PAYCOW_API_KEY"],
    api_secret=os.environ["PAYCOW_API_SECRET"],
)

payment = client.create_payment(
    user_id="customer-2048",
    amount=50.00,
    network="TRC20",
    address_serial_no="WAL-1002",
    idempotency_key="order-2048-001",
)

print(payment["sessionId"])
print(payment["paymentUrl"])
print(payment["payableAmount"])
Always display or forward payableAmount as the exact USDT transfer amount. Set payment_method="ONRAMP" only for eligible Pro, Scale, or Enterprise merchants.

Retrieve payment status

Query the authoritative payment status from PayCow by session ID.

status = client.get_payment_status("66ce30d74c0c51a48f2d2903")

if status.get("status") == "PAID":
    credit_order_once(status["userId"], status["paymentReference"])

Verify webhooks

Pass the raw request body bytes, the timestamp and signature headers, and your webhook secret to verify_webhook.

from paycow import verify_webhook

event = verify_webhook(
    raw_body=request.body,
    timestamp=request.headers["X-PayCow-Timestamp"],
    signature=request.headers["X-PayCow-Signature"],
    secret=os.environ["PAYCOW_WEBHOOK_SECRET"],
)

if event.get("status") == "PAID":
    credit_order_once(event["userId"], event["paymentReference"])

verify_webhook checks the 300-second replay window, computes HMAC-SHA256 over timestamp.rawBody, and compares signatures in constant time.

Error handling

Validation failures raise PayCowValidationError; non-2xx API responses raise PayCowApiError.

from paycow import PayCowApiError, PayCowValidationError

try:
    payment = client.create_payment(user_id="cust-1", amount=25, network="TRC20")
except PayCowValidationError as exc:
    print("Invalid input:", exc)
except PayCowApiError as exc:
    print("API error:", exc.status_code, exc.payload)

API contract

SDK methodBackend endpointRequired values
create_paymentPOST /api/payment/createuser_id, amount, network
get_payment_statusGET /api/payment/status/:idsession_id
verify_webhookLocal verificationraw_body, timestamp, signature, secret