Wujies 无界平台
应用

支付管理(pay)

支付宝、微信、余额三类渠道的密钥各配在哪、回调地址怎么拼,以及收不到款时查哪。

应用编码 pay,本页对应应用版本 1.0.3(引擎要求 >=5.6.2 <6.0.0),商业授权(app.json 写 UNLICENSED,要先购买激活,见 按应用授权),仓库 wujies-pay-plugin。

支付中心管三件事:支付应用(哪个业务从哪个应用收款)、支付渠道(支付宝 / 微信 / 余额)、支付订单与退款单。业务订单归业务应用自己(比如商城),pay 不碰业务表;收款成功后 pay 把渠道打来的回调处理掉、把自己的支付订单改成已支付,再在进程内广播 PaySuccessEvent,由订阅它的应用推进自己的订单(商城就挂了监听)。

依赖登记在清单里:本应用声明 member,商城那边声明了本应用。装商城收款链路时 pay 与 member 都要在位,缺谁先报错谁那半。

装它

装之前确认下面四件事:

  1. member 已安装启用。余额支付与余额退款走会员余额接口,没装 member 时这两处当场报「应用「会员管理」未安装或未启用,无法调用 …」,其余渠道照常。口径见 会员中心。
  2. 这台部署有对外可达的域名。支付宝和微信的支付结果要 POST 回你的地址,localhost 只够本机联调。
  3. 宿主配置里给微信留了五个键。它们注入时没有默认值,缺任何一个,支付应用在装载那一步就失败、日志报占位符解析失败。暂时不开微信也要在宿主侧配置文件(部署口径见 后端部署)把这五个键留成空值:装载只查占位符能不能解析,真正下单要到渠道里才报错。
  4. 后台任务随装载自动生效:通知补发、关闭过期订单、渠道对账都是应用内的定时周期,不需要在调度中心登记,周期写死在代码里。

商业应用要先在应用市场完成购买与激活才装得上,流程见 应用目录。装成功后侧栏多一个「支付管理」,下面四项:

菜单路由需要的权限码
支付应用apppay:app:list
支付渠道channelpay:channel:list
支付订单payOrderpay:order:list
退款订单refundpay:refund:list

每页另有 pay:app:query / add / edit / remove 式的按钮码,支付订单页多一枚 pay:order:submit(在后台发起一笔支付)。分发与角色规则见 菜单与权限码分发。

配它

种子脚本预建一个应用 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:余额扣款发生在业务应用结算那一步,业务方带会员身份下单。会员看到的余额与流水都在会员中心,见 会员中心。

渠道平台匿名回调: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 没有注册策略,不要配它
「商户订单号已存在」业务方用同一个商户订单号重复下单;这个号在表内查重
删除订单被拒「已支付的订单不能删除」删单只放行未支付订单;已收款的钱走退款订单页退
「余额支付失败,会员账户不存在」member 是否启用、该会员有没有余额账户
「应用「会员管理」未安装或未启用,无法调用 …」pay 装了但 member 没装,余额支付或余额退款被调到

实现索引

项值
数据表pay_app、pay_channel、pay_order、pay_refund、pay_notify_task
后台接口前缀/pay/app、/pay/channel、/pay/order(含 POST /pay/order/submit)、/pay/refund
回调端点POST /pay/notify/{channelCode}/{channelId}、POST /pay/notify/refund/{channelCode}/{channelId}(匿名,@SaIgnore)
会员端 / 公开端都没有:本应用无 /portal/pay/**,也没有直出公开页(仓库里不放 site-templates/)
自带静态资源frontend/index.js(后台四页的远程组件)
定时任务通知补发每 30 秒、关闭过期订单每 1 分钟、对账渠道订单状态每 2 分钟
事件广播支付成功 PaySuccessEvent、退款成功 PayRefundSuccessEvent(事件定义在平台侧,业务应用自行监听)
迁移脚本migrations/01-create-pay-tables.sql、02-create-pay-seed-data.sql
源码cn/wujies/pay

那五张表同时也是卸载时的删除依据:AppPurgeService 从迁移脚本里解析 CREATE TABLE 得到「本应用声明的表」,迁移脚本一经执行内容不可改(摘要记账规则见 数据库迁移)。

支付宝与微信两条渠道的真密钥下单、回调验签、退款整条链路没在这台部署上联机跑过,本页的错误串与回调应答形态按代码推定(未联机验证);接真渠道前先在沙箱配置下走一笔最小支付与一笔退款再上生产。

目录