MERCHANT API DOCUMENTATION

商户 API 对接文档

接口版本 v1 · UTF-8 · application/json

HTTPS

1. 接入说明

请先从后台商户列表的“对接资料”获取商户号、商户密钥和接口地址。商户登录账号不参与 API 认证。

项目	说明
生产协议	HTTPS
字符编码	UTF-8
数据格式	JSON
金额	大于 0，建议使用字符串保留两位小数

2. 认证与签名

每个请求必须携带以下请求头。时间戳使用 Unix 秒，允许服务器时间前后误差 300 秒；Nonce 不少于 12 个字符，且 10 分钟内不可重复。

请求头	说明
`X-Merchant-No`	后台分配的商户号
`X-Timestamp`	Unix 秒级时间戳
`X-Nonce`	每次请求唯一随机字符串
`X-Signature`	小写十六进制 HMAC-SHA256 签名

待签名原文

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + 原始请求体

使用商户密钥执行 HMAC-SHA256。GET 请求的原始请求体为空；POST 请求必须使用发送前未经改写的原始 JSON 字节。

3. 创建订单

POST/openapi/v1/orders

字段	类型	必填	说明
`merchant_order_no`	string	是	商户订单号，同一商户内不可重复，最长 64 位
`amount`	number/string	是	订单金额，必须大于 0
`product_code`	string	是	后台分配并启用的产品编码

请求示例

{
  "merchant_order_no": "T202610070001",
  "amount": "100.00",
  "product_code": "1010"
}

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "system_no": "SF202610070930001234",
    "merchant_order_no": "T202610070001",
    "status": "pending",
    "payment_url": "https://upstream.example/pay/abc123"
  }
}

商户应将客户跳转到 payment_url 完成支付。系统会先匹配金额，再按权重从高到低请求上游；当前通道拉空或超时时自动尝试下一通道。

全部通道拉空响应（HTTP 502）

{
  "code": 50201,
  "message": "empty order",
  "data": {
    "system_no": "SF202610070930001234",
    "merchant_order_no": "T202610070001",
    "status": "failed",
    "reason": "empty_order"
  }
}

4. 查询订单

GET/openapi/v1/orders/{system_no}

system_no 为创建订单成功后返回的平台系统单号。GET 请求参与签名的请求体为空。

成功响应

{
  "code": 0,
  "message": "success",
  "data": {
    "system_no": "SF202610070930001234",
    "merchant_order_no": "T202610070001",
    "amount": "100.00",
    "status": "paid",
    "created_at": "2026-10-07T09:30:00+00:00"
  }
}

当前版本暂未启用主动订单回调，商户应通过查单接口确认最终状态；后台的回调地址是预留配置。

5. 状态与错误

订单状态	说明
`pending`	等待支付
`paid`	支付成功

HTTP 状态码	说明
400	请求参数错误
401	商户号、时间戳或签名无效
403	来源 IP 不在白名单
404	订单或产品不存在
409	Nonce 重复、商户订单号重复或暂无可用通道

6. 安全说明

商户密钥只发送给对应商户的技术人员，不要发送到公共群。
建议配置固定服务器 IP 白名单，并校准服务器时间。
不要记录完整商户密钥或完整签名原文到公开日志。

重置商户密钥后旧密钥立即失效，商户必须同步更新签名密钥，否则后续请求将返回签名错误。

费率查询接口

GET/openapi/v1/rates

返回当前商户已开通、产品与通道均启用的产品费率。该接口使用与订单接口相同的签名请求头，GET 请求体为空。

成功响应

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "code": "1010",
      "name": "支付宝原生",
      "fee_rate": "18.000"
    }
  ]
}

fee_rate 的单位为百分比；例如 18.000 表示 18%。接口不会返回内部通道或供应商信息。