收款单 API

创建收款单 POST /v1/payments

• amount 为代币本位十进制字符串（如 USDT 6 位小数），禁止用 Number 以免精度丢失。
• 收款二维码请直接编码响应中的 address（Base58）；金额与币种在收银台展示，引导用户选择正确网络与代币并填入 amount。
• 同一商户 orderNo 重复创建返回 409；参数校验失败返回 400。

请求

POST {baseUrl}/v1/payments
Content-Type: application/json
Authorization: Influx-HMAC-SHA256 ApiKey=<ApiKey>,Timestamp=<unix秒>,Signature=<hex>

{
  "orderNo": "ORDER-20260428-0001",
  "tokenSymbol": "USDT",
  "amount": "10.50",
  "expireSec": 1800,
  "notifyUrl": "https://merchant.example.com/webhook",
  "metadata": { "userId": "u_123" }
}

字段	必填	说明
orderNo	是	商户侧唯一订单号
tokenSymbol	是	须与本环境支持的代币一致（通常 USDT）
amount	是	代币本位金额字符串
expireSec	是	正整数，订单有效秒数
notifyUrl	是	HTTPS，用于接收 payment.paid
metadata	否	任意 JSON，仅存储，不回显于 API 响应

成功响应 200

{
  "paymentId": "p_01HXXX...",
  "address": "TXxxxxxxxx...",
  "amount": "10.50",
  "amountRaw": "10500000",
  "tokenContract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "tokenSymbol": "USDT",
  "paymentNetwork": "TRC20",
  "expireAt": "2026-04-28T17:00:00.000Z",
  "status": "PENDING"
}

字段	说明
paymentId	系统订单 ID，查询与 Webhook 均用此字段
address	收款地址（Base58）
amount / amountRaw	应付金额（本位字符串 / 最小单位整数字符串）
paymentNetwork	收款链族（首期常为 TRC20，后续可扩展）
status	初始为 PENDING

错误示例

{ "error": "BAD_REQUEST", "message": "Invalid amount" }

{ "error": "UNAUTHORIZED", "message": "Invalid merchant HMAC signature" }

{ "error": "CONFLICT", "message": "Payment order already exists" }

---

查询订单 GET /v1/payments/:paymentId

路径参数 paymentId 为创建订单时返回的 paymentId。

status：PENDING（待付）、PARTIAL（部分到账）、PAID（已付清）、EXPIRED（已过期）、CANCELED（已取消）。

paidAmount、paidTxId、blockNum、paidAt 仅在已到账相关状态时非 null；未到账时 confirmations 为 0。

请求

GET {baseUrl}/v1/payments/p_01HXXX
Authorization: Influx-HMAC-SHA256 ApiKey=<ApiKey>,Timestamp=<unix秒>,Signature=<hex>

成功响应 200（待支付）

{
  "paymentId": "p_01HXXX...",
  "orderNo": "ORDER-20260428-0001",
  "status": "PENDING",
  "address": "TXxxxxxxxx...",
  "amount": "10.50",
  "amountRaw": "10500000",
  "tokenContract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "tokenSymbol": "USDT",
  "paymentNetwork": "TRC20",
  "expireAt": "2026-04-28T17:00:00.000Z",
  "paidAmount": null,
  "paidTxId": null,
  "blockNum": null,
  "confirmations": 0,
  "paidAt": null
}

成功响应 200（已支付）

{
  "paymentId": "p_01HXXX...",
  "orderNo": "ORDER-20260428-0001",
  "status": "PAID",
  "address": "TXxxxxxxxx...",
  "amount": "10.50",
  "amountRaw": "10500000",
  "tokenContract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
  "tokenSymbol": "USDT",
  "paymentNetwork": "TRC20",
  "expireAt": "2026-04-28T17:00:00.000Z",
  "paidAmount": "10.50",
  "paidTxId": "abc123def456...",
  "blockNum": "62000000",
  "confirmations": 22,
  "paidAt": "2026-04-28T16:32:10.000Z"
}

错误示例

{ "error": "NOT_FOUND", "message": "Payment not found" }