PayzCore Python SDK

Python client for the PayzCore blockchain transaction monitoring API.

Important

PayzCore is a blockchain monitoring service, not a payment processor. All payments are sent directly to your own wallet addresses. PayzCore never holds, transfers, or has access to your funds.

• Your wallets, your funds — You provide your own wallet (HD xPub or static addresses). Customers pay directly to your addresses.
• Read-only monitoring — PayzCore watches the blockchain for incoming transactions and sends webhook notifications. That's it.
• Protection Key security — Sensitive operations like wallet management, address changes, and API key regeneration require a Protection Key that only you set. PayzCore cannot perform these actions without your authorization.
• Your responsibility — You are responsible for securing your own wallets and private keys. PayzCore provides monitoring and notification only.

Installation

pip install payzcore

Quick Start

Payment Monitoring

from payzcore import PayzCore

client = PayzCore("pk_live_xxx")

# Create a payment monitoring request (network specified)
response = client.payments.create(
    amount=50,
    external_ref="user-123",
    network="TRC20",
)
payment = response["payment"]
print(f"Send {payment['amount']} {payment['token']} to {payment['address']}")
print(f"Expires at: {payment['expires_at']}")
# Static wallet projects may also return: payment['notice'], payment['original_amount'], payment['requires_txid']

# Or let the customer choose the network on the payment page
response = client.payments.create(
    amount=50,
    external_ref="user-123",
)
p = response["payment"]
print(p["awaiting_network"])    # True
print(p["payment_url"])         # "https://app.payzcore.com/pay/xxx"
print(p["available_networks"])  # [{"network": "TRC20", "name": "Tron", "tokens": ["USDT"]}, ...]

# Create a USDC payment on Polygon
response = client.payments.create(
    amount=100,
    external_ref="order-456",
    network="POLYGON",
    token="USDC",
)

# Create a payment with static wallet (dedicated mode)
response = client.payments.create(
    amount=50,
    external_ref="user-789",
    network="TRC20",
    address="Txxxx...",  # optional, static wallet dedicated mode only
)

# List payments
payments = client.payments.list(status="pending", limit=10)
for p in payments["payments"]:
    print(f"{p['id']}: {p['status']} ({p['expected_amount']} {p['token']})")
print(payments["pagination"]["has_more"])  # True if there is another page

# Poll for changes (webhook fallback): payments updated since a timestamp
changed = client.payments.list(updated_after="2026-10-15T00:00:00Z")

# Get payment details (latest cached status from database)
detail = client.payments.get("payment-uuid")
print(f"Status: {detail['payment']['status']}")
for tx in detail["payment"]["transactions"]:
    print(f"  TX: {tx['tx_hash']} - {tx['amount']} {detail['payment']['token']}")

# Cancel a pending payment
result = client.payments.cancel("payment-uuid")
# result["payment"]["status"] == "cancelled"

# Submit tx hash for verification (pool + txid mode)
result = client.payments.confirm("payment-uuid", "abc123def456...")
# result["verified"], result["status"], result["amount_received"]

Supported Networks and Tokens

The token parameter defaults to "USDT" if not specified, ensuring backward compatibility.

Project Management (Admin)

from payzcore import PayzCore

admin = PayzCore("mk_xxx", master_key=True)

# Create a project
project = admin.projects.create(
    name="My Store",
    slug="my-store",
    webhook_url="https://example.com/webhooks/payzcore",
)
print(f"API Key: {project['project']['api_key']}")

# List projects
projects = admin.projects.list()
for p in projects["projects"]:
    print(f"{p['name']} ({p['slug']}): {'active' if p['is_active'] else 'inactive'}")

Webhook Verification

from payzcore import verify_signature, construct_event, WebhookSignatureError

# In your webhook handler
def handle_webhook(request):
    body = request.body.decode("utf-8")
    signature = request.headers["X-PayzCore-Signature"]
    timestamp = request.headers["X-PayzCore-Timestamp"]
    secret = "whsec_xxx"  # From project creation

    try:
        event = construct_event(body, signature, secret, timestamp=timestamp)
    except WebhookSignatureError:
        return {"error": "Invalid signature"}, 401

    if event["event"] == "payment.completed":
        print(f"Payment {event['payment_id']} completed!")
        print(f"Amount: {event['paid_amount']} {event['token']} on {event['network']}")

    return {"ok": True}, 200

Note: The address parameter is only used with static wallet projects in dedicated mode. For HD wallet projects, this parameter is ignored.

Static Wallet Mode

When the PayzCore project is configured with a static wallet, the API works the same way but may return additional fields in the response:

In dedicated address mode, you can specify which static address to assign to a customer using the address parameter on payment creation. In shared address mode, the project's single static address is used automatically.

Before Going Live

Always test your setup before accepting real payments:

1. Verify your xPub — In the PayzCore dashboard, click "Verify Key" when adding your wallet. Compare address #0 with your wallet app's first receiving address. They must match.
2. Send a test payment — Create a monitoring request for $1–5 and send the funds to the assigned address. Verify they arrive in your wallet.
3. Test sweeping — Send the test funds back out to confirm you control the derived addresses with your private keys.

Warning: A wrong xPub key generates addresses you don't control. Funds sent to those addresses are permanently lost. PayzCore is watch-only and cannot recover funds. Please take 2 minutes to verify.

Configuration

client = PayzCore(
    "pk_live_xxx",
    base_url="https://api.payzcore.com",  # API base URL
    timeout=30.0,                          # Request timeout (seconds)
    max_retries=2,                         # Retries on 5xx/network errors (POST only when external_order_id is set)
    master_key=False,                      # Use x-master-key header
)

Error Handling

import time

from payzcore import (
    PayzCore,
    PayzCoreError,
    AuthenticationError,
    ValidationError,
    RateLimitError,
    NotFoundError,
)

client = PayzCore("pk_live_xxx")

try:
    payment = client.payments.create(
        amount=50, network="TRC20", external_ref="user-123"
    )
except AuthenticationError:
    print("Invalid API key")
except ValidationError as e:
    print(f"Invalid params: {e.message}")
except RateLimitError as e:
    # retry_after is a Unix timestamp (seconds), not a duration
    wait = max(0, (e.retry_after or 0) - int(time.time()))
    print(f"Rate limited. Daily: {e.is_daily}, retry in {wait}s")
except NotFoundError:
    print("Resource not found")
except PayzCoreError as e:
    print(f"API error {e.status}: {e.message}")

Error Classes

Requirements

• Python 3.9+
• httpx

See Also

• Getting Started — Account setup and first payment
• Authentication & API Keys — API key management
• Webhooks Guide — Events, headers, and signature verification
• Supported Networks — Available networks and tokens
• Error Reference — HTTP status codes and troubleshooting
• API Reference — Interactive API documentation (Scalar UI)

License

MIT