第三方网站接入文档

匠作空间支付系统 · 开放 API · 签名保障安全

密钥获取：登录管理后台 → 用户中心，复制 App ID、API Secret、Webhook Secret。请勿泄露或提交到公开代码库。

一、接入流程（4 步）

  1. 在后台「用户中心」复制 App ID 和 API Secret
  2. 你的服务器调用 创建订单 接口，获得 pay_url 和 pay_amount
  3. 引导用户打开 pay_url 扫码，按页面显示的 精确金额 支付
  4. 支付成功后，系统 POST 到你填写的 notify_url（带签名）

二、签名算法

所有开放接口必须携带以下公共参数：

参数说明
app_id后台 App ID
timestamp毫秒时间戳，与服务器时差不超过 5 分钟
sign签名（见下方算法）

签名步骤：

  1. 取所有业务参数 + app_id + timestamp（不含 sign）
  2. 按参数名 字典序 排列，拼接为 key1=value1&key2=value2
  3. sign = HMAC-SHA256(api_secret, 上述字符串)，输出小写 hex
// Node.js 示例
const crypto = require('crypto');
function sign(params, apiSecret) {
  const keys = Object.keys(params).filter(k => k !== 'sign' && params[k] != null && params[k] !== '').sort();
  const str = keys.map(k => `${k}=${params[k]}`).join('&');
  return crypto.createHmac('sha256', apiSecret).update(str).digest('hex');
}

三、创建订单

POST /api/open/order/create

参数必填说明
amount是商品金额（元）
channel_type否wechat / alipay / qq，默认自动选可用通道
out_trade_no否你的网站订单号（唯一）
subject否商品名称
notify_url否支付成功异步通知地址
return_url否支付完成跳转地址（预留）

返回示例：

{
  "success": true,
  "code": "OK",
  "data": {
    "order_no": "A1B2C3D4E5F6G7H8",
    "out_trade_no": "YOUR20260301001",
    "amount": 10,
    "pay_amount": 10,
    "pay_url": "https://你的域名/pay?order=A1B2C3D4E5F6G7H8",
    "qr_url": "https://你的域名/api/live/wechat",
    "expired_at": "2026-03-01 12:15:00"
  }
}

将用户跳转到 pay_url，或自行展示 qr_url 二维码。

四、查询订单

GET /api/open/order/query

参数说明
order_no平台订单号（与 out_trade_no 二选一）
out_trade_no你的网站订单号

另需公共参数 app_id、timestamp、sign（Query 传参）。

status：pending / paid / expired

五、支付成功通知（notify_url）

订单核销成功后，系统向你的 notify_url 发送 POST JSON：

{
  "order_no": "A1B2C3D4E5F6G7H8",
  "out_trade_no": "YOUR20260301001",
  "amount": 10,
  "pay_amount": 10,
  "status": "paid",
  "paid_at": "2026-03-01 12:05:00",
  "timestamp": "1709289900123",
  "sign": "..."
}

请用相同算法校验 sign（使用 API Secret），防止伪造通知。

六、收款监听（自动到账）

需在收款手机/电脑安装监听 App，Webhook 地址：

POST /api/webhook/smsforwarder

请求体需含 timestamp、content、sign，签名规则：

sign = HMAC-SHA256(webhook_secret, timestamp + "\n" + webhook_secret)

Webhook Secret 在后台「用户中心」查看，至少 16 位，与 API Secret 不同。

七、安全建议

返回首页 · 管理后台