金融科技后端【免费下载链接】pay可能是我用过的最优雅的 Alipay/WeChat/Douyin/Unipay/江苏银行 的支付 SDK 扩展包了项目地址https://gitcode.com/gh_mirrors/pa/pay点击查看免费下载导读本文聚焦 yansongda/pay本仓库即该项目源码中Pay::wechat()-close($order)关闭微信支付订单的完整用法覆盖 JSAPI、App、H5、小程序、Native 五类普通订单以及合单订单的关闭场景。文章不仅给出可直接运行的代码示例还会结合CloseShortcut、WechatAction常量与各场景ClosePlugin源码讲清_action路由规则、必传参数校验、服务商模式差异与插件调用链帮助读者在真实项目中安全、准确地关闭微信支付订单。一、方法概览微信支付关闭订单对应快捷方法如下摘自 web/docs/v3/wechat/close.md方法名参数返回值closearray $ordernull从当前仓库源码看src/Provider/Wechat.php 中close()方法的实际签名是public function close(array $order): Collection|Rocket它会先派发MethodCalled事件便于日志与埋点再通过__call(close, [$order])走 Shortcut 路由最后返回一个空的Collection实例。因此实际调用中你无需关心返回值关单结果以微信服务端返回为准。该方法同时覆盖两类场景关闭普通订单通过_action指定 JSAPI / App / H5 / 小程序 / Native 五种场景关闭合单订单通过combine_out_trade_nosub_orders参数发起合单关单。二、关闭普通订单2.1 最小可用示例Pay::config($config); $order [ out_trade_no 1514027114, // _action jsapi, // jsapi 关单默认 // _action app, // app 关单 // _action combine, // 合单关单 // _action h5, // h5 关单 // _action miniapp, // 小程序关单 // _action native, // native 关单 ]; $result Pay::wechat()-close($order);要点说明out_trade_no为必传参数它是商户系统内部订单号是关闭订单的唯一业务标识。底层插件在装载时会先校验该参数缺失会直接抛出参数异常详见下文“参数校验”一节。不传_action时默认按 JSAPI 关单在 src/Shortcut/Wechat/CloseShortcut.php 中$params[_action] ?? WechatAction::CLOSE_DEFAULT默认值为default而defaultPlugins()返回的就是 JSAPI 的插件链与文档注释“jsapi 关单默认”一致。所有“客观参数”由扩展包自动补齐如mchid直连商户或sp_mchid/sub_mchid服务商模式等请求体字段均由各场景ClosePlugin根据配置自动注入你只需传入订单类主观参数。2.2 订单配置参数所有订单配置参数和官方无任何差别兼容所有功能所有参数请参考以下 API 查看「请求参数」一栏JSAPI订单APP订单合单订单H5订单小程序订单Native订单关于miniapp的提醒文档注释中写的是_action miniapp但当前仓库源码里对应常量是WechatAction::CLOSE_MINI mini见 src/Action/WechatAction.phpCloseShortcut的match也仅匹配mini。实际开发中请传_action mini若传miniapp会落入默认分支并抛出InvalidParamsException。三、关闭合单订单3.1 示例一显式合单参数Pay::config($config); $order [ combine_out_trade_no 1514027114, sub_orders 123456 ]; $result Pay::wechat()-close($order);3.2 示例二显式_action指定合单//$order [ // out_trade_no 1514027114, // sub_orders 123456, // _action combine, //]; $result Pay::wechat()-close($order);合单关单的核心机制在 src/Shortcut/Wechat/CloseShortcut.php 中只要参数里出现combine_out_trade_no或sub_orders中的任意一个CloseShortcut就会优先自动路由到合单关单插件链无需再显式传_action combine。这一分支判断在_action解析之前执行因此两种写法效果等价。3.3 订单配置参数合单关单同样保持与官方接口完全一致的参数语义combine_out_trade_no、sub_orders等字段会原样透传给请求体所有参数请参考这里查看「请求参数」一栏。按官方接口语义sub_orders应为子订单信息数组文档示例中的123456仅为示意实际项目中请按官方「请求参数」要求组装为合法结构。四、_action路由与插件调用链源码解析关闭订单的入口是 src/Shortcut/Wechat/CloseShortcut.php 中getPlugins()的分发逻辑其路由规则与 src/Action/WechatAction.php 中定义的动作常量一一对应_action值常量场景对应插件不传默认CLOSE_DEFAULT defaultJSAPI 关单Jsapi\ClosePluginjsapiCLOSE_JSAPI jsapiJSAPI 关单Jsapi\ClosePluginappCLOSE_APP appApp 关单App\ClosePluginh5CLOSE_H5 h5H5 关单H5\ClosePluginminiCLOSE_MINI mini小程序关单Mini\ClosePluginnativeCLOSE_NATIVE nativeNative 关单Native\ClosePlugincombine或参数含combine_out_trade_no/sub_ordersCLOSE_COMBINE combine合单关单Combine\ClosePlugin每种动作最终返回一组插件链以 JSAPI 为例同样适用于 App、H5、小程序、Native、合单仅中间的业务插件不同StartPlugin::class, // 请求生命周期开始 JsapiClosePlugin::class, // 组装关单请求 URL 与请求体 AddPayloadBodyPlugin::class, // 序列化请求体 AddPayloadSignaturePlugin::class, // 生成微信支付 V3 签名 AddRadarPlugin::class, // 平台证书管理验签公钥等 VerifySignaturePlugin::class,// 校验响应签名 ResponsePlugin::class, // 统一响应处理 ParserPlugin::class, // 解析最终结果该插件链可通过 tests/Shortcut/Wechat/CloseShortcutTest.php 中的testDefault()、testCombine()、testCombineParams()等用例逐一验证。若传入不支持的_action如virtual、foomatch会落入default分支抛出InvalidParamsException错误码为Exception::PARAMS_SHORTCUT_ACTION_INVALID测试用例testVirtual()、testFoo()已覆盖此行为。五、底层 ClosePlugin 实现细节5.1 普通关单Jsapi / App / Mini 插件以 src/Plugin/Wechat/V3/Pay/Jsapi/ClosePlugin.php 为例App 与 Mini 的实现完全一致校验out_trade_no从rocket-getPayload()取出out_trade_no为空则抛出InvalidParamsException错误码PARAMS_NECESSARY_PARAMS_MISSING提示信息形如“Jsapi 关闭订单参数缺少out_trade_no”。组装请求端点直连商户POST /v3/pay/transactions/out-trade-no/{out_trade_no}/close服务商模式POST /v3/pay/partner/transactions/out-trade-no/{out_trade_no}/close按模式注入商户号直连模式请求体只含mchid取自配置服务商模式Pay::MODE_SERVICE $config-getMode()请求体为sp_mchid配置与sub_mchid优先取请求参数中的sub_mchid缺省回落到配置的sub_mchid。从源码结构看H5、Native 的ClosePlugin与上述实现保持一致均校验out_trade_no并请求同一关单端点对应文件位于 src/Plugin/Wechat/V3/Pay/H5/ClosePlugin.php 与 src/Plugin/Wechat/V3/Pay/Native/ClosePlugin.php。5.2 合单关单Combine 插件src/Plugin/Wechat/V3/Pay/Combine/ClosePlugin.php 的处理略有不同校验combine_out_trade_no缺失时抛出“合单关单参数缺少combine_out_trade_no”的InvalidParamsException。组装请求端点POST /v3/combine-transactions/out-trade-no/{combine_out_trade_no}/close直连与服务商模式 URL 相同。自动注入combine_appid优先取请求参数中的combine_appid缺省回落为配置中的mp_app_id公众号 appid。参数清理通过exceptPayload(combine_out_trade_no)将combine_out_trade_no从最终请求体中剔除它只用于拼接 URL而sub_orders等其他字段原样保留透传。六、参数校验与异常处理小结关闭订单过程中可能出现的两类核心异常均由 src/Exception/Exception.php 定义错误码场景异常信息错误码普通关单缺out_trade_no“Jsapi/App/Mini 关闭订单参数缺少out_trade_no”PARAMS_NECESSARY_PARAMS_MISSING合单关单缺combine_out_trade_no“合单关单参数缺少combine_out_trade_no”PARAMS_NECESSARY_PARAMS_MISSING_action非法“不支持的_action [...]”PARAMS_SHORTCUT_ACTION_INVALID建议在实际业务中先通过查询订单Pay::wechat()-find()确认订单状态再决定是否关单避免对已支付或已关闭的订单重复发起关闭请求。七、总结Pay::wechat()-close($order)以极简的数组入参覆盖了微信支付 V3 全部六种关单场景默认 JSAPI 关单、通过_action切换 App/H5/小程序/Native以及通过combine_out_trade_no/sub_orders自动路由合单关单。其背后是CloseShortcut的轻量路由 各场景ClosePlugin的端点组装配合插件链自动完成签名、验签、证书与响应解析。理解 src/Shortcut/Wechat/CloseShortcut.php、src/Action/WechatAction.php 与各 ClosePlugin 源码即可在直连与服务商两种模式下稳定地集成关单能力。赞分享金融科技后端【免费下载链接】pay可能是我用过的最优雅的 Alipay/WeChat/Douyin/Unipay/江苏银行 的支付 SDK 扩展包了项目地址https://gitcode.com/gh_mirrors/pa/pay点击查看免费下载相关推荐支付宝关闭订单实战指南Yansongda Pay close 方法全场景解析支付宝关闭订单实战指南Yansongda Pay close 方法全场景解析 本文基于 Yansongda Pay本仓库讲解支付宝「关闭订单」能力如何通金融科技后端微信支付订单关闭接口实战Yansongda Pay SDK 的 close 方法详解与插件链源码解析微信支付订单关闭接口实战Yansongda Pay SDK 的 close 方法详解与插件链源码解析 本指南以仓库文档 web/docs/v2/wechat/金融科技后端【特别福利】 yansongda/pay 微信支付关闭订单异常问题解析【特别福利】 yansongda/pay 微信支付关闭订单异常问题解析 前言为什么你的微信支付关单总是失败 还在为微信支付关闭订单时频繁出现的异常而困扰吗后端金融科技上一篇中间人攻击模拟实战指南基于 Anthropic-Cybersecurity-Skills 的 ARP 欺骗与 TLS 拦截测试下一篇MongoDB 冒烟测试套件Smoke Test Suites实战指南面向迭代开发的本地快速回归方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
)
