API 接入文档

基础信息

金额单位均为分。商户接口使用 AppID 和 AppSecret 做 HMAC-SHA256 签名。

支付和退款回调地址统一使用商户后台配置的默认回调地址，下单请求无需传回调地址。

支付超时字段为 timeout，单位秒，非必填；不传默认 1800 秒。

首页 / 提供管理端登录和 API 文档入口；本文档无需登录。

签名

商户接口请求头：

sign_payload = X-App-Id + "\n" + X-Timestamp + "\n" + sorted_query + "\n" + raw_body
X-Sign = hex(HMAC-SHA256(sign_payload, AppSecret))

创建 Native 支付订单

POST /api/v1/pay/native/create

请求体

{
  "out_trade_no": "YOUR_ORDER_001",
  "title": "商品购买",
  "amount": 100,
  "timeout": 1800,
  "return_url": "https://your-site.com/return",
  "attach": "optional"
}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "code_url": "weixin://wxpay/bizpayurl?pr=xxxxx",
    "out_trade_no": "YOUR_ORDER_001",
    "order_no": "P20231201001",
    "amount": 100,
    "expire_seconds": 1800,
    "expired_at": "2026-07-09T13:30:00+08:00"
  }
}

创建 JSAPI 支付订单

POST /api/v1/pay/jsapi/create

JSAPI 复用平台收银台，不需要商户单独开发订单确认页。用户在微信内打开返回的 pay_url 后，页面会自动 OAuth 并拉起微信支付。

请求体

{
  "out_trade_no": "YOUR_ORDER_001",
  "title": "商品购买",
  "amount": 100,
  "timeout": 1800,
  "return_url": "https://your-site.com/return",
  "attach": "optional"
}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "pay_url": "https://pay.ycbas.com/pay/tok_xxx",
    "out_trade_no": "YOUR_ORDER_001",
    "order_no": "P20231201001",
    "pay_type": "jsapi",
    "expire_seconds": 1800,
    "expired_at": "2026-07-09T13:30:00+08:00"
  }
}

查询订单

GET /api/v1/pay/query/:out_trade_no

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "out_trade_no": "YOUR_ORDER_001",
    "order_no": "P20231201001",
    "title": "商品购买",
    "amount": 100,
    "status": "paid",
    "pay_type": "native",
    "wechat_tx_id": "4200001234...",
    "paid_at": "2023-12-01T12:00:00+08:00",
    "created_at": "2023-12-01T12:00:00+08:00",
    "expire_seconds": 1800,
    "expired_at": "2023-12-01T12:30:00+08:00"
  }
}

发起退款

POST /api/v1/pay/refund

当前实现按商户订单号发起全额退款，只有已支付订单可退款。

请求体

{
  "out_trade_no": "YOUR_ORDER_001",
  "reason": "用户申请退款"
}

响应

{
  "code": 0,
  "message": "success",
  "data": {
    "out_trade_no": "YOUR_ORDER_001",
    "order_no": "P20231201001",
    "refund_no": "RP20231201001",
    "refund_status": "PROCESSING",
    "refund_amount": 100
  }
}

支付结果回调

支付成功后，平台会向商户后台配置的默认回调地址发送 POST 请求。

{
  "app_id": "APPxx",
  "out_trade_no": "YOUR_ORDER_001",
  "order_no": "P20231201001",
  "amount": 100,
  "status": "paid",
  "wechat_tx_id": "4200001234...",
  "paid_at": "2023-12-01T12:00:00+08:00",
  "attach": "",
  "sign": ""
}

当前回调 payload 中预留了 sign 字段，但服务端尚未填充签名。

状态枚举