SKIT.FlurlHttpClient.Wechat.TenpayV3 中 Native 支付接口的必填参数问题解析

在使用 SKIT.FlurlHttpClient.Wechat.TenpayV3 3.2.0 及以上版本时，开发者可能会遇到 Native 支付接口调用失败的问题，错误提示为"输入源/body/scene_info/payer_client_ip映射到字段用户终端IP必填性规则校验失败"。本文将深入分析这一问题的原因及解决方案。

问题现象

当开发者从 3.2.0 以下版本升级到更高版本后，调用 Native 支付接口时会收到 400 错误，提示 payer_client_ip 字段为必填项。而回退到 3.2.0 及以下版本时，相同的代码却能正常工作。

技术背景

Native 支付是微信支付提供的一种支付方式，适用于 PC 网站等场景。在调用 Native 支付接口时，请求参数中包含一个可选的 scene_info 字段，该字段下又包含 payer_client_ip 等子字段。

问题根源分析

1. 版本差异：3.2.0 以下版本在初始化 CreatePayTransactionNativeRequest 时会自动创建 Scene 对象，但未强制要求填写 payer_client_ip 字段。而 3.2.0 以上版本中，如果存在 scene_info 字段，微信支付端会严格校验其子字段。

2. 参数规则：

   • scene_info 本身是可选字段
   • 但如果传入了 scene_info，则其下的 payer_client_ip 变为必填字段
   • 3.2.0 以下版本可能默认传入了空字符串，而微信支付端未严格校验

3. SDK 行为变化：新版本 SDK 初始化时会创建 Scene 对象，但未自动填充 payer_client_ip，导致校验失败。

解决方案

1. 临时解决方案：

   • 手动将 request.Scene 设为 null
   • 或者明确设置 payer_client_ip 为有效客户端 IP

2. 推荐做法：

   var request = new CreatePayTransactionNativeRequest()
   {
       OutTradeNumber = order.Number,
       AppId = _tenpayOptions.GZHAppId,
       Description = description,
       NotifyUrl = _tenpayOptions.NotifyUrl,
       Amount = new CreatePayTransactionNativeRequest.Types.Amount() { Total = (int)(order.ActualPayment * 100) },
       Scene = null // 显式设置为 null
   };
   

3. 最佳实践：

   • 如果需要收集用户终端信息，应该正确填写 payer_client_ip
   • 如果不需要这些信息，应该确保不传入 scene_info 字段

后续改进

SDK 维护者已注意到这一问题，计划在后续版本中：

1. 默认不初始化 scene_info 字段
2. 优化参数校验逻辑
3. 与微信支付官方沟通规范参数校验规则

总结

这一问题反映了支付接口参数校验的严格性变化。开发者在升级 SDK 版本时，应当仔细阅读变更日志，并按照最新规范调整代码。对于支付类接口，严格按照官方文档要求填写所有必填参数是最稳妥的做法。