支付能力接入

概述

1. 在控制台注册账号 → 创建应用 → 在应用详情页生成一把 sk-live-… 形式的 API Key。
2. 订阅「支付能力」, 填写支付结果回调地址 callbackUrl。
3. 业务后端调用「创建订单」接口下单, 拿到 payUrl 展示给用户付款。
4. 用户付款成功后, 开放平台会以 POST 方式回调 callbackUrl, 业务后端处理订单 (强烈建议主动调「查询」接口二次确认订单状态)。

鉴权

所有业务接口都在 Authorization Header 携带 API Key:

Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Key 在控制台「应用详情 → API Keys」中创建, 一个应用可以挂多把 (例如 production / test / 单独吊销)。 生成的 Key 仅本次明文显示, 请立即妥善保存。

创建支付订单

请求 Body

{
  "businessId": "order_20250612001",    // 业务方自定义订单号, 必须全局唯一
  "amount": "1.00",                     // 字符串, 单位元, 精度 2 位
  "subject": "VIP 月卡",                 // 商品标题
  "channel": "wxpay",                   // 支付渠道: wxpay | alipay
  "notifyUrl": "",                      // 可选, 覆盖订阅时填的回调地址
  "returnUrl": "https://your-app.com/order/result",  // 可选, 付款后浏览器跳转的页面
  "extra": {}                           // 可选, 业务透传字段, 回调时原样返回
}

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "payNo": "pay_20250612abcdef",      // 平台内部订单号
    "payUrl": "https://pay.yunshee.com/pay/..."   // 给用户跳转付款
  }
}

curl 示例

curl -X POST https://pay.yunshee.com/api/v1/pay/create \\
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \\
  -H "Content-Type: application/json" \\
  -d '{"businessId":"order_20250612001", "amount":"1.00", "subject":"VIP 月卡", "channel":"wxpay"}'

查询订单状态

curl 示例

curl -X GET "https://pay.yunshee.com/api/v1/pay/query?payNo=pay_20250612abcdef" \\
  -H "Authorization: Bearer sk-live-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

响应

{
  "code": 0,
  "msg": "ok",
  "data": {
    "payNo": "pay_20250612abcdef",
    "businessId": "order_20250612001",
    "amount": "1.00",
    "channel": "wxpay",
    "state": "paid",                    // waiting | paid | refunded | closed
    "paidAt": "2026-06-12 21:30:55"
  }
}

支付结果回调

用户付款成功后, 开放平台以 POST 调用你在订阅时填写的 callbackUrl。

回调 Body

{
  "appId": "app_xxxxxxxx",
  "businessId": "order_20250612001",
  "payNo": "pay_20250612abcdef",
  "amount": "1.00",
  "channel": "wxpay",
  "paidAt": "2026-06-12 21:30:55",
  "subject": "VIP 月卡",
  "extra": "",
  "timestamp": 1781267455
}

推荐处理方式

收到回调后, 推荐用自己持有的 API Key 主动调用 GET /pay/query?payNo=… 二次确认订单状态再处理业务。这是最稳妥的防伪方式 (Stripe、阿里云等均推荐), 不依赖第三方签名。

错误码