Open API

业务系统通过 HTTP JSON 接口与支付平台交互。所有接口前缀为 /api/v1。

通用约定

项目	说明
协议	HTTPS（生产）/ HTTP（开发）
编码	UTF-8
金额	整数，单位分
签名	HMAC-SHA256，密钥为 `app_secret`
时间戳	Unix 秒，`timestamp` 与服务器差值 ≤ 300 秒

签名算法

1. 排除 sign 字段及空值
2. 按 key 字母序排序
3. 拼接 key=value&key=value...
4. HMAC-SHA256(app_secret, 拼接串) → 小写十六进制

响应格式

{ "code": 0, "data": { ... } }

code	含义
0	成功
非 0	失败，message 字段含错误描述

创建订单

POST /api/v1/orders

请求体

字段	类型	必填	说明
app_id	string	是	接入应用 ID
out_trade_no	string	是	业务侧订单号，同一 app 下唯一
amount	integer	是	金额（分）
subject	string	是	商品标题
notify_url	string	是	异步通知地址
return_url	string	是	同步回跳地址
timestamp	integer	是	Unix 时间戳（秒）
nonce	string	是	随机字符串
sign	string	是	签名

请求示例

{
  "app_id": "app_abc123",
  "out_trade_no": "ORDER20250530001",
  "amount": 100,
  "subject": "月度会员",
  "notify_url": "https://biz.example.com/api/pay/notify",
  "return_url": "https://biz.example.com/pay/success",
  "timestamp": 1717056000,
  "nonce": "a1b2c3d4e5",
  "sign": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

响应示例

{
  "code": 0,
  "data": {
    "order_no": "P202505300001",
    "pay_url": "http://127.0.0.1:8010/pay/xYzToken123",
    "expire_at": "2025-05-30T13:00:00Z"
  }
}

将用户重定向至 pay_url 进入收银台。

查询订单

GET /api/v1/orders/{out_trade_no}?app_id=xxx&timestamp=...&nonce=...&sign=...

查询参数同样需签名（GET 参数参与签名拼接）。

响应示例

{
  "code": 0,
  "data": {
    "order_no": "P202505300001",
    "out_trade_no": "ORDER20250530001",
    "status": "paid",
    "amount": 100,
    "paid_at": "2025-05-30T12:05:00Z",
    "channel_trade_no": "wx_demo_123456"
  }
}

订单状态

status	说明
pending	待支付
paid	已支付
closed	已关闭
expired	已过期

关闭订单

POST /api/v1/orders/{out_trade_no}/close?app_id=xxx&...

仅 pending 状态订单可关闭。已支付订单不可关闭。

响应示例

{ "code": 0, "message": "ok" }

异步通知

支付成功后，平台向创建订单时指定的 notify_url 发送 POST 请求。

业务系统应：

验证签名
校验金额与订单号
幂等更新本地订单
响应纯文本 success（非 JSON）

若未收到 success，平台会按策略重试通知。

错误码示例

场景	典型响应
app_id 无效	`{ "code": 400, "message": "app_id 无效" }`
签名错误	`{ "code": 400, "message": "签名验证失败" }`
订单不存在	`{ "code": 404, "message": "订单不存在" }`
重复 out_trade_no	`{ "code": 400, "message": "订单号已存在" }`