入门

响应与错误码

通用响应结构、错误码，以及幂等、金额与状态的处理建议。

通用响应结构

所有商户 API 的业务响应统一格式：

JSON

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

规则：

code = 0 表示成功
code != 0 表示失败
msg 为原因说明。失败信息通常以 | 加一个固定的键结尾（例如 Order not found|orderNotFound）；请按错误码或该键判断，不要按文本判断
data 成功时为业务对象，失败时不返回
所有带签名的响应（包括错误）HTTP 状态码均为 200。只有鉴权错误使用各自的 HTTP 状态码（401 / 403）

常见错误码：

code	含义
`400`	请求格式错误
`401`	未授权
`403`	无权访问
`422`	业务参数校验失败，包括 `merchant_order_no` / `merchant_refund_no` 重复
`500`	系统内部错误
`1001`	商户账户已停用
`2002`	订单不存在
`2006`	代收金额不满足通道限制
`3003`	未开通该支付方式或该支付方式目前不可用
`5001`	代付单号重复
`5002`	代付订单不存在
`5004`	代付余额不足
`5007`	代付方式不可用
`5008`	代付金额不满足通道限制

按 merchant_order_no、merchant_refund_no、merchant_payout_no 做幂等
通知处理同样需要幂等
若多次收到同一通知，确认订单已处理后返回 success
重复的 merchant_order_no 或 merchant_refund_no 会以 code=422 拒绝；HansaPay 不会返回原响应。若创建请求超时，请先按你的单号查询，再使用新单号重试
HansaPay 已记录后失败的请求（例如卡被拒）同样占用其单号
merchant_order_no 与 merchant_refund_no 共用同一命名空间：不要把退款单号用作订单号