🆕 #3828 【微信支付】更新商家转账 API 的请求和响应字段，同步官方文档的字段调整，新增转账场景报备信息

Author: HeCG95

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/transfer/BusinessOperationTransferRequest.java

@@ -6,8 +6,10 @@
 import lombok.Builder;
 import lombok.Data;
 import lombok.NoArgsConstructor;
+import lombok.experimental.Accessors;
 
 import java.io.Serializable;
+import java.util.List;
 
 /**
  * 运营工具-商家转账请求参数
@@ -37,11 +39,11 @@ public class BusinessOperationTransferRequest implements Serializable {
   private String outBillNo;
 
   /**
-   * 运营工具转账场景ID
-   * 必须，用于标识运营工具转账的具体业务场景
+   * 转账场景ID
+   * 必须，该笔转账使用的转账场景，可前往“商户平台-产品中心-商家转账”中申请。如：1000（现金营销），1006（企业报销）等
    */
-  @SerializedName("operation_scene_id")
-  private String operationSceneId;
+  @SerializedName("transfer_scene_id")
+  private String transferSceneId;
 
   /**
    * 用户在直连商户应用下的用户标示
@@ -86,4 +88,36 @@ public class BusinessOperationTransferRequest implements Serializable {
    */
   @SerializedName("notify_url")
   private String notifyUrl;
-}
+
+  /**
+   * 转账场景报备信息
+   * 必须，需按转账场景准确填写报备信息，参考 <a href="https://pay.weixin.qq.com/doc/v3/merchant/4013774588">转账场景报备信息字段说明</a>
+   */
+  @SerializedName("transfer_scene_report_infos")
+  private List<TransferSceneReportInfo> transferSceneReportInfos;
+
+  /**
+   * 转账场景报备信息
+   */
+  @Data
+  @Accessors(chain = true)
+  public static class TransferSceneReportInfo implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 信息类型
+     * 必须，不能超过15个字符，商户所属转账场景下的信息类型，此字段内容为固定值，需严格按照 <a href="https://pay.weixin.qq.com/doc/v3/merchant/4013774588">转账场景报备信息字段说明</a> 传参。
+     */
+    @SerializedName("info_type")
+    private String infoType;
+
+    /**
+     * 信息内容
+     * 必须，不能超过32个字符，商户所属转账场景下的信息内容，商户可按实际业务场景自定义传参，需严格按照 <a href="https://pay.weixin.qq.com/doc/v3/merchant/4013774588">转账场景报备信息字段说明</a> 传参。
+     */
+    @SerializedName("info_content")
+    private String infoContent;
+
+  }
+
+}

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/transfer/BusinessOperationTransferResult.java

@@ -31,15 +31,27 @@ public class BusinessOperationTransferResult implements Serializable {
   private String transferBillNo;
 
   /**
-   * 转账状态
-   * WAIT_PAY：等待确认
-   * PROCESSING：转账中
-   * SUCCESS：转账成功
-   * FAIL：转账失败
-   * REFUND：已退款
+   * 单据状态
+   * 商家转账订单状态
+   * ACCEPTED：转账已受理，可原单重试（非终态）。
+   * PROCESSING: 转账锁定资金中。如果一直停留在该状态，建议检查账户余额是否足够，如余额不足，可充值后再原单重试（非终态）。
+   * WAIT_USER_CONFIRM:  待收款用户确认，当前转账单据资金已锁定，可拉起微信收款确认页面进行收款确认（非终态）。
+   * TRANSFERING:  转账中，可拉起微信收款确认页面再次重试确认收款（非终态）。
+   * SUCCESS:  转账成功，表示转账单据已成功（终态）。
+   * FAIL:  转账失败，表示该笔转账单据已失败。若需重新向用户转账，请重新生成单据并再次发起（终态）。
+   * CANCELING:  转账撤销中，商户撤销请求受理成功，该笔转账正在撤销中，需查单确认撤销的转账单据状态（非终态）。
+   * CANCELLED:  转账撤销完成，代表转账单据已撤销成功（终态）。
    */
-  @SerializedName("transfer_state")
-  private String transferState;
+  @SerializedName("state")
+  private String state;
+
+  /**
+   * 跳转领取页面的package信息
+   * 跳转微信支付收款页的package信息， <a href="https://pay.weixin.qq.com/doc/v3/merchant/4012719576">APP调起用户确认收款</a> 或者 <a href="https://pay.weixin.qq.com/doc/v3/merchant/4012716430">JSAPI调起用户确认收款</a> 时需要使用的参数。仅当转账单据状态为WAIT_USER_CONFIRM时返回。<br>
+   * 单据创建后，用户24小时内不领取将过期关闭，建议拉起用户确认收款页面前，先查单据状态：如单据状态为WAIT_USER_CONFIRM，可用之前的package信息拉起；单据到终态时需更换单号重新发起转账。
+   */
+  @SerializedName("package_info")
+  private String packageInfo;
 
   /**
    * 发起转账的时间

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/example/BusinessOperationTransferExample.java

@@ -8,6 +8,8 @@
 import com.github.binarywang.wxpay.service.WxPayService;
 import com.github.binarywang.wxpay.service.impl.WxPayServiceImpl;
 
+import java.util.Arrays;
+
 /**
  * 运营工具-商家转账API使用示例
  * 
@@ -41,10 +43,15 @@ public void init() {
   public void createOperationTransferExample() {
     try {
       // 构建转账请求
+      BusinessOperationTransferRequest.TransferSceneReportInfo reportInfo = new BusinessOperationTransferRequest.TransferSceneReportInfo();
+      reportInfo.setInfoType("活动名称");
+      reportInfo.setInfoContent("新会员有礼");
+
       BusinessOperationTransferRequest request = BusinessOperationTransferRequest.newBuilder()
         .appid("your_app_id")                                    // 应用ID
         .outBillNo("OT" + System.currentTimeMillis())           // 商户转账单号
-        .operationSceneId(WxPayConstants.OperationSceneId.OPERATION_CASH_MARKETING) // 运营工具转账场景ID
+        .transferSceneId(WxPayConstants.OperationSceneId.OPERATION_CASH_MARKETING) // 运营工具转账场景ID
+        .transferSceneReportInfos(Arrays.asList(reportInfo)) // 转账场景报备信息
         .openid("user_openid")                                   // 用户openid
         .userName("张三")                                          // 用户姓名（可选）
         .transferAmount(100)                                     // 转账金额，单位分
@@ -59,7 +66,8 @@ public void createOperationTransferExample() {
       System.out.println("转账成功！");
       System.out.println("商户单号: " + result.getOutBillNo());
       System.out.println("微信转账单号: " + result.getTransferBillNo());
-      System.out.println("转账状态: " + result.getTransferState());
+      System.out.println("单据状态: " + result.getState());
+      System.out.println("跳转领取页面的package信息: " + result.getPackageInfo());
       System.out.println("创建时间: " + result.getCreateTime());
 
     } catch (WxPayException e) {

weixin-java-pay/src/test/java/com/github/binarywang/wxpay/service/BusinessOperationTransferServiceTest.java

@@ -7,6 +7,8 @@
 import org.testng.annotations.BeforeClass;
 import org.testng.annotations.Test;
 
+import java.util.Arrays;
+
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
@@ -36,18 +38,25 @@ public void testServiceInitialization() {
 
   @Test
   public void testRequestBuilder() {
+
+    // 构建转账请求
+    BusinessOperationTransferRequest.TransferSceneReportInfo reportInfo = new BusinessOperationTransferRequest.TransferSceneReportInfo();
+    reportInfo.setInfoType("test_info_type");
+    reportInfo.setInfoContent("test_info_content");
+
     BusinessOperationTransferRequest request = BusinessOperationTransferRequest.newBuilder()
       .appid("test_app_id")
       .outBillNo("OT" + System.currentTimeMillis())
-      .operationSceneId(WxPayConstants.OperationSceneId.OPERATION_CASH_MARKETING)
+      .transferSceneId(WxPayConstants.OperationSceneId.OPERATION_CASH_MARKETING)
+      .transferSceneReportInfos(Arrays.asList(reportInfo))
       .openid("test_openid")
       .transferAmount(100)
       .transferRemark("测试转账")
       .userRecvPerception(WxPayConstants.UserRecvPerception.CASH_MARKETING.CASH)
       .build();
 
     assertThat(request.getAppid()).isEqualTo("test_app_id");
-    assertThat(request.getOperationSceneId()).isEqualTo(WxPayConstants.OperationSceneId.OPERATION_CASH_MARKETING);
+    assertThat(request.getTransferSceneId()).isEqualTo(WxPayConstants.OperationSceneId.OPERATION_CASH_MARKETING);
     assertThat(request.getTransferAmount()).isEqualTo(100);
     assertThat(request.getTransferRemark()).isEqualTo("测试转账");
   }
@@ -77,11 +86,13 @@ public void testResultClasses() {
     BusinessOperationTransferResult result = new BusinessOperationTransferResult();
     result.setOutBillNo("test_out_bill_no");
     result.setTransferBillNo("test_transfer_bill_no");
-    result.setTransferState("SUCCESS");
+    result.setState("SUCCESS");
+    result.setPackageInfo("test_package_info");
 
     assertThat(result.getOutBillNo()).isEqualTo("test_out_bill_no");
     assertThat(result.getTransferBillNo()).isEqualTo("test_transfer_bill_no");
-    assertThat(result.getTransferState()).isEqualTo("SUCCESS");
+    assertThat(result.getState()).isEqualTo("SUCCESS");
+    assertThat(result.getPackageInfo()).isEqualTo("test_package_info");
 
     BusinessOperationTransferQueryResult queryResult = new BusinessOperationTransferQueryResult();
     queryResult.setOperationSceneId("2001");