PayCow
Python SDK
Official zero-dependency Python client for the PayCow non-custodial USDT payment API, using standard library urllib, hmac, and typed exceptions.
paycow (Python)
Zero-dependency package with pyproject.toml and unit tests.
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"])
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 method | Backend endpoint | Required values |
|---|---|---|
create_payment | POST /api/payment/create | user_id, amount, network |
get_payment_status | GET /api/payment/status/:id | session_id |
verify_webhook | Local verification | raw_body, timestamp, signature, secret |