TRC-20 USDT 商户 API

接入配置

后台创建并查询订单，付款人通过收银台使用 TronLink，链上固化后平台按订单发出到账通知。

从管理员取得商户号、API 密钥和回调验签密钥。可在下单时指定 HTTPS 回调地址，也可在门户配置商户默认地址。密钥保存在业务后台。

API 地址 https://pay-api.ignitions.ai。鉴权使用 Authorization: Bearer <API_KEY>。平台根据密钥识别商户。

创建支付订单

POST /v1/payments · Content-Type: application/json

同一商户以相同商户订单号和相同参数重试时返回原订单，包括保持 callback_url 的值及是否传入。保存 payment_id，把付款人带到 checkout_url。

curl https://pay-api.ignitions.ai/v1/payments -H "Authorization: Bearer ${MERCHANT_API_KEY}" -H 'Content-Type: application/json' --data-binary '{
  "merchant_order_id": "ORDER-1001",
  "amount_atomic": "12500000",
  "expires_at": "2030-01-01T12:00:00Z",
  "callback_url": "https://merchant.example.com/v1/webhooks/tron",
  "return_url": "https://merchant.example.com/wallet"
}'

响应示例

{
  "payment_id": "24c21b5f-78b7-404a-9b76-f0a610d182db",
  "merchant_order_id": "ORDER-1001",
  "amount_atomic": "12500000",
  "expires_at": "2030-01-01T12:00:00Z",
  "status": "PENDING",
  "checkout_url": "https://checkout.example.com/pay/#EXAMPLE_CHECKOUT_TOKEN"
}

查询支付订单

GET /v1/payments/{payment_id}

payment_id 是下单接口返回的 UUID。只查询本商户订单。已确认订单附带确认时间及交易 ID 列表。

curl https://pay-api.ignitions.ai/v1/payments/24c21b5f-78b7-404a-9b76-f0a610d182db -H "Authorization: Bearer ${MERCHANT_API_KEY}"

响应示例

{
  "payment_id": "24c21b5f-78b7-404a-9b76-f0a610d182db",
  "merchant_order_id": "ORDER-1001",
  "amount_atomic": "12500000",
  "expires_at": "2030-01-01T12:00:00Z",
  "status": "PAID",
  "paid_at": "2030-01-01T11:55:00Z",
  "txids": [
    "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
  ]
}

订单状态

以查单或已验签通知的 PAID 为入账依据。收银台跳转用于返回业务页面。

到账回调 payment.paid

平台通过 HTTPS POST 向下单时保存的地址投递，使用该商户的验签密钥签名。成功持久化后返回 204，重复事件同样返回 204。平台重试超时、HTTP 408、429 和 5xx，沿用地址、event_id 和原始正文，每次重新签名。管理员可重发最终失败的事件。投递时验证 DNS 和 HTTPS 证书，拒绝重定向及未经平台放行的 VPC 目标。

{
  "event_id": "payment.paid:24c21b5f-78b7-404a-9b76-f0a610d182db",
  "api_version": "v1",
  "type": "payment.paid",
  "occurred_at": "2030-01-01T11:55:00Z",
  "data": {
    "merchant_id": "holdem",
    "payment_id": "24c21b5f-78b7-404a-9b76-f0a610d182db",
    "merchant_order_id": "ORDER-1001",
    "amount_atomic": "12500000",
    "txids": [
      "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
    ]
  }
}

保留原始 HTTP 请求正文。使用独立回调密钥计算 HMAC-SHA256(timestamp + "." + rawBody)，验签后再解析 JSON。核对商户号、支付 ID、商户订单号和金额，使用 event_id 和本地订单唯一约束，在同一事务中去重和入账。

Node.js 验签示例

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyWebhook(rawBody, timestamp, signature, secret, now = Date.now()) {
  if (typeof timestamp !== 'string' || !/^\d{1,12}$/.test(timestamp) ||
      typeof signature !== 'string' || !/^sha256=[0-9a-f]{64}$/.test(signature) ||
      Math.abs(now - Number(timestamp) * 1000) > 300_000) return false;
  const expected = createHmac('sha256', secret)
    .update(timestamp).update('.').update(rawBody).digest();
  return timingSafeEqual(expected, Buffer.from(signature.slice(7), 'hex'));
}

版本记录

不兼容变更使用新的 API 主版本路径，旧版文档单独保留。