简介面向Java后端开发者的微信企业转账到零钱参考实现聚焦企业付款、工资发放、退款等真实业务场景适合已有一定Web开发基础、需要快速接入微信商户平台的读者。资源以精简RAR压缩包提供共2个Java文件、约3KB分别承担转账接口请求构造与微信签名算法实现便于直接嵌入现有支付模块。目前已有3086人学习下载。源码覆盖商户平台参数配置、AppID/商户号/API密钥调用、MD5与HMAC-SHA256签名、HTTPS与SSL证书管理等关键环节同时演示了转账金额、接收方openid、备注等请求参数的组装方式并针对失败、超时、账户异常等常见返回状态给出处理思路。日志与异步回调的设计可帮助追踪转账结果权限控制与测试环境说明则兼顾安全性和上线前验证。对于需要梳理企业付款完整链路或二次开发微信支付功能的开发者是一份轻量但完整的参考代码。1. 不是普通支付项目用户在小程序点提现钱怎么安全进零钱做过小程序分销或佣金结算的都知道真正麻烦的环节不在前端页面而在「用户点了提现之后」。财务在商户后台一笔笔手工转账名字写错要退金额漏了对不上账。这个项目把微信支付「企业付款到零钱」的能力封装成一套 Java 后台转账服务小程序端触发提现后端把转账单落库、生成签名、加载商户证书走 HTTPS 双向认证请求微信把钱从商户号直接打进用户零钱同时把每笔转账流水和结果查询管起来。适合要做用户提现、退款、报销打款的小程序后台也是 Java 开发者理解微信支付 v2 转账接口的一份完整参考实现。2. 项目定位与技术选型Spring Boot 服务如何把转账做成一个中台2.1 这个转账后台能干什么代码定位在「转账能力中台」这一层不掺具体业务。它对外只暴露一个转账接口和一个查单接口业务方比如分销系统、退款系统往里面传 openid、金额、业务单号后端负责跟微信把账算清。能力上就四件事单笔转账向指定 openid 的用户零钱打款支持校验姓名、自定义备注金额单位统一为分流水落库每笔转账有独立流水状态机是 INIT → TRANSFERRING → SUCCESS / FAILED方便后面做对账和导出查单兜底微信返回超时或结果未知时调 gettransferinfo 把「转账中」的单子刷新成终态扩展位批量转账、并发打款、重试策略都在 service 层预留了位置不动 client 就能加。这个骨架解决的是三个常见痛点。第一手工转账没法跟业务单对应财务对账靠肉眼第二转账接口有金额单位、签名、证书这些硬门槛业务方直接接微信容易踩坑第三转账结果不是即时返回的缺一层「先落库、再查单」的状态管理。项目把这三件事收敛在一个模块里。转账流水对应的表结构很简单但有两个字段必须设计对CREATE TABLE t_transfer_record ( id bigint NOT NULL AUTO_INCREMENT, biz_no varchar(64) NOT NULL COMMENT 业务单号唯一, openid varchar(64) NOT NULL, amount_fen bigint NOT NULL COMMENT 金额单位分, status varchar(16) NOT NULL DEFAULT INIT COMMENT INIT/TRANSFERRING/SUCCESS/FAILED, payment_no varchar(64) DEFAULT NULL COMMENT 微信付款单号, error_msg varchar(255) DEFAULT NULL, create_time datetime DEFAULT NULL, update_time datetime DEFAULT NULL, PRIMARY KEY (id), UNIQUE KEY uk_biz_no (biz_no) ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;biz_no 的唯一索引是幂等判断的兜底比代码里任何 if 判断都可靠payment_no 是微信侧的付款单号用户投诉或对账时要用很多人第一次做会漏掉这个字段。2.2 技术栈与依赖选择| 组件 | 选型 | 用途 | | 语言/框架 | Java 8 Spring Boot 2.x | 提供 Web 入口和配置装配 | | HTTP/SSL | Apache HttpClient 4.5 | 发起带双向证书的 POST 请求 | | XML 处理 | JDK DocumentBuilder / XPath | 组包请求、解析响应 | | 存储 | MySQL可选 MyBatis-Plus | 转账流水表 | | 签名 | MD5v2 老接口 | 参数签名与验签 |这里有两个选型值得说。一个是 HTTP 客户端微信企业付款的老接口是 HTTPS 双向认证RestTemplate 配证书比较绕HttpClient 的 SSLConnectionSocketFactory 是现成的资料也多所以项目用 HttpClient 而不是 OkHttp。另一个是签名老接口是 MD5 字典序拼接commons-codec 的 DigestUtils 就够用不需要引入额外加密库如果后面迁到 v3 商家转账这块要整体换成 SHA256-RSA最后一章会讲改造点。2.3 工程目录与分层设计源码按「入口 → 业务 → 外部通道 → 工具」四层拆wx-transfer/ ├── controller/ │ └── TransferController.java # 转账/查单 HTTP 入口 ├── service/ │ ├── TransferService.java # 转账主流程与状态机 │ └── impl/TransferServiceImpl.java ├── client/ │ ├── WxTransferClient.java # 封装微信转账、查单请求 │ └── WxSslClient.java # 加载 p12 证书的 SSL 客户端 ├── config/ │ ├── WxPayProperties.java # 商户号/appid/密钥/证书路径 │ └── WxPayConfig.java # 参数校验与 Bean 装配 ├── model/ │ ├── TransferRequest.java # 业务入参 │ ├── TransferRecord.java # 流水实体 │ └── WxTransferResponse.java # 微信响应对象 └── util/ ├── WxPaySign.java # 字典序 MD5 签名 └── XmlUtils.java # XML 组包与解析分层逻辑一句话controller 只做基础校验service 管状态和幂等client 管跟微信的通信util 管签名和 XML。依赖方向是从上往下service 依赖 client 的接口而不是具体实现这样换微信接口版本时最多动 client 和 utilservice 以上的业务代码不用动。后文所有代码都能在这个目录里找到对应位置读者拿到源码后可以按图索骥。3. 核心模块拆解一张转账单从进入到返回的完整链路3.1 第一步签名生成微信支付的第一道门槛微信 v2 接口所有请求都要带 sign规则是除 sign 本身外的所有请求参数按 key 字典序排列拼成 keyvaluekeyvalue 的形式末尾接上 key商户API密钥再做 MD5 并转大写。public class WxPaySign { public static String createSign(MapString, String params, String apiKey) { // TreeMap 保证 key 按字典序排列签名能否通过就看这一步 MapString, String sorted new TreeMap(params); StringBuilder sb new StringBuilder(); for (Map.EntryString, String entry : sorted.entrySet()) { String k entry.getKey(); String v entry.getValue(); // 空值不参与签名sign 本身也要排除 if (v null || v.isEmpty() || sign.equals(k)) { continue; } sb.append(k).append().append(v).append(); } // 最后拼接 API 密钥MD5 后转大写 sb.append(key).append(apiKey); String md5 DigestUtils.md5Hex(sb.toString().getBytes(StandardCharsets.UTF_8)); return md5.toUpperCase(); } }逻辑说明分三步。第一步用 TreeMap 排序HashMap 的顺序不稳定同一组参数算出两个 sign 的情况多半是这里出了问题第二步跳空值微信要求参数为空的字段不参与签名如果把空值拼进去再算 MD5签名必然对不上第三步拼 key 后做 MD5编码统一用 UTF-8结果转大写。这个方法要求调用方组装参数时直接传 TreeMap传 HashMap 会让排序失效。参数上 apiKey 是商户平台「账户中心 → API 安全」里设置的 API v2 密钥不是证书私钥两者别混。很多人第一次跑通时在签名上耗掉半天最后发现是某个空值字段也被拼进了签名串。注意这个签名模块只适配 v2 老接口。v3 商家转账改成 SHA256-RSA用商户私钥对报文签名逻辑完全不同。3.2 第二步加载 p12 证书构造双向认证 HTTP 客户端企业付款接口要求客户端证书商户平台下载的 apiclient_cert.p12 是 PKCS12 格式它的密码就是商户号本身。public class WxSslClient { public static CloseableHttpClient build(String mchId, String certPath) throws Exception { // p12 的密码是商户号不是 API 密钥这里最容易填错 KeyStore keyStore KeyStore.getInstance(PKCS12); try (InputStream in new FileInputStream(certPath)) { keyStore.load(in, mchId.toCharArray()); } SSLContext sslContext SSLContexts.custom() .loadKeyMaterial(keyStore, mchId.toCharArray()) .build(); // 微信要求 TLSv1.2hostname 校验保持默认 SSLConnectionSocketFactory factory new SSLConnectionSocketFactory( sslContext, new String[]{TLSv1.2}, null, SSLConnectionSocketFactory.getDefaultHostnameVerifier()); return HttpClients.custom() .setSSLSocketFactory(factory) .build(); } }代码里两个关键点。第一keyStore.load 和 loadKeyMaterial 用了同一个密码 mchId如果传成 API 密钥启动时不报错但握手阶段会抛证书校验失败。第二TLS 版本固定 TLSv1.2微信网关对旧协议握手不友好hostname verifier 保持默认请求地址必须是 api.mch.weixin.qq.com不能用 IP 直连否则证书域名匹配不上。这个方法每次调用会 new 一个 HttpClient实际项目中建议把构建好的 client 缓存在 Spring 容器里只在证书失效时重建减少 TLS 握手开销。如果你在日志里看到每个请求都莫名的多出几百毫秒耗时多半就是这里每次重建了连接。3.3 第三步组包 POST 请求并解析微信响应转账接口地址是 /mmpaymkttransfers/promotion/transfers请求体是 XML。参数里几个关键字段先说明mch_appid 是发起转账的小程序 appidmchid 是商户号注意没有下划线partner_trade_no 是商户侧唯一单号amount 单位是分spbill_create_ip 必须是商户平台白名单里的出口 IP。public WxTransferResponse transfer(WxTransferRequest req) throws Exception { MapString, String params new TreeMap(); params.put(mch_appid, config.getAppId()); params.put(mchid, config.getMchId()); params.put(nonce_str, UUID.randomUUID().toString().replace(-, )); params.put(partner_trade_no, req.getBizNo()); params.put(openid, req.getOpenId()); params.put(check_name, req.getCheckName()); // NO_CHECK / FORCE_CHECK if (StringUtils.isNotBlank(req.getRealName())) { params.put(re_user_name, req.getRealName()); // FORCE_CHECK 时必填 } params.put(amount, String.valueOf(req.getAmountFen())); params.put(desc, req.getDesc()); params.put(spbill_create_ip, config.getSpbillCreateIp()); params.put(sign, WxPaySign.createSign(params, config.getApiKey())); String xml XmlUtils.toXml(params); HttpPost post new HttpPost(https://api.mch.weixin.qq.com/mmpaymkttransfers/promotion/transfers); post.setEntity(new StringEntity(xml, ContentType.create(text/xml, StandardCharsets.UTF_8))); try (CloseableHttpClient client WxSslClient.build(config.getMchId(), config.getCertPath()); CloseableHttpResponse response client.execute(post)) { String respXml EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8); return XmlUtils.parseTransferResponse(respXml); } }这里有两个细节展开说。一是 check_name 字段NO_CHECK 表示不校验真实姓名FORCE_CHECK 表示强制校验此时 re_user_name 必须传用户实名一般提现场景建议 FORCE_CHECK避免 openid 泄露后资金被转走。二是 partner_trade_no 建议直接用业务流水号数据库主键或订单号不要每次生成随机数否则重复请求时微信会按相同单号拒绝反而丢了幂等。响应解析也要做对。微信返回的是 XML通信层和业务层是分开判断的public static WxTransferResponse parseTransferResponse(String xml) throws Exception { DocumentBuilder builder DocumentBuilderFactory.newInstance().newDocumentBuilder(); Document doc builder.parse(new ByteArrayInputStream(xml.getBytes(StandardCharsets.UTF_8))); WxTransferResponse resp new WxTransferResponse(); resp.setReturnCode(textOf(doc, return_code)); resp.setReturnMsg(textOf(doc, return_msg)); resp.setResultCode(textOf(doc, result_code)); resp.setErrCode(textOf(doc, err_code)); resp.setErrCodeDes(textOf(doc, err_code_des)); resp.setPartnerTradeNo(textOf(doc, partner_trade_no)); resp.setPaymentNo(textOf(doc, payment_no)); resp.setPaymentTime(textOf(doc, payment_time)); return resp; } private static String textOf(Document doc, String tag) { NodeList list doc.getElementsByTagName(tag); return list.getLength() 0 ? list.item(0).getTextContent() : ; }return_code 表示微信网关是否正常接收return_code 为 SUCCESS 只代表请求到了微信不代表钱打出去了真正打款成功要看 result_code 为 SUCCESS 并且返回了 payment_no。这个层次判断是后续所有状态流转的依据。payment_no 是微信侧的付款单号对账和客户投诉时要用务必存进流水表。3.4 第四步Service 层把转账单的状态管起来client 只负责跟微信通信业务状态在 service 层管。核心逻辑是先落库再调微信保证任何异常情况下流水都能查到。Override Transactional public TransferResult transfer(TransferRequest request) { // 1. 幂等判断同一 bizNo 只打一次 if (transferRecordMapper.countByBizNo(request.getBizNo()) 0) { return TransferResult.duplicated(request.getBizNo()); } // 2. 先落一条转账中流水重试或查单时能查到 TransferRecord record TransferRecord.init(request); transferRecordMapper.insert(record); // 3. 调微信发起打款 WxTransferResponse resp wxTransferClient.transfer(toWxRequest(request, record)); // 4. 按业务层结果更新状态 if (resp.isBusinessSuccess()) { record.markSuccess(resp.getPaymentNo(), resp.getPaymentTime()); } else { record.markFail(resp.getErrCodeDes()); } transferRecordMapper.updateById(record); return record.toResult(); }这段代码体现三个习惯。第一幂等判断放在事务最前面数据库表上给 biz_no 建唯一索引代码判断加唯一索引双重保险并发请求下才能真正挡住重复打款。第二先插流水再调微信这样即使微信调用抛异常数据库里也有一条 TRANSFERRING 状态的记录后面定时查单任务能接上。第三微信网络请求不要包在 Transactional 里长连接会挤占数据库连接池建议把 client 调用放在事务外或用编程式事务精确控制提交点。4. 运行配置与联调证书、IP、密钥一次调通4.1 前置条件商户号、产品权限、证书三件套跑这个项目之前先确认账号侧有没有三样东西。一是商户号需要在微信支付商户平台完成注册并绑定好小程序二是「企业付款到零钱」的产品权限这个不是默认开通的要在产品中心申请审核会看营业执照和对公账户信息个体户和小微商户在这步容易被卡提前确认经营范围三是 API 证书和 API 密钥都在商户平台的「账户中心 → API 安全」里下载和设置。特别提醒一下 appid 关联这件事。小程序 appid 必须和商户号完成关联绑定否则转账时会报 openid 与 appid 不匹配。关联入口在小程序后台的「支付」菜单绑定关系决定了签名里 mch_appid 能不能对上用户的 openid 来源。一套后台接多个小程序时转账时要按用户来源动态选择 appid不能全局写死一个。4.2 配置项拆解与证书放置工程里所有外部依赖都收敛在 application.yml 的 wxpay 前缀下wxpay: mch-id: 1618888888 # 商户号 app-id: wx8888888888888888 # 小程序 appidopenid 的来源 api-key: 你的APIv2密钥 # 商户平台-账户中心-API安全 cert-path: /data/cert/apiclient_cert.p12 spbill-create-ip: 101.132.xx.xx # 服务器出口公网 IPconfig 包下的 WxPayProperties 用 ConfigurationProperties 把这组配置映射成对象ConfigurationProperties(prefix wxpay) Component public class WxPayProperties { private String mchId; private String appId; private String apiKey; private String certPath; private String spbillCreateIp; // getter / setter 省略 }配置里最容易出问题的是 cert-path 和 spbill-create-ip 两个值。证书文件建议放到服务器固定目录 /data/cert 下别放 classpath 里否则打包后路径会变文件权限记得收紧p12 里有私钥放到 600 权限即可。spbill-create-ip 不是本机局域网 IP是服务器访问公网时的出口 IP在商户平台「企业付款 → 产品设置」里也要放行同一个地址。这两个值对不上联调阶段必炸。4.3 本地联调小额真实验证怎么走通微信支付的沙箱环境对老转账接口支持有限我一般直接用真实商户号做小额打款验证。第一次联调建议打给自己金额 0.1 元即 amount 传 10 分流程走通后再放开业务量。联调步骤按顺序来。第一步启动工程后发起一笔转账先看 return_code不是 SUCCESS 就查 return_msg多半是签名或证书问题。第二步return_code 成功后去微信确认零钱到账通知再到商户平台的「企业付款 → 交易账单」里核对这笔记录确认 payment_no 与本地流水一致。第三步故意把 openid 改成乱值确认业务层错误能正常落库为 FAILED幂等判断也能挡住第二笔重复请求。这套自测用例跑完接口才算真正联调通过。提示第一笔打款前确认商户号余额充足。企业付款走的是商户号余额不是结算后自动通道余额不足会报余额错误。5. 避坑指南企业转账最常见的五个翻车现场5.1 证书握手失败PKIX 与 p12 密码现象请求刚发出就抛 SSLHandshakeException日志里常见 PKIX path building failed 或 unrecognized_name。原因两种最常见。一是 p12 的密码填了 API 密钥微信下发的证书密码是商户号二是项目里放的是 apiclient_cert.pem / apiclient_key.pem 单证书文件而代码按 PKCS12 格式加载。解决从商户平台重新下载 apiclient_cert.p12load 和 loadKeyMaterial 都传 mchId 当密码TLS 版本固定 TLSv1.2请求地址保持 api.mch.weixin.qq.com不要用 IP 直连。验证最快的方式是写一个独立单元测试只调用 WxSslClient.build 并执行一个空请求握手通过再往下查。5.2 金额不合法单位永远是分现象微信返回 AMOUNT_INVALID或者明明传了 1用户只收到 1 分钱。原因接口金额单位是分但业务系统里习惯用元直接拿元的值传进去1 和 100 差了一百倍。解决后端实体字段用 Long 类型存分入参校验强制分单位前端展示的元由后端除以 100 转换。传输层永远不出现元避免精度丢失。这个约定要写进接口文档否则后面接手的同学一定会踩第二次。5.3 openid 与 appid 不匹配现象返回 OPENID_APPID_NOT_MATCH。原因用户的 openid 是在小程序 A 登录产生的转账请求里 mch_appid 填了小程序 B 的 appid微信按 appid 维度校验 openid 归属。解决mch_appid 必须填用户 openid 来源的那个小程序 appid且该 appid 与商户号完成关联绑定。如果一套后台对接多个小程序转账时按用户来源动态选择 appid 和对应的商户配置不要全局写死一套。5.4 IP 白名单与 spbill_create_ip现象返回 IP 地址不在白名单内 或 该 IP 不合法。原因商户平台只放行了某个出口 IP而请求实际走的是另一个出口比如本地联调走了家庭宽带或服务器有多条线路spbill_create_ip 参数也填了跟白名单不一致的值。解决用在线 IP 检测工具确认当前出口 IP加入商户平台白名单同时把 spbill_create_ip 配成同一个值。服务器迁移或换网络后第一件事就是核对这两个值这个坑在联调阶段出现频率极高。5.5 重复转账超时重试后用户收到两笔钱现象一次请求抛出 SocketTimeoutException代码自动重试结果用户收到两笔打款。原因微信可能已经受理了第一次请求只是响应超时没返回客户端误判失败又发了一次转账接口没有天然幂等相同参数也可能生成新单。解决partner_trade_no 用唯一业务单号流水表加 unique 索引做幂等超时后不要盲目重发先调 gettransferinfo 查单根据返回的转账状态决定是重试还是挂起。把「超时 → 查单 → 决定」写成一个固定流程比任何重试策略都稳。6. 二次开发从单笔转账到批量结算的改造路线6.1 批量转账与查单兜底把能力接进真实业务后最先遇到的需求就是批量结算。改造点不在 client而在 service 层加一个批量入口用固定线程池控制并发避免触发微信的频次限制。每单独立异常失败不影响其它单子。public BatchResult batchTransfer(ListTransferRequest requests) { ExecutorService pool Executors.newFixedThreadPool(4); ListFutureTransferResult futures requests.stream() .map(req - pool.submit(() - transferService.transferWithRetry(req))) .collect(Collectors.toList()); // 汇总统计成功 / 失败 / 转账中 }配套要做查单兜底。转账中超时的单子留在 TRANSFERRING 状态起一个定时任务把这些单号的 partner_trade_no 组装成查单请求POST 到 /mmpaymkttransfers/gettransferinfo根据返回的 statusSUCCESS / FAILED / PROCESSING把本地状态刷新成终态。这个定时任务建议每 5 分钟跑一轮只处理创建时间超过 10 分钟仍未终态的单子控制查询量。6.2 迁移到微信支付 V3 商家转账的提前量老接口对新商户在陆续收紧有条件的话新项目可以直接按 V3 商家转账做。改造点集中在签名和报文两层签名换成 SHA256-RSA用商户私钥签名并上送平台证书验签报文从 XML 换成 JSON请求地址变成 /v3/transfer/batches。check_name 在 V3 里叫 user_name且要对真实姓名做 RSA-OAEP 加密后再上送这步最容易漏。目录结构不用动替换 client 和 util 两个包的内容service 的状态机可以完全复用。从那以后我每次接支付类需求都会先把证书、白名单、密钥这三件套的验证写成独立的自测用例跑通了再动业务代码这个习惯让后面所有联调都省了一半时间。希望帮到你。本文还有配套的精品资源点击获取
