内置官方支付配置与上线验收

支持范围

• 支付宝：公钥模式，电脑网站支付、手机网站支付、当面付扫码。产品码以控制台选择为准，不根据浏览器自动改成商户未开通的产品。
• 微信：API v3 自动平台证书模式，Native 扫码、普通手机浏览器 H5。微信内置浏览器的 JSAPI/小程序不在本轮支持范围，H5 会提示用系统浏览器打开。
• 官方支付不依赖 lywq；lywq 外接通道仍通过独立适配器使用。订单创建付款后绑定原支付方，后续查单、关单和退款不会静默切换支付方。

配置

当前按人民币 CNY 结算，不能只改符号模拟美元支付。支付私钥/API V3 密钥由服务端加密保存，主题不可读取。站点迁移与旧数据升级见 支付凭据保护与升级说明。

回调域名必须是站点对外可访问的 HTTPS origin，如 https://example.com，不要填写路径、参数或片段。付款返回地址必须同源。商户后台域名和产品授权需与实际部署匹配。

支付宝配置应用 ID、商户私钥、支付宝公钥、RSA2、网关域名。生产使用 openapi.alipay.com；沙箱使用对应网关与沙箱密钥，不能混用。建议填写 sellerId 启用明确的商户身份检查。

支付宝产品选择：

微信配置 appId、mchId、商户私钥、商户证书序列号、API v3 密钥。当前使用自动平台证书，尚不支持仅配置微信支付公钥 ID 的另一种验签模式。H5 必须另外开通商户 H5 权限和支付域名；请求包含付款人 IP、H5Info。反向代理应由 Halo 的受信任转发设置解析真实客户端地址，不要允许互联网用户任意伪造转发头。

公开回调路由：

• /apis/api.knowsphere.webjing.com/v1alpha1/payment-providers/alipay/callback
• /apis/api.knowsphere.webjing.com/v1alpha1/payment-providers/wechat/callback

不要给回调增加登录跳转或缓存。微信签名头与原始 JSON body 必须完整传递。HTTP 请求头不区分大小写。验签或业务一致性校验失败返回非 2xx；服务端暂时失败允许网关重试。

支付与资金状态

网关下单使用 initiating 状态，阻止并行的取消或重复下单。下单完成回到 pending；成功回调可直接进入 paid/completed。请求中断超过恢复等待时间后，订单协调器主动查单恢复。支付过程中不要删除订单或随意替换商户配置。

取消/过期使用 cancelling 状态。先查单、再关单，网关已支付则补单发放权益。网关暂时不可用时保留 cancelling 并重试，不把未知结果判成未付款。

全额退款使用由订单号确定的稳定退款申请号。微信先查询该退款号，不存在时才创建。同一退款的网络重试不会改变申请号。

• refunding：退款请求处理中或网络结果暂时未知，继续保留权益并查询结果。
• refund_failed：网关明确拒绝或返回异常/关闭，需到商户平台核实，不自动重开另一笔退款。
• refund_finalizing：已确认到账，正在撤销权益；失败时继续本地收尾，不再次退款。
• refunded：退款与权益收尾完成。

本轮为全额订单退款，不提供多笔部分退款。外接 lywq 自动退款仍不支持，需按原商户平台流程处理，插件会在发起前明确提示。

二维码通过服务端 ZXing 本地生成 PNG data URL；付款内容不发送到第三方图片网站。网页支付保留显式“打开付款页面”按钮，浏览器拦截时可恢复。扫码等待时显示有效期并查询结果，关闭弹框会停止轮询。

部署与验收

在 Halo 2.26.0+ 测试站安装与目标环境一致的正式插件包。主题不需要插件源码或构建凭据。

安装同一次构建的后端与主题资源，不能只替换 JS：新的支付状态、二维码图片和回调处理必须配套。Base 与 Pro 的资源文件名不同，始终读取 Finder 的 cssUrl/jsUrl。

自动化验证覆盖 SDK 请求结构、微信扫码图片可解码、退款只路由一次、退款处理中不撤权、关闭失败可恢复、回调失败响应、金额不匹配拒绝补单，以及被浏览器拦截后的付款入口。它不等同于真实网关验收。

上线前在自有商户环境逐项验收：支付宝沙箱及各已开通产品、微信 Native 手机扫码与 H5、支付成功回调、临时阻断通知后的查单补偿、取消与支付同时发生、重复通知、退款 PROCESSING 到 SUCCESS、退款异常人工核对、退款后权限回收。正式扣款/退款需由商户授权人员操作。