docs/NEW_TRANSFER_API_USAGE.md
从2025年1月15日开始,微信支付推出了新版的商户转账API。新开通的商户号只能使用最新版本的商户转账接口。WxJava 已经完整支持新版转账API。
MerchantTransferService/v3/transfer/batchesTransferService/v3/fund-app/mch-transfer/transfer-bills微信支付转账支持两种收款授权模式:
WxPayConstants.ReceiptAuthorizationMode.CONFIRM_RECEIPT_AUTHORIZATIONWxPayConstants.ReceiptAuthorizationMode.NO_CONFIRM_RECEIPT_AUTHORIZATIONTransferBillsRequest request = TransferBillsRequest.newBuilder()
.appid("your_appid")
.outBillNo("NO_CONFIRM_" + System.currentTimeMillis())
.transferSceneId("1005") // 佣金报酬场景
.openid("user_openid")
.transferAmount(200) // 2元
.transferRemark("免确认收款转账")
.receiptAuthorizationMode(WxPayConstants.ReceiptAuthorizationMode.NO_CONFIRM_RECEIPT_AUTHORIZATION)
.userRecvPerception("Y")
.build();
try {
TransferBillsResult result = transferService.transferBills(request);
System.out.println("转账成功,直接到账:" + result.getTransferBillNo());
} catch (WxPayException e) {
if ("USER_NOT_AUTHORIZED".equals(e.getErrCode())) {
System.err.println("用户未授权免确认收款,请先引导用户进行授权");
}
}
TransferBillsRequest request = TransferBillsRequest.newBuilder()
.appid("your_appid")
.outBillNo("CONFIRM_" + System.currentTimeMillis())
.transferSceneId("1005")
.openid("user_openid")
.transferAmount(150) // 1.5元
.transferRemark("需确认收款转账")
// .receiptAuthorizationMode(...) // 不设置时使用默认的确认模式
.userRecvPerception("Y")
.build();
TransferBillsResult result = transferService.transferBills(request);
System.out.println("转账发起成功,等待用户确认:" + result.getPackageInfo());
使用免确认授权模式时,需要处理以下可能的错误:
try {
TransferBillsResult result = transferService.transferBills(request);
} catch (WxPayException e) {
switch (e.getErrCode()) {
case "USER_NOT_AUTHORIZED":
// 用户未授权免确认收款
System.err.println("请先引导用户进行免确认收款授权");
// 可以引导用户到授权页面
break;
case "AUTHORIZATION_EXPIRED":
// 授权已过期
System.err.println("用户授权已过期,请重新授权");
break;
default:
System.err.println("转账失败:" + e.getMessage());
}
}
// 获取WxPayService实例
WxPayService wxPayService = new WxPayServiceImpl();
wxPayService.setConfig(config);
// 获取新版转账服务
TransferService transferService = wxPayService.getTransferService();
// 构建转账请求
TransferBillsRequest request = TransferBillsRequest.newBuilder()
.appid("your_appid") // 应用ID
.outBillNo("T" + System.currentTimeMillis()) // 商户转账单号
.transferSceneId("1005") // 转账场景ID(佣金报酬)
.openid("user_openid") // 用户openid
.userName("张三") // 收款用户姓名(可选,需要加密)
.transferAmount(100) // 转账金额(分)
.transferRemark("佣金报酬") // 转账备注
.notifyUrl("https://your-domain.com/notify") // 回调地址(可选)
.userRecvPerception("Y") // 用户收款感知(可选)
.build();
try {
TransferBillsResult result = transferService.transferBills(request);
System.out.println("转账成功,微信转账单号:" + result.getTransferBillNo());
System.out.println("状态:" + result.getState());
} catch (WxPayException e) {
System.err.println("转账失败:" + e.getMessage());
}
// 通过商户单号查询
String outBillNo = "T1642567890123";
TransferBillsGetResult result = transferService.getBillsByOutBillNo(outBillNo);
// 通过微信转账单号查询
String transferBillNo = "1000000000000000000000000001";
TransferBillsGetResult result2 = transferService.getBillsByTransferBillNo(transferBillNo);
System.out.println("转账状态:" + result.getState());
System.out.println("转账金额:" + result.getTransferAmount());
// 撤销转账(仅在特定状态下可撤销)
String outBillNo = "T1642567890123";
TransferBillsCancelResult cancelResult = transferService.transformBillsCancel(outBillNo);
System.out.println("撤销结果:" + cancelResult.getState());
// 在回调接口中处理通知
@PostMapping("/transfer/notify")
public String handleTransferNotify(HttpServletRequest request) throws Exception {
String notifyData = StreamUtils.copyToString(request.getInputStream(), StandardCharsets.UTF_8);
// 构建签名头
SignatureHeader header = new SignatureHeader();
header.setTimeStamp(request.getHeader("Wechatpay-Timestamp"));
header.setNonce(request.getHeader("Wechatpay-Nonce"));
header.setSignature(request.getHeader("Wechatpay-Signature"));
header.setSerial(request.getHeader("Wechatpay-Serial"));
try {
TransferBillsNotifyResult notifyResult = transferService.parseTransferBillsNotifyResult(notifyData, header);
// 处理业务逻辑
String outBillNo = notifyResult.getOutBillNo();
String state = notifyResult.getState();
System.out.println("转账单号:" + outBillNo + ",状态:" + state);
return "SUCCESS";
} catch (WxPayException e) {
System.err.println("验签失败:" + e.getMessage());
return "FAIL";
}
}
| 特性 | 传统API (MerchantTransferService) | 新版API (TransferService) |
|---|---|---|
| 发起方式 | 批量转账 | 单笔转账 |
| API路径 | /v3/transfer/batches | /v3/fund-app/mch-transfer/transfer-bills |
| 场景支持 | 基础转账场景 | 丰富的转账场景 |
| 回调通知 | 支持 | 支持 |
| 撤销功能 | 不支持 | 支持 |
| 适用商户 | 所有商户 | 新开通商户必须使用 |
TransferService)通过以上指南,您可以轻松使用WxJava的新版商户转账API功能。