RudaXpay

RudaXpay

TRC20-USDT 支付网关

用一个入口统一承载托管支付、订单追踪、结算配置与运营控制。

托管支付页订单路由统一结算
登录
语言
EN中文

鉴权

鉴权

所有 API 请求需要 API Key。在商户控制台 → API Keys 中创建和管理密钥。

请求头

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

⚠ 请妥善保管 API Key，不要暴露在客户端代码或公开仓库中。

创建订单

创建支付订单

每个订单分配一个独立的 TRC20 收款地址。返回的 checkout_url 可直接跳转到托管支付页。

字段类型必填说明
merchant_order_nostring✓商户订单号（唯一，幂等）
amountstring✓订单金额 USDT（字符串以保留精度）
currencystring✓币种（USDT）
networkstring✓区块链网络（TRC20）
subjectstring订单描述（展示给付款方）
notify_urlstringWebhook 回调地址
return_urlstring支付完成后用户点击「返回商户」的跳转地址

请求

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"
  }'

响应

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"
}

查询订单

查询订单状态

轮询订单状态用于对账或在自有后台展示。

请求

cURL

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

响应

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"
}

状态值

paying等待链上转账
pending_confirmation已检测到转账，等待确认
paid支付已确认，已记入商户余额
underpaid到账金额不足
overpaid到账金额超出（管理员可执行退款）
expired支付窗口已过期
exception需人工处理
voided付款方已取消

放弃支付

放弃支付订单

付款方在托管支付页决定放弃支付时，可调用此端点作废订单。系统立即释放收款地址并通知商户。

⚠ 此端点为公开接口（无需 API Key），由托管支付页直接调用。仅"paying"状态的订单可被放弃。

请求

cURL

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

响应

JSON

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

托管支付页

托管支付页

创建订单后，将客户跳转到 checkout_url。支付页自动处理以下流程：

  • • 展示收款地址和二维码
  • • 实时显示支付状态和确认进度
  • • 对少付、超付、过期等异常状态给出清晰提示
  • • 支持中英文切换（通过 ?locale=zh-CN 参数）
  • • 每 5 秒自动轮询，直到订单进入终态

Webhook

Webhook 验签

订单状态变化时，PaymentGateway 会向您的 notify_url 发送签名 POST 请求。处理前请务必验证签名。

事件类型

payment.paid订单支付已确认
payment.voided订单被付款方取消

Webhook 请求头

X-PG-Event事件名（如 payment.paid）
X-PG-TimestampISO 8601 时间戳
X-PG-Nonce随机 nonce
X-PG-SignatureHMAC-SHA256 签名：sha256=event:timestamp:nonce:secret
X-PG-Delivery-Id唯一投递 ID

验证 Webhook 签名

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

重试策略

指数退避：5分钟 → 10分钟 → 20分钟 → 40分钟 → 60分钟（上限）。最多重试 8 次。返回 HTTP 2xx 即停止重试。

错误码

错误码

所有错误遵循统一的 JSON 结构。

错误码说明
auth.invalid_api_keyAPI Key 缺失、无效或已禁用
merchant.order.invalid_payload请求体格式错误或缺少必填字段
merchant.order.duplicatemerchant_order_no 重复 — 返回已有订单
merchant.order.amount_invalid金额为零、负数或格式无效
merchant.order.address_pool_unavailable暂无可用收款地址 — 请稍后重试
merchant.order.cannot_abandon订单状态非 paying，无法放弃
auth.session_expired商户或管理员会话已过期
admin.order.not_found订单 ID 不存在

频率限制

频率限制

V1 按账户级别限频。

操作限制
创建订单每分钟 30 次
查询订单每分钟 60 次
Webhook 投递入站投递不限频