> 本文整理自平台文档 docs/wujies/5.x/plugins/pay.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-c7845d37304f-cover.svg)
应用编码 pay,本页对应应用版本 1.0.3(引擎要求 >=5.6.2 <6.0.0),商业授权(app.json 写 UNLICENSED,要先购买激活,见 [按应用授权](/docs/wujies/5.x/license/per-app)),仓库 [wujies-pay-plugin](https://gitee.com/wujies/wujies-pay-plugin)。
支付中心管三件事:支付应用(哪个业务从哪个应用收款)、支付渠道(支付宝 / 微信 / 余额)、支付订单与退款单。业务订单归业务应用自己(比如[商城](/docs/wujies/5.x/plugins/mall)),pay 不碰业务表;收款成功后 pay 把渠道打来的回调处理掉、把自己的支付订单改成已支付,再在进程内广播 PaySuccessEvent,由订阅它的应用推进自己的订单(商城就挂了监听)。
依赖登记在清单里:本应用声明 member,商城那边声明了本应用。装商城收款链路时 pay 与 member 都要在位,缺谁先报错谁那半。
装它
装之前确认下面四件事:
1. member 已安装启用。余额支付与余额退款走会员余额接口,没装 member 时这两处当场报「应用「会员管理」未安装或未启用,无法调用 …」,其余渠道照常。口径见 [会员中心](/docs/wujies/5.x/plugins/member)。 2. 这台部署有对外可达的域名。支付宝和微信的支付结果要 POST 回你的地址,localhost 只够本机联调。 3. 宿主配置里给微信留了五个键。它们注入时没有默认值,缺任何一个,支付应用在装载那一步就失败、日志报占位符解析失败。暂时不开微信也要在宿主侧配置文件(部署口径见 [后端部署](/docs/wujies/5.x/deploy/backend))把这五个键留成空值:装载只查占位符能不能解析,真正下单要到渠道里才报错。 4. 后台任务随装载自动生效:通知补发、关闭过期订单、渠道对账都是应用内的定时周期,不需要在调度中心登记,周期写死在代码里。
商业应用要先在应用市场完成购买与激活才装得上,流程见 [应用目录](/docs/wujies/5.x/platform/app-market/catalog)。装成功后侧栏多一个「支付管理」,下面四项:
| 菜单 | 路由 | 需要的权限码 |
|---|---|---|
| 支付应用 | app | pay:app:list |
| 支付渠道 | channel | pay:channel:list |
| 支付订单 | payOrder | pay:order:list |
| 退款订单 | refund | pay:refund:list |
每页另有 pay:app:query / add / edit / remove 式的按钮码,支付订单页多一枚 pay:order:submit(在后台发起一笔支付)。分发与角色规则见 [菜单与权限码分发](/docs/wujies/5.x/platform/app-market/menus)。
配它
种子脚本预建一个应用 mall_pc 和两条渠道(wx_lite、wallet),微信那条的渠道配置全是占位串,回调地址指向 http://localhost:8080,上线前都要在页面上改掉。种子文件自己的注释就写明 config 一律留占位、真实凭据不进这个文件。
支付应用页的两个回调地址。下单时 pay 把「支付回调基础地址」拼成渠道实际回调的入口:基础地址后面追加 /{渠道编码}/{渠道id},填 http://你的域名/app/pay/notify,微信收到的就是 /app/pay/notify/wx_lite/2。基础地址留空会拼出以 / 开头的相对地址,渠道直接拒收;末尾多写一个 / 会拼出双斜杠。退款回调基础地址整串照用、不追加后缀,改渠道 id 也不会反映到它上面。应用页的「可用支付渠道」是渠道 id 的逗号清单,下单选的渠道不在里面,直接被拒。
支付宝渠道(alipay_pc / alipay_wap / alipay_app / alipay_qr 四个编码)。五个键放渠道页的「渠道配置」JSON:serverUrl、appId、privateKey、publicKey、signType,下单签名与回调验签读的都是这份。私钥与公钥的值由有权限的人在那个页面录入,或由部署侧注入;任何真值都不进仓库、迁移脚本、文档和截图。这份 JSON 存在渠道表里,改完保存即生效。
微信渠道(wx_pub / wx_lite / wx_app / wx_native / wx_h5 五个编码)。与支付宝不同,签名与回调解密的材料放在部署侧配置文件或环境变量里的五个键:pay.wechat.appId、pay.wechat.merchantId、pay.wechat.merchantSerialNumber、pay.wechat.privateKey、pay.wechat.apiV3Key。商户私钥那一族的真值同样只说"配在哪个键、由哪一侧注入",仓库与文档里一律不出现。在渠道 JSON 里改这几个键不生效,那里只有 mchId 参与查单与关单;这五个键是应用装载时读的,换值要重启宿主,别指望改库生效。
余额渠道(wallet)。渠道配置空对象即可,前提只有 member 在装。付款从会员余额扣(余额流水类型 2 消费),退款退回余额(类型 3,备注带上原订单号),流水落在会员的表里,pay 只记自己的退款单。
回调地址要和对外真实路径对齐。代码只负责往基础地址后面追加 /{渠道编码}/{渠道id},它不知道你这台部署前面有没有网关前缀。种子值 http://localhost:8080/app/pay/notify 是本机联调用的完整形态;换域名或上了网关,先用一次请求确认回调端点的对外路径长什么样,再决定基础地址填到哪一截,多删少改都会让渠道打到不存在的地址。
费率与时限。渠道的默认费率在下单时抄进支付订单的渠道费率;订单有效期写死创建后 30 分钟,没有配置项,后台任务每分钟关闭到期订单。渠道编码枚举里还有一个 mock,没有注册对应策略,配出来用到就是「未找到支付策略: mock」。
订单与状态口径。支付订单号由雪花生成;商户订单号在支付订单表里查重,业务方重复拿同一个号来下单会被直接拒(「商户订单号已存在」)。支付订单四档状态:未支付、已支付、已退款、已关闭,到期未付的由后台任务批量关闭。退款单三档:等待、成功、失败,失败时渠道回的错误码与错误文本记在退款行上,退款订单页直接看得到。
用它
管理员在四页里建应用、绑渠道、核对支付订单与退款单;退款单从退款订单页创建,金额原路退回,余额渠道直接回会员余额。订单页的「发起支付」用来从后台试单(需要 pay:order:submit)。已支付的订单删不掉,处理中的退款单也删不掉,这是接口层的硬规则:钱已收就走退款流程,别指望删单。
会员不直接调 pay:余额扣款发生在业务应用结算那一步,业务方带会员身份下单。会员看到的余额与流水都在会员中心,见 [会员中心](/docs/wujies/5.x/plugins/member)。
渠道平台匿名回调:POST /pay/notify/{渠道编码}/{渠道id} 与 POST /pay/notify/refund/{渠道编码}/{渠道id} 免登录。处理抛异常时 pay 按渠道规范回失败应答(支付宝回失败文本、微信回失败 JSON),让渠道按自己的节奏重试;成功时支付宝要求应答体恰好是 success 文本,微信要求 code=SUCCESS 的 JSON。重复通知靠订单状态判重,不会二次广播。回调之后 pay 还会建通知任务,向订单携带的回调地址补发结果(最多 5 次,15 秒起指数退避,应答体 success 或 HTTP 200 算完成);进程内的业务推进走 PaySuccessEvent,通知任务是给需要进程外接收方留的那条线。
出问题查什么
| 现象 | 先看什么 |
|---|---|
| 下单报「该应用下支付渠道不存在或已停用」 | 应用页「可用支付渠道」里有没有那个渠道 id、渠道状态是否启用 |
| 「支付宝下单失败: …」 | 渠道配置 JSON 五个键齐不齐,serverUrl 与沙箱/生产环境是否匹配 |
| 「微信下单失败: …」 | 宿主 pay.wechat.* 五个键与商户后台材料是否对得上,改完是否重启过宿主 |
| 支付应用装载失败,日志报占位符解析失败 | pay.wechat.* 缺键;哪怕不开微信渠道,装载也要这五个键能解析 |
| 用户付了钱但业务订单没动 | 支付回调基础地址是否对外可达;看宿主日志「支付回调处理异常」;商城侧再确认进程内事件监听有没有执行 |
| 退款结果收不到回调 | 退款回调基础地址整串照用、不追加任何后缀;匿名端点 /pay/notify/refund/{渠道编码}/{渠道id} 是另一条路径,要让渠道打到它就得把基础地址本身填成那个完整形态 |
| 「未找到支付策略: mock」 | 渠道编码 mock 没有注册策略,不要配它 |
| 「商户订单号已存在」 | 业务方用同一个商户订单号重复下单;这个号在表内查重 |
| 删除订单被拒「已支付的订单不能删除」 | 删单只放行未支付订单;已收款的钱走退款订单页退 |
| 「余额支付失败,会员账户不存在」 | m |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-c7845d37304f-guide.svg)


评论区需要浏览器启用 JavaScript 才能加载。