支付中台 API 文档

本文档描述了自建支付中台系统的 API 接口，用于商户系统接入及收银台前端交互。

接口总览

接口名称	方法	路径	描述
创建订单	POST	/api/precreate	商户后台调用，生成收银台链接
获取订单信息	GET	/api/cashier_info	收银台前端调用，展示订单详情
获取支付参数	POST	/api/get_pay_params	收银台前端调用，请求上游支付链接
查询订单状态	GET	/api/check_order	收银台/商户调用，查询支付状态

1. 创建订单 (Pre-create)

场景: 商户系统后台生成订单后，调用此接口获取“收银台链接”，然后引导用户跳转到该链接。

• URL: /api/precreate
• Method: POST
• Content-Type: application/json

请求参数

字段名	必填	类型	说明	示例
name	是	String	商品名称	"VIP会员充值"
price	是	String/Number	订单金额 (元)	"0.01"

响应参数

字段名	类型	说明
success	Boolean	是否成功
out_trade_no	String	中台生成的唯一订单号
cashier_url	String	收银台跳转地址
msg	String	错误信息 (失败时)

示例

// Request
{
    "name": "测试商品",
    "price": "1.00"
}

// Response
{
    "success": true,
    "out_trade_no": "1738155990123",
    "cashier_url": "http://localhost:3000/cashier.html?orderId=1738155990123"
}

2. 获取订单信息 (Cashier Info)

场景: 用户访问收银台页面 (cashier.html) 时，前端JS会自动调用此接口加载订单详情。

• URL: /api/cashier_info
• Method: GET

请求参数

字段名	必填	类型	说明
orderId	是	String	订单号 (URL参数中获取)

响应参数

字段名	类型	说明
success	Boolean	是否成功
data	Object	订单详情数据
name	String	商品名称
price	String	金额
expire_time	Number	订单过期时间戳 (毫秒)
logo_url	String	收银台Logo URL

3. 获取支付参数 (Get Pay Params)

场景: 用户在收银台选择支付方式（如支付宝、微信）并点击支付时调用。中台会根据设备类型请求上游接口，返回支付链接。

• URL: /api/get_pay_params
• Method: POST
• Content-Type: application/json

请求参数

字段名	必填	类型	说明	示例
orderId	是	String	订单号	"1738155990123"
type	是	String	支付方式	"alipay" 或 "wxpay"
device	否	String	设备类型	"pc" 或 "mobile" (默认 pc)

响应参数

字段名	类型	说明
success	Boolean	是否成功
data	Object	支付跳转数据
payurl	String	跳转链接 (H5/Web跳转)
qrcode	String	二维码内容 (用于生成二维码)
urlscheme	String	唤起APP的协议链接 (u.alipay.com / weixin://)

注意: 前端应优先使用 urlscheme (移动端APP唤起)，其次 qrcode (展示二维码)，最后 payurl (跳转)。

4. 查询订单状态 (Check Order)

场景: 收银台前端轮询，或商户后台查询订单支付状态。

• URL: /api/check_order
• Method: GET

请求参数

字段名	必填	类型	说明
out_trade_no	是	String	订单号

响应参数

字段名	类型	说明
success	Boolean	请求是否成功
status	Number	支付状态: 1 已支付, 0 未支付
msg	String	状态描述

示例

// Response (Paid)
{
    "success": true,
    "status": 1,
    "msg": "Paid"
}