聚合支付中心接入文档

所有业务应用通过本中台统一收款：支付密钥集中托管，业务侧只做「签名下单 + 接收回调」两件事。

一、方案概述

业务系统不再保存任何微信/支付宝商户密钥。下单、签名、验签、回调分发、对账全部由中台完成：

• 业务后端：调用统一下单接口（用 app_secret 签名），拿到 order_no 与 status_token。
• 业务前端：把用户引导到「聚合收银」小程序，携带 order_no + token。
• 聚合收银小程序：用自身 openid 唤起微信支付，完成后回跳业务小程序。
• 中台：接收微信/支付宝异步通知，验签入账后，再回调业务侧的 notify_url。

二、5 分钟接入

POST /api/v1/pay/unifiedorder
Content-Type: application/x-www-form-urlencoded

app_id=a1b2c3d4e5f6g7h8
out_trade_no=ORDER20261020001
amount=0.01
subject=测试商品
channel=wechat            # wechat | alipay
trade_type=jsapi          # jsapi(小程序) | app | h5 | native
attach=任意透传参数
timestamp=1770000000
nonce_str=7f3a9c1b2d4e
sign=9A8B7C6D5E4F...      # 见「签名规则」

{
  "code": 0,
  "msg": "ok",
  "data": {
    "order_no": "PC20261020103000123456",
    "status_token": "9f8a7b6c5d4e3f21",
    "amount": "0.01",
    "status": 0,
    "status_text": "待支付",
    "expire_time": "2026-10-20 11:00:00",
    "need_client_prepay": true
  }
}

wx.navigateToMiniProgram({
  appId: '聚合收银小程序AppID',
  path: 'pages/index/index?order_no=' + order_no + '&token=' + status_token,
  // 也可以放在 extraData 里
  extraData: { order_no: order_no, token: status_token }
})

三、环境与域名

通道回调地址一览（由中台统一提供，业务方无需配置）

四、签名规则

业务方调用需要签名的接口（下单、查单、关单、退款）时必须携带签名，算法与微信支付 V2 一致：

1. 参数中必须包含 app_id、timestamp（秒级时间戳）、nonce_str（随机串）；
2. 剔除 sign 以及值为空字符串或 null 的参数；
3. 按参数名 ASCII 升序排序，拼成 k1=v1&k2=v2；
4. 末尾追加 &key=你的app_secret；
5. 做 MD5，转大写，即 sign。

PHP

function payCenterSign(array $params, string $secret): string {
    unset($params['sign']);
    $params = array_filter($params, fn($v) => $v !== '' && $v !== null);
    ksort($params);
    $pairs = [];
    foreach ($params as $k => $v) {
        $pairs[] = $k . '=' . $v;
    }
    return strtoupper(md5(implode('&', $pairs) . '&key=' . $secret));
}

Node.js

const crypto = require('crypto');

function sign(params, secret) {
  const { sign, ...rest } = params;
  const str = Object.keys(rest)
    .filter(k => rest[k] !== '' && rest[k] !== null && rest[k] !== undefined)
    .sort()
    .map(k => `${k}=${rest[k]}`)
    .join('&');
  return crypto.createHash('md5').update(str + '&key=' + secret, 'utf8')
    .digest('hex').toUpperCase();
}

Python

import hashlib

def sign(params: dict, secret: str) -> str:
    params.pop('sign', None)
    items = [(k, v) for k, v in params.items() if v not in ('', None)]
    raw = '&'.join(f'{k}={v}' for k, v in sorted(items))
    return hashlib.md5((raw + '&key=' + secret).encode('utf-8')).hexdigest().upper()

五、统一下单

POST/api/v1/pay/unifiedorder

幂等：相同 app_id + out_trade_no 重复请求返回同一笔订单；金额不一致会返回 2008。

返回：

curl 示例

curl -X POST 'http://localhost:8100/api/v1/pay/unifiedorder' \
  -d 'app_id=a1b2c3d4e5f6g7h8' \
  -d 'out_trade_no=TEST20261020001' \
  -d 'amount=0.01' \
  -d 'subject=联调测试' \
  -d 'channel=wechat' \
  -d 'trade_type=jsapi' \
  -d 'timestamp=1770000000' \
  -d 'nonce_str=abc123456789' \
  -d 'sign=计算出来的大写MD5'

六、支付唤起（收银小程序内部接口）

以下接口由聚合收银小程序调用，业务方无需实现，仅供理解链路与排查问题。

POST/api/v1/wx/login

用 wx.login 的 code 换取 openid。参数：code。返回 openid、unionid。

POST/api/v1/pay/clientprepay

返回 pay_params，微信小程序可直接传给 uni.requestPayment：

{
  "appId": "wx555d0fc8251f5c36",
  "timeStamp": "1770000000",
  "nonceStr": "8f2c...",
  "package": "prepay_id=wx2010...",
  "signType": "RSA",
  "paySign": "MEUCIQ..."
}

七、查询支付状态（前端轮询）

GET/api/v1/pay/status?order_no=xxx&token=xxx

无需签名，只需订单号与令牌。返回 status、pay_time、transaction_id 等。业务前端若想自己轮询（例如 H5 收银页），可用它。

八、业务方查单（服务端，签名）

POST/api/v1/pay/query

参数：app_id、order_no 或 out_trade_no、sync（1 = 同时向渠道同步状态）。

用途：回调丢失时补偿、对账核验、发货前二次确认。

九、关闭订单

POST/api/v1/pay/close

参数：app_id、order_no。仅待支付订单可关闭，同时会尽力关闭渠道侧订单。

十、退款

POST/api/v1/pay/refund

{
  "code": 0,
  "data": {
    "refund_no": "RF202610201100001",
    "channel_refund_id": "50300...",
    "refund_amount": "0.01",
    "status": 1
  }
}

支持部分退款多次申请；全部退完后订单状态变为「已退款」。

十一、应用列表（公开）

GET/api/v1/app/list?keyword=

返回所有已激活应用（不含任何密钥），用于小程序首页与门户展示。

十二、异步通知与验签

支付成功后中台会向应用的 notify_url 发送 POST（form 表单）：

处理要求（重要）

1. 必须验签，并校验 app_id；
2. 用 out_trade_no 做幂等：已处理过直接返回 success；
3. 校验金额与本地订单一致，不一致必须告警并拒绝；
4. 输出纯文本 success 才算成功，否则中台会重试（最多 3 次）；
5. 接口需在 5 秒内响应，重逻辑请异步处理。

PHP 示例

<?php
// notify_url 指向本文件
$secret = '你的app_secret';
$post   = $_POST;

// 1. 验签
$sign = $post['sign'] ?? '';
unset($post['sign']);
$post = array_filter($post, fn($v) => $v !== '' && $v !== null);
ksort($post);
$raw = implode('&', array_map(fn($k) => "$k={$post[$k]}", array_keys($post)));
if (!hash_equals(strtoupper(md5($raw . '&key=' . $secret)), strtoupper($sign))) {
    http_response_code(400);
    exit('sign error');
}

// 2. 幂等 + 金额校验（示例）
$outTradeNo = $_POST['out_trade_no'];
$amount     = $_POST['amount'];
// $order = DB::row('SELECT * FROM orders WHERE order_no = ?', [$outTradeNo]);
// if (!$order) { log_error(); exit('order not found'); }
// if ($order['status'] === 'paid') { exit('success'); }
// if (bccomp($order['amount'], $amount, 2) !== 0) { log_error(); exit('amount mismatch'); }
// DB::update('UPDATE orders SET status="paid", transaction_id=? WHERE order_no=?', [$_POST['transaction_id'], $outTradeNo]);

// 3. 必须输出 success
echo 'success';

十三、同步回调处理

同步回调是用户浏览器的跳转，用来给用户看结果，不能作为发货依据：

中台的处理逻辑：

1. 读取 out_trade_no，查本地订单；
2. 若仍为「待支付」，主动向渠道查一次单（回调可能比跳转晚到），已支付则补入账并分发业务通知；
3. 渲染响应式结果页：显示金额、订单状态、订单号，已支付且有业务 return_url 时提供「返回业务应用」按钮；
4. 支付宝同步参数中的 trade_no / total_amount 会做交叉校验并记录日志。

十四、错误码

十四、联调清单

十六、常见问题

1. 下单报 1004 签名失败？

九成是排序或空值处理不对：必须剔除空值后再按 key 升序；拼接末尾是 &key=secret；结果转大写。

2. 支付完成但业务没收到回调？

• 确认 notify_url 是公网可访问的 HTTPS 地址；
• 确认回调返回了 success；
• 后台「回调日志」可看到中台向业务方发起的请求与响应，含 HTTP 状态码与重试次数；
• 可用「业务方查单」接口 + sync=1 主动补偿。

3. 能否不跳小程序、直接在业务小程序里支付？

不行。微信 openid 按小程序 AppID 隔离，业务小程序的 openid 无法在聚合小程序中使用；同理聚合小程序的 openid 也不能用于业务小程序的 JSAPI 下单。统一收银必须走聚合小程序。

4. 支付宝能在小程序里用吗？

微信小程序内只能唤起微信支付。支付宝适用于 App（trade_type=app）与 H5（trade_type=h5）。

5. 生产环境注意事项

• 域名必须是 HTTPS，并加入小程序 request 合法域名；
• 中台 app.debug 必须为 false；
• 证书目录 cert/、runtime/ 禁止 Web 访问；
• 业务服务器开启 NTP 时间同步。