确认支付

通过提供链上交易哈希来手动确认支付。此接口使用请求体 accessSign 认证。

TIP

大多数情况下 HashNut 会自动检测链上支付，不需要调这个接口。 仅当自动检测迟迟没有反应，或你想主动把交易哈希告诉 HashNut 以加速确认时才用。

接口

POST /v4.0.0/pay/orders/confirm

请求体

字段	类型	必填	说明
payOrderId	string	是	HashNut 订单 ID（26 位 ULID）
merchantOrderId	string	是	您的订单标识符
payTxId	string	是	证明已支付的链上交易哈希，必须符合该链的格式
accessSign	string	是	创建订单时返回的 accessSign，原样回传

NOTE

Tron 订单的 payTxId 如果带 0x 前缀，服务端会自动去掉，两种写法都能接受。

请求示例

{
  "payOrderId": "01KWCGJ443GX4SCBQK53CTF04A",
  "merchantOrderId": "8b7eb554-b847-4450-9",
  "payTxId": "9f3c1d7e5a2b48c0913f6ed4a7b25c8e1049fba3762d5e08c41b9a6f3d072e21a",
  "accessSign": "BE333D8F1A561EFFCA7C0DCB88BC60C1EE67A00E6FBE02333270B8C68564679E"
}

响应示例

{
  "code": 0,
  "msg": "success",
  "data": null
}

调用成功只表示交易哈希已被受理，不代表订单已经支付成功：

• 如果这笔交易 HashNut 已经监听到，订单立刻转入 CONFIRMING (2)，随后等区块确认数达标转 SUCCESS (3)；
• 如果还没监听到，交易哈希会被记下，订单仍留在 INIT (0)，等链上监听到再往下走。

两种情况都要用查询订单读实际状态，不要假定调用成功就等于支付成功。 状态变更时也会发支付通知。

订单已部分支付时

如果订单当前是 PAID (1)（即已经短款支付过一次、正在等补款），这个接口会把 payTxId 记到最近一条补款记录上，而不是订单本身。此时需要先存在一条待支付的补款记录， 否则会返回 no supplement found。

常见错误

msg	含义
malformed pay order id	payOrderId 不是合法的 26 位 ULID
pay order not exist	订单不存在
invalid tx id	payTxId 不符合该链的交易哈希格式
access sign verify failed	accessSign 不匹配，确认是创建订单时返回的那个值
order already failed	订单已处于失败 / 过期 / 已取消（状态 < 0）
transaction already paid other order	这笔交易已经被用于另一笔订单
transaction already paid for this order	这笔交易已经提交过一次
no supplement found	订单是 PAID 状态但没有待支付的补款记录
order already paid or confirmed	订单已支付完成，且提交的哈希与订单记录的不一致

WARNING

payTxId 必须是真实存在、且确实转给该订单 receiptAddress、币种与链都匹配的交易。 币种或收款地址不匹配时接口会报错并拒绝，订单状态不变。

自动检测 vs 手动确认

特性	自动检测	手动确认
触发方式	HashNut 监听区块链	商户调用此接口
交易哈希	自动发现	由商户提供
使用场景	默认流程	检测延迟时的补救手段
调用后状态	不适用	已监听到 → CONFIRMING (2)；未监听到 → 仍为 INIT (0)