🆕 #3717 【微信支付】商户转账新增免确认收款授权模式支持

2026-02-07 19:27:50 +08:00 · 2025-12-21 17:49:11 +08:00
parent 621b8dc0e4
commit b0d9c6cc76
5 changed files with 268 additions and 4 deletions
--- a/docs/NEW_TRANSFER_API_SUPPORT.md
+++ b/docs/NEW_TRANSFER_API_SUPPORT.md
@@ -17,6 +17,7 @@
 | **转账方式** | 批量转账 | 单笔转账 |
 | **场景支持** | 基础场景 | 丰富场景（如佣金报酬等） |
 | **撤销功能** | ❌ 不支持 | ✅ 支持 |
+| **授权模式** | 仅需确认模式 | ✅ 支持免确认授权模式 |
 | **适用范围** | 所有商户 | **新开通商户必须使用** |

 ### 2. 新版API功能列表
@@ -27,6 +28,30 @@
 ✅ **回调通知** - `parseTransferBillsNotifyResult()`
 ✅ **RSA加密** - 自动处理用户姓名加密
 ✅ **场景支持** - 支持多种转账场景ID
+✅ **授权模式** - 支持免确认收款授权模式
+
+### 3. 收款授权模式支持
+
+**新增功能：免确认收款授权模式**
+
+- **需确认收款授权模式**（默认）：用户需要手动确认才能收款
+- **免确认收款授权模式**：用户授权后，收款无需确认，转账直接到账
+
+#### 使用方法
+
+```java
+// 免确认授权模式 - 提升用户体验
+TransferBillsRequest request = TransferBillsRequest.newBuilder()
+    .receiptAuthorizationMode(WxPayConstants.ReceiptAuthorizationMode.NO_CONFIRM_RECEIPT_AUTHORIZATION)
+    // 其他参数...
+    .build();
+
+// 需确认授权模式（默认）
+TransferBillsRequest request2 = TransferBillsRequest.newBuilder()
+    .receiptAuthorizationMode(WxPayConstants.ReceiptAuthorizationMode.CONFIRM_RECEIPT_AUTHORIZATION)
+    // 其他参数...
+    .build();
+```

 ## 快速开始

--- a/docs/NEW_TRANSFER_API_USAGE.md
+++ b/docs/NEW_TRANSFER_API_USAGE.md
@@ -16,6 +16,100 @@
 - **API前缀**: `/v3/fund-app/mch-transfer/transfer-bills`
 - **特点**: 单笔转账，支持更丰富的转账场景

+## 收款授权模式功能
+
+### 授权模式说明
+
+微信支付转账支持两种收款授权模式：
+
+#### 1. 需确认收款授权模式（默认）
+- **常量**: `WxPayConstants.ReceiptAuthorizationMode.CONFIRM_RECEIPT_AUTHORIZATION`
+- **特点**: 用户收到转账后需要手动点击确认才能到账
+- **适用场景**: 一般的转账场景
+- **用户体验**: 安全性高，但需要额外操作
+
+#### 2. 免确认收款授权模式  
+- **常量**: `WxPayConstants.ReceiptAuthorizationMode.NO_CONFIRM_RECEIPT_AUTHORIZATION`
+- **特点**: 用户事先授权后，转账直接到账，无需确认
+- **适用场景**: 高频转账场景，如佣金发放、返现等
+- **用户体验**: 体验流畅，无需额外操作
+- **前提条件**: 需要用户事先进行授权
+
+### 使用示例
+
+#### 免确认授权模式转账
+
+```java
+TransferBillsRequest 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("用户未授权免确认收款，请先引导用户进行授权");
+    }
+}
+```
+
+#### 需确认授权模式转账（默认）
+
+```java
+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());
+```
+
+### 错误处理
+
+使用免确认授权模式时，需要处理以下可能的错误：
+
+```java
+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());
+    }
+}
+```
+
+### 使用建议
+
+1. **高频转账场景**推荐使用免确认模式，提升用户体验
+2. **首次使用**需引导用户进行授权
+3. **处理异常**妥善处理授权相关异常，提供友好的错误提示
+4. **场景选择**根据业务场景选择合适的授权模式
+
 ## 使用新版转账API

 ### 1. 获取服务实例