取消订单

取消尚未支付完成的支付订单。此接口使用请求头 HMAC 签名。

接口

POST /v4.0.0/api/orders/cancel

请求体

字段	类型	必填	说明
payOrderId	string	是	HashNut 订单 ID

请求体只需要 payOrderId——商户身份由请求头签名和订单自身的归属关系确定，不需要再传 accessKeyId。

请求头

参见认证签名了解所需的 HMAC 签名请求头：

• hashnut-request-uuid
• hashnut-request-timestamp
• hashnut-request-sign

请求示例

{
  "payOrderId" : "01KWCGJ443GX4SCBQK53CTF04A"
}

响应示例

{
  "code" : 0,
  "msg" : "success",
  "ui" : null,
  "version" : null,
  "count" : 0,
  "data" : null
}

成功时 data 为 null，不返回订单对象。需要确认最终状态请调用查询订单。

取消规则

• 状态 INIT (0) 和 PAID (1) 的订单可以取消。PAID 指已收到一笔短款支付、正在等补款。
• 状态大于 PAID 的订单（CONFIRMING (2)、SUCCESS (3)、FINISH (4)）不能取消。
• 已经是 CANCELED (-3) 的订单不能重复取消。
• 订单必须属于当前 api key 所属的商户。
• 取消操作不可逆。

WARNING

订单取消后，其占用的收款地址会释放回地址池。如果客户在取消后仍向该地址转账， 这笔钱可能被归属到复用了该地址的其他订单，或者无法被识别。 请确保你的前端在取消后立即停止展示该支付地址。

常见错误

业务错误统一通过 code = -2 加 msg 返回，具体原因看 msg（完整返回码见创建订单）：

msg	含义
pay order not exist or canceled	订单不存在，或已经是取消状态
pay order already full paid, can not cancel	订单状态已超过 PAID，不允许取消
can not find api key	订单关联的 api key 不存在或不是 api key 类型
invalid request sign	请求头签名不匹配
request timestamp out of allowed window, ...	时间戳超出 ±5 分钟窗口
duplicate request uuid, replay rejected	hashnut-request-uuid 复用了
pay order not created by current merchant	这笔订单不属于当前签名所用 api key 的商户