统一下单 API 文档 · 聚合支付演示

概述

商户系统通过 HTTPS 调用本平台 统一下单 接口创建支付订单，再引导用户完成支付（演示环境为 Mock）。支付成功后平台按费率结算并入账，同时可查询订单状态。

基础地址（本地演示）：http://localhost:3000

接入准备

运营在后台完成 商户开户 并 审核通过
商户登录商户后台 → 接入信息，获取 App Key、App Secret
将密钥配置在商户服务端，用于 API 请求鉴权

鉴权方式

每个请求在 HTTP 头中携带商户密钥（演示环境，生产环境建议改为签名方案）：

请求头	说明
`X-Api-Key`	商户 App Key，形如 `pk_xxx`
`X-Api-Secret`	商户 App Secret，形如 `sk_xxx`
`Content-Type`	`application/json`

基础约定

项目	说明
协议	HTTPS（本地演示可用 HTTP）
编码	UTF-8
金额单位	元，最多两位小数
支付渠道 channel	`wechat` 微信 · `alipay` 支付宝 · `unionpay` 银联（Mock）；须为商户已开通渠道。不传则顾客在收银台自选
订单状态 status	`pending` 待支付 · `paid` 已支付
响应格式	JSON，含 `ok`、`code`、`message`、`data`

统一下单

POST /api/v1/unified/order

请求参数（Body JSON）

参数	类型	必填	说明
amount	number	是	订单金额（元），如 99.00
channel	string	否	已开通渠道之一；省略时 `pay_url` 收银台由用户选择
subject	string	否	商品描述，默认「演示商品」
out_trade_no	string	否	商户订单号，不传则由平台生成
notify_url	string	否	支付成功后的异步通知地址（http/https）。运营在后台对该订单执行「手动回调」时，平台将向该 URL POST JSON（超时 8 秒）。收银台支付成功不发此通知，请用「查询订单」确认
client_ip	string	否	用户 IP，便于对账

响应 data 字段

字段	说明
order_id	平台订单 ID
out_trade_no	商户订单号
amount / amount_fen	金额（元 / 分）
channel / subject / status	渠道、描述、状态
pay_url	收银台地址，如 `/pay.html?id={order_id}`
created_at	创建时间（ISO8601）
paid_at	支付成功时间；仅 `status=paid` 时有值
fee_amount / net_amount	手续费、入账金额；仅已支付时有值

响应示例

{
  "ok": true,
  "code": "SUCCESS",
  "message": "下单成功",
  "data": {
    "order_id": "uuid",
    "out_trade_no": "P1779438078562110",
    "amount": 99,
    "amount_fen": 9900,
    "channel": "wechat",
    "subject": "演示商品",
    "status": "pending",
    "pay_url": "/pay.html?id=uuid",
    "notify_url": "https://merchant.example.com/pay/notify",
    "created_at": "2026-05-22T08:21:18.562Z",
    "paid_at": null
  }
}

查询订单

GET /api/v1/unified/order/{out_trade_no}

根据 商户订单号 查询单笔订单；已支付订单含 fee_amount、net_amount、paid_at（支付成功时间）。

已支付订单 data 补充字段

字段	说明
status	`paid`
paid_at	支付成功时间（ISO8601）
fee_rate / fee_amount	费率、手续费（元）
net_amount	商户入账金额（元）

订单列表

GET /api/v1/unified/orders?status=pending&limit=50

Query	说明
status	可选，`pending` / `paid`
limit	可选，默认 50，最大建议 100

返回数组元素字段与「查询订单」一致，含 created_at、paid_at 等。

支付结果与异步通知

演示环境为 Mock 渠道。支付成功方式：① 顾客打开 pay_url 收银台完成支付；② 运营在后台订单列表点击 手动回调。两种方式均会将 status 置为 paid 并写入 paid_at、账变流水。

异步通知 notify_url

统一下单时传入 notify_url 后，当运营对该笔待支付订单执行 手动回调 且入账成功时，平台向该地址发起：

POST {notify_url} · Content-Type: application/json · 超时 8 秒

商户接口建议返回 HTTP 2xx 表示接收成功；非 2xx 视为通知失败（可在运营操作日志中查看结果）。

说明：收银台支付成功不会触发 notify_url，请对收银台场景使用「查询订单」轮询或改由运营手动回调。

通知 Body 示例

{
  "event": "payment.success",
  "order_id": "uuid",
  "out_trade_no": "M20260522001",
  "merchant_id": "uuid",
  "amount": 99,
  "amount_fen": 9900,
  "channel": "wechat",
  "status": "paid",
  "fee_amount": 0.59,
  "net_amount": 98.41,
  "paid_at": "2026-05-24T12:00:00.000Z",
  "subject": "演示商品"
}

通知字段

字段	说明
event	固定 `payment.success`
order_id	平台订单 ID
out_trade_no	商户订单号
merchant_id	商户 ID
amount / amount_fen	订单金额（元 / 分）
channel	支付渠道
status	`paid`
fee_amount / net_amount	手续费、入账金额
paid_at	支付成功时间
subject	商品描述

错误码

code	HTTP	说明
SUCCESS	200	成功
AUTH_REQUIRED	401	未提供 API 密钥
AUTH_INVALID	401	密钥错误
MERCHANT_INACTIVE	403	商户未开通
INVALID_PARAM	400	参数无效
DUPLICATE_OUT_TRADE_NO	400	商户订单号重复
ORDER_NOT_FOUND	404	订单不存在

调用示例（cURL）

将 YOUR_KEY、YOUR_SECRET 替换为商户后台中的密钥。

统一下单

curl -X POST "http://localhost:3000/api/v1/unified/order" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "X-Api-Secret: YOUR_SECRET" \
  -d "{\"amount\":99,\"channel\":\"wechat\",\"subject\":\"演示商品\",\"out_trade_no\":\"M20260522001\",\"notify_url\":\"https://merchant.example.com/pay/notify\"}"

查询订单

curl "http://localhost:3000/api/v1/unified/order/M20260522001" \
  -H "X-Api-Key: YOUR_KEY" \
  -H "X-Api-Secret: YOUR_SECRET"