简介微信支付商家转账到零钱 DemoThinkPHP是一套面向 ThinkPHP 开发者的完整支付转账示例旨在解决商家向用户零钱退款、返现等资金操作中的接口对接与业务落地问题。资源包共 825 个文件整体大小约 1.61MB以 PHP 源码文件为主639 个并包含 Markdown 文档、JSON 配置、License、Git 忽略文件等辅助资源目录结构清晰可直接用于对照学习和二次开发。示例从微信支付环境接入、支付参数配置、转账请求构建到回调结果处理与签名验证层层展开同时针对支付安全与地区合规性给出代码层面的处理参考整体设计遵循简单实用原则开发者可将精力集中在核心业务逻辑上。目前已有 1464 人学习下载适合正在使用 ThinkPHP 开发微信支付功能、需要参考完整转账流程与安全细节的 PHP 开发者。 上周朋友在群里问用户余额要提现到微信零钱ThinkPHP 项目里怎么调最省事他搜了一堆资料大部分文章还停留在早年“企业付款到零钱”的老接口上照着复制出来的代码跑不通报错信息又看不懂。原因倒不复杂——这个产品早就更名为“商家转账到零钱”接口从 V2 升级到了 V3数据格式从 XML 换成了 JSON签名方式也从 MD5 变成了 RSA-SHA256。这个 Demo 我前后调了两天踩了不少坑今天干脆把整个实现过程、代码结构和排错思路完整拆出来给做微信支付相关任务的 ThinkPHP 开发者一个可直接参考的底子。需要先说明白商家转账到零钱的本质是商户号用自己的资金把一笔钱直接打到一个用户微信零钱里。常见场景包括平台返佣、报销打款、奖励发放、供应链结算等。微信支付对这类资金操作审核非常严格所以“能不能开通”这个问题比“怎么写代码”更值得先搞清楚。1. 先别急着写代码商家转账到零钱的权限门槛与接口选型很多人一上来就找接口文档结果代码写完了才发现商户号根本没权限白忙活半天。这个功能本身就是资金划转类接口微信支付要求商户先在后台申请开通对应产品权限而且不是所有商户号都能通过审核。1.1 产品演进从企业付款到零钱到商家转账我早期接入这个功能时它还叫“企业付款到零钱”老接口路径是/mmpaymkttransfers/promotion/transfers走 XML 的 POST 请求签名用 APIv2 密钥做 MD5。后来微信支付在 2022 年前后调整产品线把它归入“商家转账”体系同时发布了基于 APIv3 的新接口也就是批量转账接口/v3/transfer/batches。对没有存量老代码的新项目我不建议再碰 V2。原因有两个一是新商户号现在想开通 V2 企业付款权限已经很难微信支付在引导大家迁到 V3二是 V3 接口是 JSON 格式、支持批量转账一个批次最多可以放 2000 条明细业务扩展性明显更好。老项目如果已经在跑 V2且没有强需求暂时可以不迁移但新增功能一定要走在 V3 上。1.2 直连模式和服务商模式要分清这里单独提醒一下如果你接的是微信支付服务商模式比如帮多个子商户做代付你的调用身份跟直连模式完全不同。直连模式下商户号自己的 AppID 和自己的商户号绑定服务商模式下需要用服务商商户号并且很多产品规则会受特约商户资质影响。我这个 Demo 以最常见的“直连商户号”为例服务商场景除了参数上多一层绑定关系签名和请求流程是一致的搞懂了直连服务商只是换参数的问题。1.3 开通权限要准备什么登录微信支付商户平台后在“产品中心”找到“商家转账”或者“商家转账到零钱”按页面提示提交申请。我实测下来的经验审核重点会看这几个维度商户主体正常经营营业执照信息完整。转账用途描述清晰例如“平台推广佣金结算”会比较好过“自动退款”或“利润分红”则要额外说明业务流程。一定周期的交易流水或持续经营记录新注册没多久、零交易量的商户号通过率很低。如果接口返回类似“产品权限未开通”或NOT_ENABLED的错误不用怀疑代码先去确认商户平台里的申请状态。2. 开工前的材料清单证书、密钥和 ThinkPHP 配置权限开通之后再回来准备技术参数。商家转账到零钱在 V3 体系下对证书和密钥的要求比普通微信支付接口高一个档次少一个东西签名就会失败。2.1 需要准备的材料材料来源/说明用途商户号 mchid商户平台首页请求身份标识AppID公众号/开放平台账号校验 openid 归属APIv3 密钥商户平台手动设置回调解密、部分敏感数据加密商户 API 证书商户平台下载请求签名含证书序列号商户 API 私钥在商户平台生成证书时得到本地保存签名时使用微信支付平台证书从证书下载接口获取验签、加密用户姓名最容易踩的坑是“商户 API 私钥”和“APIv3 密钥”混为一谈。API 私钥是一把 RSA 私钥文件用来给请求签名APIv3 密钥是一串 32 字节的字符串用来解密回调报文。这两个东西一个是文件一个是口令别弄混。2.2 ThinkPHP 6 中定义配置文件我习惯在config/wechat.php里集中管理这些参数避免散落在控制器里。文件内容类似这样?php return [ // 直连商户号 mch_id 1600000000, // 公众号 AppID app_id wx8888888888888888, // APIv3 密钥 api_v3_key 32位字符串, // 商户API证书序列号 serial_no 从证书详情页复制, // 商户API私钥文件绝对路径 private_key_path /www/wechat_keys/apiclient_key.pem, // 微信支付平台证书公钥文件路径加密请求头 platform_cert_path /www/wechat_keys/wechatpay_platform.pem, // 转账回调通知地址 notify_url https://api.example.com/wechat/transfer/notify, ];私钥文件不要放在项目 web 根目录下放到 web 根目录之外会更安全。ThinkPHP 项目里我一般放到/www/wechat_keys/然后在配置里写绝对路径这样即使 Web 配置有疏漏私钥也不会被直接下载。3. 核心代码实现ThinkPHP 里跑通一次转账需要做的事第一次接 V3 接口的人最大的障碍不是业务参数而是签名机制。微信支付 V3 的每个请求都要在Authorization头里带一段由商户私钥签名的串服务端校验失败就直接拒绝请求。3.1 最关键的签名逻辑V3 签名串的构造规则是固定的把请求方法、请求绝对 URL、时间戳、随机串、请求体拼接起来用商户私钥做 SHA256 签名再按指定格式放进 Authorization 头。我在 ThinkPHP 里封装了一个方法/** * 构造 V3 Authorization 头 * param string $method GET/POST * param string $url 完整请求URL含query参数 * param string $body 请求体JSON字符串 */ protected function buildAuthHeader($method, $url, $body ) { $timestamp time(); $nonce bin2hex(random_bytes(16)); $message $method . \n . $url . \n . $timestamp . \n . $nonce . \n . $body . \n; $privateKey openssl_pkey_get_private(file_get_contents($this-privateKeyPath)); if (!$privateKey) { throw new \Exception(商户私钥读取失败); } openssl_sign($message, $signature, $privateKey, OPENSSL_ALGO_SHA256); return sprintf( WECHATPAY2-SHA256-RSA2048 mchid%s,nonce_str%s,signature%s,timestamp%d,serial_no%s, $this-mchId, $nonce, base64_encode($signature), $timestamp, $this-serialNo ); }这段代码有两个细节必须注意第一$body是请求体的原始 JSON 字符串调 GET 接口且没有查询参数时它就是空字符串不能是null第二$url必须是完整的https://api.mch.weixin.qq.com/...形式如果 URL 带了查询参数也要原样拼进去参与签名。很多“签名不正确”的问题都是这两处没对齐。3.2 发起转账批次接下来是业务核心创建转账批次。V3 的/v3/transfer/batches接口一次可以带多条明细。参数组织如下{ appid: wx8888888888888888, out_batch_no: pl2025010112345678, batch_name: 平台推广佣金结算, batch_remark: 2025年1月佣金, total_amount: 800, total_num: 2, transfer_detail_list: [ { out_detail_no: pl20250101001, transfer_amount: 500, transfer_remark: 1月推广佣金, openid: o-MYE42l80oelYMDE34nYD45X }, { out_detail_no: pl20250101002, transfer_amount: 300, transfer_remark: 1月推广佣金, openid: o-MYE42l80oelYMDE34nYD46Y, user_name: base64加密后的姓名 } ], transfer_scene_id: 1000 }其中total_amount和transfer_amount的单位都是分不是元。transfer_scene_id字段需要根据转账用途从官方文档选择对应场景编码我用的是平台推广佣金对应的场景值。如果业务要求强校验用户姓名比如FORCE_CHECK模式需要在参数里加user_name字段而且这个字段不是明文要拿微信支付平台证书的公钥做 RSA-OAEP 加密后再转 base64。代码如下public function encryptUserName($userName) { $publicKey openssl_pkey_get_public(file_get_contents($this-platformCertPath)); if (!$publicKey) { throw new \Exception(微信支付平台证书读取失败); } $encrypted ; openssl_public_encrypt($userName, $encrypted, $publicKey, OPENSSL_PKCS1_OAEP_PADDING); return base64_encode($encrypted); }生成请求体后用统一封装的方法发送public function createBatch($params) { $url https://api.mch.weixin.qq.com/v3/transfer/batches; $json json_encode($params, JSON_UNESCAPED_UNICODE); $authorization $this-buildAuthHeader(POST, $url, $json); $result $this-httpPost($url, $json, $authorization); if (isset($result[code])) { // 接口返回错误码优先记录方便排查 throw new \Exception(微信转账接口异常: . $result[message] ?? json_encode($result)); } return $result; }这里务必注意同步接口返回的batch_id只代表微信支付接收了批次不代表每一笔都转账成功。转账结果会通过异步回调推送也需要主动查询明细状态确认终态。3.3 查询转账单状态转账批次创建后我们需要在合适的时机主动查询保证业务订单状态正确。查询接口也要签名但签名串里不带请求体URL 里如果带查询参数要连同参数一起签名。我在代码里直接传完整 URLpublic function queryBatchByOutNo($outBatchNo) { $url https://api.mch.weixin.qq.com/v3/transfer/batches/out-batch-no/ . $outBatchNo . ?need_query_detailtrue; $authorization $this-buildAuthHeader(GET, $url, ); return $this-httpGet($url, $authorization); }查询接口返回的transfer_state字段区分FINISHED、FAIL等不同状态。定时任务里我会把一批处于“已创建”但始终没有回调结果的转账单捞出来逐个调这个接口做状态补偿。3.4 回调通知解密转账结果通过异步回调推送到我们配置的notify_url回调报文里的resource.ciphertext是 AES-256-GCM 加密的内容需要用 APIv3 密钥解密。解密时有个容易犯错的细节ciphertext解 base64 后末尾 16 字节是 GCM 的认证标签tag要拆出来单独传给openssl_decryptpublic function decryptCallback($ciphertextB64, $nonce, $associatedData) { $ciphertext base64_decode($ciphertextB64); $tag substr($ciphertext, -16); $content substr($ciphertext, 0, -16); $plaintext openssl_decrypt( $content, aes-256-gcm, $this-apiV3Key, OPENSSL_RAW_DATA, $nonce, $tag, $associatedData ); return json_decode($plaintext, true); }回调处理完成后必须向微信返回 HTTP 200 和{code:SUCCESS}这样的响应体否则微信会按策略重复推送好几次。这个细节在联调阶段一定要处理好。4. 实测中容易翻车的细节签名、证书序列号、IP 白名单和金额代码写完只是第一步真正花时间的是联调阶段碰到的各种报错。下面这些坑我每一类都遇到过按“现象-原因-解决”的顺序写清楚。4.1 签名错误 invalid signature如果请求返回invalid signature优先检查三件事私钥是否跟商户 API 证书是同一对。有些商户在平台重新申请过证书却还在用旧的私钥文件签名自然不通过。签名串里的 URL 是否带了协议头和查询参数。之前我封装查询接口时只传了路径漏掉了https://api.mch.weixin.qq.com前缀微信验签比对不上。请求体是否跟签名时一致。例如 PHP 里json_encode默认会把中文转成\uXXXX如果你签名时用的是JSON_UNESCAPED_UNICODE生成的字符串发送时也必须是同一个字符串。我在封装方法里统一处理了编码避免这类不匹配。4.2 证书序列号对不上请求头里的serial_no是商户 API 证书的序列号不是证书文件的文件名也不是证书内容里的随机字符串。获取方式是在商户平台的“API 安全 - API 证书”里直接复制或者用命令读证书openssl x509 -in apiclient_cert.pem -noout -serial这个序列号是十进制的还是带分隔符的要按商户平台展示的形式填。填错的话微信会返回“证书序列号不正确”这个错跟签名问题不一样一眼就能定位。4.3 IP 白名单限制V3 接口在商户平台配置了 API 安全 IP 白名单不在白名单内的请求会被拒绝报错信息经常会误导人我遇到过直接把请求拒在签名校验之前的情况。本地开发环境出口 IP 一变就会导致“上午能调通下午突然报错”。解决办法是在商户平台把正式服务器的公网 IP 加到白名单里本地调试时把当前出口 IP 临时加进去调完再删。如果公司网络是动态 IP最好直接在服务器上联调。4.4 金额精度和单笔限额转账金额是整数分PHP 里如果从数据库读出来的是元单位浮点数直接乘以 100 再转 int 很容易因为浮点精度出现“差一分钱”的诡异问题。稳妥做法是金额在数据库就存成分单位的整数或者用bcmul($amount, 100, 0)做精确的十进制乘法千万别用intval($amount * 100)这种写法。另外微信支付对单笔转账额度和单日累计都有约束超出会返回TRANSFER_AMOUNT_EXCEED_LIMIT。具体数值跟产品和商户号有关联调阶段可以先用 1 分钱或者最低金额测试通道通不通再逐渐放大验证额度。5. 从 Demo 到生产幂等单号、对账机制和几个安全细节Demo 跑通了不等于可以上线。从“能调通接口”到“能稳定处理线上资金”中间还差着工程化设计。5.1 幂等与唯一单号批量转账接口的out_batch_no是商户侧唯一批次号明细里的out_detail_no是每个明细的唯一单号。这两个单号必须在整个商户号下全局唯一并且生成后不能修改。我建议用“业务前缀 业务单号 日期”的方式生成例如TFR2025010112000001这样既满足唯一性排查问题时也一眼能看出是哪类业务。在业务代码里还要防止同一笔提现请求被用户重复提交导致重复打款。做法是生成转账批次前先在业务订单表里把订单状态置为“转账处理中”同时用唯一索引约束业务订单号和转账批次号的关系让并发重复请求在数据库层面直接失败。5.2 状态查询与对账转账异步回调不是 100% 能送达网络抖动、回调超时都会导致本地订单永远停在“处理中”。线上必须有个定时任务做兜底每 5 到 10 分钟扫一次超过一定时间未终态的转账单调用查询接口把状态刷新回本地。对账上可以每天拉一次微信支付的对账单跟本地“成功转账”的记录做比对发现差异及时人工复核。小额差错可能无所谓但涉及资金宁可在状态上多一次查询也不要漏掉一笔失败单。5.3 日志与私钥安全转账接口的请求响应日志建议至少保留 90 天。日志里不要记录完整用户姓名、openid、金额以外的敏感信息尤其不能把请求体里的user_name密文直接 dump 进日志这会给后续安全审计带来麻烦。日志里记商户批次号、响应码、HTTP 状态码就够了。私钥文件的权限也要收紧在 Linux 服务器上至少设置为 600所属用户改成 PHP-FPM 的运行用户防止被同服务器的其他账号读取。能把私钥放到单独的密钥管理服务里更好小项目至少做到不把私钥提交进 Git 仓库。我在实际开发中体会到商家转账这类资金接口代码本身并不复杂复杂的是对签名、回调、幂等、对账这些细节的把控。微信支付官方实际上也提供了wechatpay-php这个 SDK如果项目里没有特殊要求我反而建议生产环境直接用官方 SDK它把签名、验签、证书下载、回调解密都封装好了至少能规避掉一半我上面写的这类问题。手写一遍 Demo 的价值是让你真正理解请求在每一层经历了什么排查问题的时候心里有底不至于对着报错信息发懵。两者结合起来才是对接这类接口的正确姿势。本文还有配套的精品资源点击获取