v3.8 升级指南

此版本包含多个 BREAKING CHANGES，建议在升级前仔细阅读以下内容。

重点检查

运行环境

• 确认 PHP 版本 >= 8.2，否则无法安装此版本

简单使用者

• 检查是否有使用微信 MchTransfer 相关插件，命名空间已变更为 Transfer
• v3.8.0-beta.2 起新增微信小程序虚拟支付支持，如需使用请在 wechat.default 配置中增加 virtual_pay 节点（offer_id、app_key、callback_token 等）
• v3.8.0-beta.4 起各 Provider 配置校验从 Pay::config() 推迟到实际使用该 Provider 时执行，未使用的 Provider 配置不完整不再导致初始化报错
• v3.8.0-beta.4 起微信虚拟支付客户端签名自动对 signData 做字典序排序，并在返回结果中提供与签名逐字节一致的 signData JSON 字符串，前端请原样传递给 wx.requestVirtualPayment
• v3.8.0-beta.4 起微信虚拟支付服务端 API 支持配置 virtual_pay.app_secret 自动获取并缓存 access_token（stable_token 接口）
• v3.8.0-beta.5 起依赖要求变更为 yansongda/artful ~1.2.0、yansongda/supports ~4.1.0（Composer 安装时自动处理）
• v3.8.0-beta.5 起所有 Provider 配置统一校验 mode 合法性，非法值直接抛出 InvalidConfigException（此前为 warning 或静默回退）；江苏银行不支持服务商模式（PayMode::SERVICE），传入将被拒绝
• v3.8.0-beta.5 修复 PayPal 请求 body 残留业务参数的问题（查询/捕获/退款请求不再混入 order_id、refund_id 等业务标识参数），PayPal 回调验签前置校验扩展至全部 transmission/cert/algo 请求头（#1196）
• v3.8.0-beta.5 修复 Stripe 查询/取消/退款查询接口因请求残留内部参数而实际不可用的问题；Stripe 支付缺必要参数时改为 SDK 侧直接抛出异常；新增支持通过 _headers 参数注入自定义请求头（如 Idempotency-Key、Stripe-Version、Stripe-Account）
• v3.8.0-beta.6 起抖音「担保支付」（ecpay）已全部删除，替换为「通用交易系统」，请务必阅读下方 抖音：担保支付 → 通用交易系统（3.7 → 3.8 迁移指引）
• v3.8.0-beta.7 起仅使用微信小程序虚拟支付时不再强制配置微信支付商户凭据：同时配置 virtual_pay.app_key 与 virtual_pay.app_secret 后，mch_id、mch_secret_key、mch_secret_cert、mch_public_cert_path 可全部留空；若配置了其中任意一项，则四项仍需完整填写（#1218）
• v3.8.0-beta.8 起 Provider 运行模式统一为枚举 PayMode：配置项 mode 请写 PayMode::NORMAL / PayMode::SANDBOX / PayMode::SERVICE（use Yansongda\Pay\Enum\PayMode;，仍兼容历史 int 写法 0/1/2），Pay::MODE_* 常量已删除；$config->getMode() 返回 PayMode 枚举，=== Pay::MODE_SERVICE 这类与 int 的比较需改为 ->isService()（#1221）

自有插件开发者

• 检查是否有自行扩展相关插件，如果有，请对照 breaking changes 检查是否需要更改
• 所有 Plugin 已迁移使用 Trait 方法代替 Functions.php 函数调用
• v3.8.0-beta.3 起所有 Provider 的 _url payload 字段统一为前导 / 格式，各 Provider 的 base URL 常量已去掉尾部 /。如自定义插件中设置了 _url 字段，请遵循前导 / 约定（例如 /v3/pay/transactions/native 而非 v3/pay/transactions/native）
• v3.8.0-beta.5 起 src 内 provider 名称 100% 常量化，统一引用 Pay::PROVIDER_* 常量；Config 的 Provider 配置类映射与 AbstractServiceProvider 改为静态实例化，自定义 ServiceProvider 或扩展 Provider 映射时请留意（#1193、#1194）

更改版本号

将 composer.json 的 yansongda/pay 版本号更改为 ~3.8.0，随后 composer update 即可。

BREAKING CHANGES

• change: 最低 PHP 版本要求从 8.0 升级到 8.2 (#1139)
• change: 所有 Provider 配置统一校验 mode 合法性，非法值由原来的 warning / 静默回退改为抛出 InvalidConfigException(CONFIG_PROVIDER_INVALID)；江苏银行不再接受服务商模式 PayMode::SERVICE (#1197)
• delete: 移除废弃函数 get_alipay_config、get_wechat_config、get_unipay_config，请使用 get_provider_config 代替 (#1139)
• delete: 移除废弃的 Wechat\StartPlugin，请使用 Yansongda\Artful\Plugin\StartPlugin 代替 (#1139)
• delete: 移除废弃的微信 Transfer 插件（因微信支付 API 变更）(#1139)
• change: 重命名 MchTransfer 命名空间为 Transfer (#1139)
• delete: 删除 src/Functions.php 文件，所有辅助函数已迁移到对应的 Trait (#1142, #1143, #1144)
• delete: 删除抖音「担保支付」（ecpay）全部实现：Plugin\Douyin\V1\Pay\AddPayloadSignaturePlugin、Plugin\Douyin\V1\Pay\Mini\{Pay,Query,Refund,QueryRefund}Plugin 及配置字段 mini_app_id/mch_id/mch_secret_token/mch_secret_salt/thirdparty_id；详见下方迁移指引
• change: 重命名 Wechat::URL_VIRTUAL 常量为 URL_OPENAPI，并扩展路由/sns/到开放接口域名 (#788)
• change: 迁移 Plugin\Wechat\Virtual\GetAccessTokenPlugin 至 Plugin\Wechat\Openapi\GetStableTokenPlugin（微信开放接口域）(#788)
• change: 迁移 Plugin\Wechat\Virtual\CheckResponsePlugin 至 Plugin\Wechat\Openapi\ResponsePlugin（合并 HTTP 状态码与业务 errcode 校验；异常文案由「微信虚拟支付返回业务异常/微信返回状态码异常」变为「微信开放接口返回业务/状态码异常」，异常码不变）(#788)
• change: ProviderConfigInterface::getMode() 返回类型由 int 变更为 PayMode 枚举，AbstractConfig::getModeEnum() 移除；$config->getMode() === Pay::MODE_SERVICE 这类写法恒为 false（枚举与 int 严格比较不相等），请改用 $config->getMode()->isService()；$config->toArray()['mode'] 同步由 int 变为 PayMode（toJson() / json_encode() 仍输出 0/1/2）(#1221)
• delete: 删除 Pay::MODE_NORMAL / Pay::MODE_SANDBOX / Pay::MODE_SERVICE 常量，请改用 PayMode::NORMAL / PayMode::SANDBOX / PayMode::SERVICE（use Yansongda\Pay\Enum\PayMode;）；配置项 mode 仍兼容历史 int 写法（0/1/2）(#1221)

抖音：担保支付 → 通用交易系统（3.7 → 3.8 迁移指引）

v3.8.0-beta.6 起，抖音 Provider 为「通用交易系统」（trade_basic）实现，老的「担保支付」（ecpay）已全部删除，升级即坏，无兼容层。

配置字段映射

老（3.7.x 担保支付）	新（3.8 通用交易系统）	说明
mini_app_id	app_id	即 client_key
（无）	app_secret	新增，获取 client_token
mch_secret_salt（MD5 请求签名）	app_private_key	改为 RSA 应用私钥（SHA256-RSA2048）下单加签
mch_secret_token（SHA1 回调校验）	douyin_public_key	改为抖音平台公钥验签（Byte-* 回调头 + 三行验签串）
mch_id / thirdparty_id	（删除）	通用交易系统接口 schema 无此字段，多门店用下单参数 merchantUid 透传

用法变化

• 下单：mini() 不再调用服务端 API，而是返回 {data, byteAuthorization} 供前端 tt.requestOrder(data, byteAuthorization)，下单参数改为官方 camelCase 字段（outOrderNo/totalAmount/skuList/orderEntrySchema 等）
• 查询/退款：统一走 query()/refund() + _action 分发（order/cps/refund；refund 支持 _action=audit 退款审核），插件不再注入 app_id 等字段
• 回调：callback() 入参传 ServerRequestInterface（需 Byte-* 回调头验签），array 入参不再支持；callback() 统一处理支付结果/退款结果/退款申请三类回调（按 body type 分发），退款申请回调需业务方自行构造同步应答
• 存量担保支付订单（老 order_id/order_token 等）的退款/查询不在新系统覆盖范围内，如有此类订单请停留在 v3.7.x 处理完再升级