CHINAUSDT 多租户收银台
返回文章列表
接入HMACWebhookUSDT

用 HMAC 与 Webhook 把 USDT 收银台接到业务系统

说明 CHINAUSDT 下单签名、防重放与支付结果 Webhook 的对接要点，适合技术负责人做接入清单。

把业务系统接到 CHINAUSDT，核心只有两件事：你怎么可信地下单，以及我们怎么可信地通知你「已支付」。

下单：HMAC 签名串

收银台 API（如 POST /checkout/v1/orders）要求请求头携带：

  • X-ZLPay-Key
  • X-ZLPay-Timestamp
  • X-ZLPay-Nonce
  • X-ZLPay-Signature

待签串顺序固定为五行：

METHOD
PATH
TIMESTAMP
NONCE
SHA256_HEX(RAW_BODY)

签名使用项目密钥对上述字符串做 HMAC-SHA256，再转十六进制。注意：必须对原始 body 字节哈希，不要先反序列化再重序列化。

时间窗与 nonce 用于防重放；可选 X-ZLPay-Idempotency-Key 保证同一业务意图只建一单。

回执：Webhook

订单链上确认并结算后，CHINAUSDT 会向你配置的 webhook_url 推送事件（如 order.paid）。请：

  1. 用 webhook 密钥校验 X-ZLPay-Signature（常见形式为对 timestamp.body 做 HMAC）；
  2. 按 out_trade_no 幂等履约——已开通则勿重复延期；
  3. 返回 HTTP 2xx，否则会按退避策略重试。

业务字段（用户 ID、套餐、天数等）放在下单时的 notify_ref，Webhook 原样带回，支付系统本身不理解会员语义。

建议验收

  • 沙箱或小额主网：下单 → 付款 → 收到 Webhook → 业务侧只履约一次
  • 故意重放同一回调：状态不变
  • 签名缺 nonce / 改 body：应被拒

更完整的密钥与通道配置，登录 用户控制台 的 API 页查看。