Skip to content

Commit 262a02b

Browse files
CopilotCopilot
authored
📝 为微信支付新增商户转账接口添加全面的文档和示例
1 parent 3a1d807 commit 262a02b

File tree

3 files changed

+526
-0
lines changed

3 files changed

+526
-0
lines changed

‎NEW_TRANSFER_API_SUPPORT.md

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# 微信支付新版商户转账API支持
2+
3+
## 问题解答
4+
5+
**问题**: 新开通的商户号只能使用最新版本的商户转账接口，WxJava是否支持？
6+
7+
**答案**: **WxJava 已经完整支持新版商户转账API！** 从2025年1月15日开始生效的新版转账API已在WxJava中实现。
8+
9+
## 新版转账API特性
10+
11+
### 1. API接口对比
12+
13+
| 特性 | 传统转账API | 新版转账API (2025.1.15+) |
14+
|------|-------------|-------------------------|
15+
| **服务类** | `MerchantTransferService` | `TransferService` |
16+
| **API路径** | `/v3/transfer/batches` | `/v3/fund-app/mch-transfer/transfer-bills` |
17+
| **转账方式** | 批量转账 | 单笔转账 |
18+
| **场景支持** | 基础场景 | 丰富场景（如佣金报酬等） |
19+
| **撤销功能** | ❌ 不支持 | ✅ 支持 |
20+
| **适用范围** | 所有商户 | **新开通商户必须使用** |
21+
22+
### 2. 新版API功能列表
23+
24+
✅ **发起转账** - `transferBills()`
25+
✅ **查询转账** - `getBillsByOutBillNo()` / `getBillsByTransferBillNo()`
26+
✅ **撤销转账** - `transformBillsCancel()`
27+
✅ **回调通知** - `parseTransferBillsNotifyResult()`
28+
✅ **RSA加密** - 自动处理用户姓名加密
29+
✅ **场景支持** - 支持多种转账场景ID
30+
31+
## 快速开始
32+
33+
### 1. 获取服务实例
34+
35+
```java
36+
// 获取WxPayService实例
37+
WxPayService wxPayService = new WxPayServiceImpl();
38+
wxPayService.setConfig(config);
39+
40+
// 获取新版转账服务 - 这就是新开通商户需要使用的服务！
41+
TransferService transferService = wxPayService.getTransferService();
42+
```
43+
44+
### 2. 发起转账（新版API）
45+
46+
```java
47+
// 构建转账请求
48+
TransferBillsRequest request = TransferBillsRequest.newBuilder()
49+
.appid("your_appid") // 应用ID
50+
.outBillNo("T" + System.currentTimeMillis()) // 商户转账单号
51+
.transferSceneId("1005") // 转账场景ID（佣金报酬）
52+
.openid("user_openid") // 用户openid
53+
.userName("张三") // 收款用户姓名（可选，自动加密）
54+
.transferAmount(100) // 转账金额（分）
55+
.transferRemark("佣金报酬") // 转账备注
56+
.build();
57+
58+
// 发起转账
59+
TransferBillsResult result = transferService.transferBills(request);
60+
System.out.println("转账成功，微信转账单号：" + result.getTransferBillNo());
61+
```
62+
63+
### 3. 查询转账结果
64+
65+
```java
66+
// 通过商户单号查询
67+
TransferBillsGetResult result = transferService.getBillsByOutBillNo("T1642567890123");
68+
69+
// 通过微信转账单号查询
70+
TransferBillsGetResult result2 = transferService.getBillsByTransferBillNo("wx_transfer_bill_no");
71+
72+
System.out.println("转账状态：" + result.getState());
73+
```
74+
75+
### 4. 撤销转账（新功能）
76+
77+
```java
78+
// 撤销转账
79+
TransferBillsCancelResult cancelResult = transferService.transformBillsCancel("T1642567890123");
80+
System.out.println("撤销状态：" + cancelResult.getState());
81+
```
82+
83+
## 重要说明
84+
85+
### 转账场景ID (transfer_scene_id)
86+
- **1005**: 佣金报酬（常用场景）
87+
- 其他场景需要在微信商户平台申请
88+
89+
### 转账状态说明
90+
- **ACCEPTED**: 转账已受理
91+
- **PROCESSING**: 转账处理中
92+
- **SUCCESS**: 转账成功
93+
- **FAIL**: 转账失败
94+
- **CANCELLED**: 转账撤销完成
95+
96+
### 新开通商户使用建议
97+
98+
1. **优先使用** `TransferService` （新版API）
99+
2. **不要使用** `MerchantTransferService` （可能不支持）
100+
3. **必须设置** 转账场景ID (`transfer_scene_id`)
101+
4. **建议开启** 回调通知以实时获取转账结果
102+
103+
## 完整示例代码
104+
105+
详细的使用示例请参考：
106+
- 📄 [NEW_TRANSFER_API_USAGE.md](./NEW_TRANSFER_API_USAGE.md) - 详细使用指南
107+
- 💻 [NewTransferApiExample.java](./weixin-java-pay/src/main/java/com/github/binarywang/wxpay/example/NewTransferApiExample.java) - 完整代码示例
108+
109+
## 常见问题
110+
111+
**Q: 我是新开通的商户，应该使用哪个服务？**
112+
A: 使用 `TransferService`，这是专为新版API设计的服务。
113+
114+
**Q: 新版API和旧版API有什么区别？**
115+
A: 新版API使用单笔转账模式，支持更丰富的转账场景，并且支持撤销功能。
116+
117+
**Q: 如何设置转账场景ID？**
118+
A: 在商户平台申请相应场景，常用的佣金报酬场景ID是"1005"。
119+
120+
**Q: 用户姓名需要加密吗？**
121+
A: WxJava会自动处理RSA加密，您只需要传入明文姓名即可。
122+
123+
## 版本要求
124+
125+
- WxJava 版本：4.7.0+
126+
- 支持时间：2025年1月15日+
127+
- 适用商户：所有商户（新开通商户强制使用）
128+
129+
通过以上说明，新开通的微信支付商户可以放心使用WxJava进行商户转账操作！

‎NEW_TRANSFER_API_USAGE.md

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
# 微信支付新版商户转账API使用指南
2+
3+
## 概述
4+
5+
从2025年1月15日开始，微信支付推出了新版的商户转账API。新开通的商户号只能使用最新版本的商户转账接口。WxJava 已经完整支持新版转账API。
6+
7+
## API对比
8+
9+
### 传统转账API (仍然支持)
10+
- **服务类**: `MerchantTransferService`
11+
- **API前缀**: `/v3/transfer/batches`
12+
- **特点**: 支持批量转账，一次可以转账给多个用户
13+
14+
### 新版转账API (2025.1.15+)
15+
- **服务类**: `TransferService`
16+
- **API前缀**: `/v3/fund-app/mch-transfer/transfer-bills`
17+
- **特点**: 单笔转账，支持更丰富的转账场景
18+
19+
## 使用新版转账API
20+
21+
### 1. 获取服务实例
22+
23+
```java
24+
// 获取WxPayService实例
25+
WxPayService wxPayService = new WxPayServiceImpl();
26+
wxPayService.setConfig(config);
27+
28+
// 获取新版转账服务
29+
TransferService transferService = wxPayService.getTransferService();
30+
```
31+
32+
### 2. 发起转账
33+
34+
```java
35+
// 构建转账请求
36+
TransferBillsRequest request = TransferBillsRequest.newBuilder()
37+
.appid("your_appid") // 应用ID
38+
.outBillNo("T" + System.currentTimeMillis()) // 商户转账单号
39+
.transferSceneId("1005") // 转账场景ID（佣金报酬）
40+
.openid("user_openid") // 用户openid
41+
.userName("张三") // 收款用户姓名（可选，需要加密）
42+
.transferAmount(100) // 转账金额（分）
43+
.transferRemark("佣金报酬") // 转账备注
44+
.notifyUrl("https://your-domain.com/notify") // 回调地址（可选）
45+
.userRecvPerception("Y") // 用户收款感知（可选）
46+
.build();
47+
48+
try {
49+
TransferBillsResult result = transferService.transferBills(request);
50+
System.out.println("转账成功，微信转账单号：" + result.getTransferBillNo());
51+
System.out.println("状态：" + result.getState());
52+
} catch (WxPayException e) {
53+
System.err.println("转账失败：" + e.getMessage());
54+
}
55+
```
56+
57+
### 3. 查询转账结果
58+
59+
```java
60+
// 通过商户单号查询
61+
String outBillNo = "T1642567890123";
62+
TransferBillsGetResult result = transferService.getBillsByOutBillNo(outBillNo);
63+
64+
// 通过微信转账单号查询
65+
String transferBillNo = "1000000000000000000000000001";
66+
TransferBillsGetResult result2 = transferService.getBillsByTransferBillNo(transferBillNo);
67+
68+
System.out.println("转账状态：" + result.getState());
69+
System.out.println("转账金额：" + result.getTransferAmount());
70+
```
71+
72+
### 4. 撤销转账
73+
74+
```java
75+
// 撤销转账（仅在特定状态下可撤销）
76+
String outBillNo = "T1642567890123";
77+
TransferBillsCancelResult cancelResult = transferService.transformBillsCancel(outBillNo);
78+
System.out.println("撤销结果：" + cancelResult.getState());
79+
```
80+
81+
### 5. 处理回调通知
82+
83+
```java
84+
// 在回调接口中处理通知
85+
@PostMapping("/transfer/notify")
86+
public String handleTransferNotify(HttpServletRequest request) throws Exception {
87+
String notifyData = StreamUtils.copyToString(request.getInputStream(), StandardCharsets.UTF_8);
88+
89+
// 构建签名头
90+
SignatureHeader header = new SignatureHeader();
91+
header.setTimeStamp(request.getHeader("Wechatpay-Timestamp"));
92+
header.setNonce(request.getHeader("Wechatpay-Nonce"));
93+
header.setSignature(request.getHeader("Wechatpay-Signature"));
94+
header.setSerial(request.getHeader("Wechatpay-Serial"));
95+
96+
try {
97+
TransferBillsNotifyResult notifyResult = transferService.parseTransferBillsNotifyResult(notifyData, header);
98+
99+
// 处理业务逻辑
100+
String outBillNo = notifyResult.getOutBillNo();
101+
String state = notifyResult.getState();
102+
103+
System.out.println("转账单号：" + outBillNo + "，状态：" + state);
104+
105+
return "SUCCESS";
106+
} catch (WxPayException e) {
107+
System.err.println("验签失败：" + e.getMessage());
108+
return "FAIL";
109+
}
110+
}
111+
```
112+
113+
## 重要参数说明
114+
115+
### 转账场景ID (transfer_scene_id)
116+
- **1005**: 佣金报酬（常用）
117+
- 其他场景ID需要在商户平台申请
118+
119+
### 转账状态
120+
- **PROCESSING**: 转账中
121+
- **SUCCESS**: 转账成功
122+
- **FAILED**: 转账失败
123+
- **REFUNDED**: 已退款
124+
125+
### 用户收款感知 (user_recv_perception)
126+
- **Y**: 用户会收到微信转账通知
127+
- **N**: 用户不会收到微信转账通知
128+
129+
## 新旧API对比总结
130+
131+
| 特性 | 传统API (MerchantTransferService) | 新版API (TransferService) |
132+
|------|----------------------------------|---------------------------|
133+
| 发起方式 | 批量转账 | 单笔转账 |
134+
| API路径 | `/v3/transfer/batches` | `/v3/fund-app/mch-transfer/transfer-bills` |
135+
| 场景支持 | 基础转账场景 | 丰富的转账场景 |
136+
| 回调通知 | 支持 | 支持 |
137+
| 撤销功能 | 不支持 | 支持 |
138+
| 适用商户 | 所有商户 | 新开通商户必须使用 |
139+
140+
## 注意事项
141+
142+
1. **新开通的商户号**: 必须使用新版API (`TransferService`)
143+
2. **转账场景ID**: 需要在商户平台申请相应的转账场景
144+
3. **用户姓名加密**: 如果传入用户姓名，会自动进行RSA加密
145+
4. **回调验签**: 建议开启回调验签以确保安全性
146+
5. **错误处理**: 妥善处理各种异常情况
147+
148+
通过以上指南，您可以轻松使用WxJava的新版商户转账API功能。

0 commit comments

Comments
 (0)