RudaXpay

TRC20-USDT Payments

Use one surface for hosted checkout, order tracking, settlement configuration, and operations control.

Hosted checkoutOrder routingUnified settlement

Language

EN 中文

Authentication

All API requests require an API key. Create and manage your keys in the Merchant Console → API Keys.

Request header

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

⚠ Keep your API key secure. Do not expose it in client-side code or public repositories.

Create Order

Create a payment order

Each order gets a unique TRC20 deposit address. The response includes a checkout_url for redirecting your customer to the hosted payment page.

Field	Type	Required	Description
merchant_order_no	string	✓	Your order reference (unique, idempotent)
amount	string	✓	Order amount in USDT (string to preserve precision)
currency	string	✓	Currency code (USDT)
network	string	✓	Blockchain network (TRC20)
subject	string		Order description shown to payer
notify_url	string		Webhook URL for payment status callbacks
return_url	string		Redirect URL after payment (user-facing)

Request

cURL

curl -X POST "https://cloud.rudaxpay.com/api/merchant/orders" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_order_no": "ORD-20260614-001",
    "amount": "100.00",
    "currency": "USDT",
    "network": "TRC20",
    "subject": "VIP subscription",
    "notify_url": "https://your-server.com/webhook",
    "return_url": "https://your-site.com/order/ORD-20260614-001"
  }'

Response

JSON

{
  "id": "po_a1b2c3d4e5f6g7h8",
  "merchant_order_no": "ORD-20260614-001",
  "status": "paying",
  "amount": "100.00",
  "currency": "USDT",
  "network": "TRC20",
  "asset": "USDT",
  "deposit_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "deposit_uri": "tron:TXXXXXXXXXXXXXXXXXXXXXXXXXXXXX?amount=100.00",
  "checkout_url": "https://your-domain.com/checkout/po_a1b2c3d4e5f6g7h8",
  "qr_code": "...",
  "expired_at": "2026-06-14T12:20:00.000Z",
  "subject": "VIP subscription"
}

Query Order

Query order status

Poll order status for reconciliation or display in your own dashboard.

Request

cURL

curl "https://cloud.rudaxpay.com/api/merchant/orders/po_xxx" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

JSON

{
  "id": "po_a1b2c3d4e5f6g7h8",
  "merchant_order_no": "ORD-20260614-001",
  "status": "paid",
  "amount": "100.00",
  "received_amount": "100.000000",
  "currency": "USDT",
  "network": "TRC20",
  "asset": "USDT",
  "deposit_address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "tx_hash": "abc123def456789...",
  "confirmed_at": "2026-06-14T10:30:00.000Z",
  "created_at": "2026-06-14T10:00:00.000Z"
}

Status values

payingAwaiting on-chain transfer

pending_confirmationTransaction detected, waiting for confirmations

paidPayment confirmed, funds credited to merchant balance

underpaidAmount received below expected

overpaidAmount received above expected (admin may issue refund)

expiredPayment window expired

exceptionManual review required

voidedCancelled by payer

Abandon Order

Abandon a paying order

When a payer decides not to complete the payment, the checkout page can abandon the order. This releases the deposit address immediately and notifies the merchant via webhook.

⚠ This endpoint is public (no API key required) — it is called from the hosted checkout page. Only orders in "paying" status can be abandoned.

Request

cURL

curl -X POST "https://cloud.rudaxpay.com/api/merchant/orders/po_xxx/abandon"

Response

JSON

{
  "id": "po_a1b2c3d4e5f6g7h8",
  "status": "voided"
}

Hosted Checkout

Hosted checkout page

After creating an order, redirect your customer to the checkout_url. The page handles the payment flow automatically:

• Displays deposit address and QR code
• Shows real-time payment status with confirmation progress
• Handles underpaid, overpaid, and expired states with clear messaging
• Supports English and Chinese (zh-CN) via ?locale= query parameter
• Auto-polls every 5 seconds until the order reaches a terminal state

Webhooks

Webhook verification

PaymentGateway sends signed POST requests to your notify_url when order status changes. Always verify the signature before processing.

Event types

payment.paidOrder payment confirmed

payment.voidedOrder cancelled by payer

Webhook headers

X-PG-EventEvent name (e.g. payment.paid)

X-PG-TimestampISO 8601 timestamp

X-PG-NonceRandom nonce

X-PG-SignatureHMAC-SHA256 signature: sha256=event:timestamp:nonce:secret

X-PG-Delivery-IdUnique delivery ID

Verify webhook signature

cURL

# Your server receives a POST with these headers:
# X-PG-Event: payment.paid
# X-PG-Timestamp: 2026-06-14T10:30:00.000Z
# X-PG-Nonce: a1b2c3d4e5f6g7h8
# X-PG-Signature: sha256=...
# X-PG-Delivery-Id: whd_...

# Verify the signature using your webhook secret

Retry policy

Webhooks use exponential backoff: 5min → 10min → 20min → 40min → 60min (capped). Max 8 attempts. Respond with HTTP 2xx to stop retries.

Error Codes

Error codes

All errors follow a consistent JSON structure.

Code	Description
auth.invalid_api_key	API key is missing, invalid, or disabled
merchant.order.invalid_payload	Request body is malformed or missing required fields
merchant.order.duplicate	merchant_order_no already exists — returns the existing order
merchant.order.amount_invalid	Amount is zero, negative, or not a valid number
merchant.order.address_pool_unavailable	No available deposit address — retry later
merchant.order.cannot_abandon	Order is not in "paying" status and cannot be abandoned
auth.session_expired	Merchant or admin session has expired
admin.order.not_found	Order ID does not exist

Rate Limits

Rate limits

V1 rate limits are enforced at the account level.

Operation	Limit
Create order	30 requests per minute
Query order	60 requests per minute
Webhook delivery	No rate limit on inbound delivery