:new: 【微信支付】平台收付通（退款）增加垫付退款回补和查询垫付回补结果的接口

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/ecommerce/RefundNotifyResult.java

@@ -170,6 +170,25 @@ public class RefundNotifyResult implements Serializable {
   @SerializedName(value = "amount")
   private Amount amount;
 
+  /**
+   * <pre>
+   * 字段名：退款出资商户
+   * 变量名：refund_account
+   * 是否必填：否
+   * 类型：string（32）
+   * 描述：
+   *   电商平台垫资退款专用参数。需先确认已开通此功能后，才能使用。若需要开通，请联系微信支付客服。
+   *   枚举值：
+   *   REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付，需要向微信支付申请开通
+   *   REFUND_SOURCE_SUB_MERCHANT : 二级商户，默认值
+   *   注意：
+   *   若传入REFUND_SOURCE_PARTNER_ADVANCE，仅代表可以使用垫付退款，实际出款账户需以退款申请受理结果或查单结果为准。
+   *   示例值：REFUND_SOURCE_SUB_MERCHANT
+   * </pre>
+   */
+  @SerializedName(value = "refund_account")
+  private String refundAccount;
+
   @Data
   @NoArgsConstructor
   public static class Amount implements Serializable {

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/ecommerce/RefundQueryResult.java

@@ -183,6 +183,44 @@ public class RefundQueryResult implements Serializable {
    */
   public List<PromotionDetail> promotionDetails;
 
+
+  /**
+   * <pre>
+   * 字段名：退款出资商户
+   * 变量名：refund_account
+   * 是否必填：否
+   * 类型：string（32）
+   * 描述：
+   *   电商平台垫资退款专用参数。需先确认已开通此功能后，才能使用。若需要开通，请联系微信支付客服。
+   *   枚举值：
+   *   REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付，需要向微信支付申请开通
+   *   REFUND_SOURCE_SUB_MERCHANT : 二级商户，默认值
+   *   注意：
+   *   若传入REFUND_SOURCE_PARTNER_ADVANCE，仅代表可以使用垫付退款，实际出款账户需以退款申请受理结果或查单结果为准。
+   *   示例值：REFUND_SOURCE_SUB_MERCHANT
+   * </pre>
+   */
+  @SerializedName(value = "refund_account")
+  private String refundAccount;
+
+  /**
+   * <pre>
+   * 字段名：资金账户
+   * 变量名：funds_account
+   * 是否必填：否
+   * 类型：string（32）
+   * 描述：
+   *   若订单处于待分账状态，且未指定垫资退款（即refund_account未指定为REFUND_SOURCE_PARTNER_ADVANCE），
+   *   可以传入此参数，指定退款资金来源账户。当该字段不存在时，默认使用订单交易资金所在账户出款，
+   *   即待分账时使用不可用余额的资金进行退款，已分账或无分账时使用可用余额的资金进行退款。 AVAILABLE：可用余额
+   * 示例值：AVAILABLE
+   * </pre>
+   */
+  @SerializedName(value = "funds_account")
+  private String fundsAccount;
+
+
+
   @Data
   @NoArgsConstructor
   public static class Amount implements Serializable {

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/ecommerce/RefundsRequest.java

@@ -147,6 +147,41 @@ public class RefundsRequest implements Serializable {
   @SerializedName(value = "notify_url")
   private String notifyUrl;
 
+  /**
+   * <pre>
+   * 字段名：退款出资商户
+   * 变量名：refund_account
+   * 是否必填：否
+   * 类型：string（32）
+   * 描述：
+   *   电商平台垫资退款专用参数。需先确认已开通此功能后，才能使用。若需要开通，请联系微信支付客服。
+   *   枚举值：
+   *   REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付，需要向微信支付申请开通
+   *   REFUND_SOURCE_SUB_MERCHANT : 二级商户，默认值
+   *   注意：
+   *   若传入REFUND_SOURCE_PARTNER_ADVANCE，仅代表可以使用垫付退款，实际出款账户需以退款申请受理结果或查单结果为准。
+   *   示例值：REFUND_SOURCE_SUB_MERCHANT
+   * </pre>
+   */
+  @SerializedName(value = "refund_account")
+  private String refundAccount;
+
+  /**
+   * <pre>
+   * 字段名：资金账户
+   * 变量名：funds_account
+   * 是否必填：否
+   * 类型：string（32）
+   * 描述：
+   *   若订单处于待分账状态，且未指定垫资退款（即refund_account未指定为REFUND_SOURCE_PARTNER_ADVANCE），
+   *   可以传入此参数，指定退款资金来源账户。当该字段不存在时，默认使用订单交易资金所在账户出款，
+   *   即待分账时使用不可用余额的资金进行退款，已分账或无分账时使用可用余额的资金进行退款。 AVAILABLE：可用余额
+   * 示例值：AVAILABLE
+   * </pre>
+   */
+  @SerializedName(value = "funds_account")
+  private String fundsAccount;
+
   @Data
   @Builder
   @NoArgsConstructor(access = AccessLevel.PRIVATE)

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/ecommerce/RefundsResult.java

@@ -240,4 +240,22 @@ public class RefundsResult implements Serializable {
 
   }
 
+
+  /**
+   * <pre>
+   * 字段名：退款资金来源
+   * 变量名：refund_account
+   * 是否必填：否
+   * 类型：string（32）
+   * 描述：
+   *   枚举值：
+   * REFUND_SOURCE_PARTNER_ADVANCE : 电商平台垫付
+   * REFUND_SOURCE_SUB_MERCHANT : 二级商户，默认值
+   * 示例值：REFUND_SOURCE_SUB_MERCHANT
+   * </pre>
+   */
+  @SerializedName(value = "refund_account")
+  private String refundAccount;
+
+
 }

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/bean/ecommerce/ReturnAdvanceResult.java

@@ -0,0 +1,159 @@
+package com.github.binarywang.wxpay.bean.ecommerce;
+
+import com.google.gson.annotations.SerializedName;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+import java.io.Serializable;
+import java.util.List;
+
+
+/**
+ * 垫付退款回补API结果
+ * * <pre>
+ *  *   文档地址：https://pay.weixin.qq.com/wiki/doc/apiv3_partner/apis/chapter7_6_4.shtml
+ *  * </pre>
+ *
+ * @author yantao
+ * created on  2024/11/20
+ */
+@Data
+@NoArgsConstructor
+public class ReturnAdvanceResult implements Serializable {
+
+  private static final long serialVersionUID = -186851559004865784L;
+
+  /**
+   * <pre>
+   * 字段名：微信退款单号
+   * 变量名：refund_id
+   * 是否必填：是
+   * 类型：string（32）
+   * 描述：
+   * 微信支付退款单的主键，唯一定义此资源的标识。 必须是垫付退款的微信支付退款单
+   * 示例值：50000000382019052709732678859
+   * </pre>
+   */
+  @SerializedName(value = "refund_id")
+  private String refundId;
+
+  /**
+   * <pre>
+   * 字段名：微信回补单号
+   * 变量名：advance_return_id
+   * 是否必填：是
+   * 类型：string（32）
+   * 描述：微信支付生成的垫付回补操作单号
+   * 示例值：1215562501201407033233368018
+   * </pre>
+   */
+  @SerializedName(value = "advance_return_id")
+  private String advanceReturnId	;
+
+  /**
+   * <pre>
+   * 字段名：垫付回补金额
+   * 变量名：return_amount
+   * 是否必填：是
+   * 类型：int
+   * 描述：退款单对应的垫付退款的金额
+   * 示例值：888
+   * </pre>
+   */
+  @SerializedName(value = "return_amount")
+  private Integer returnAmount	;
+
+  /**
+   * <pre>
+   * 字段名：出款方商户号
+   * 变量名：payer_mchid
+   * 是否必填：是
+   * 类型：string（32）
+   * 描述：微信支付分配给出款方的商户号
+   * 示例值：1900000109
+   * </pre>
+   */
+  @SerializedName(value = "payer_mchid")
+  private String  payerMchid ;
+
+  /**
+   * <pre>
+   * 字段名：出款方账户
+   * 变量名：payer_account
+   * 是否必填：是
+   * 类型：string（32）
+   * 描述：
+   * 枚举值：
+   * BASIC：基本账户
+   * OPERATION：运营账户
+   * 示例值：BASIC
+   * </pre>
+   */
+  @SerializedName(value = "payer_account")
+  private String payerAccount;
+
+  /**
+   * <pre>
+   * 字段名：入账方商户号
+   * 变量名：payee_mchid
+   * 是否必填：是
+   * 类型：string（32）
+   * 描述：
+   * 微信支付分配给入账方的商户号
+   * 示例值：1900000108
+   * </pre>
+   */
+  @SerializedName(value = "payee_mchid")
+  private String payeeMchid;
+
+  /**
+   * <pre>
+   * 字段名：入账方账户
+   * 变量名：payee_account
+   * 是否必填：是
+   * 类型：string（32）
+   * 描述：枚举值：
+   * BASIC：基本账户
+   * OPERATION：运营账户
+   * 示例值：BASIC
+   * </pre>
+   */
+  @SerializedName(value = "payee_account")
+  private String payeeAccount;
+
+  /**
+   * <pre>
+   * 字段名：垫付回补结果
+   * 变量名：result
+   * 是否必填：是
+   * 类型：string（32）
+   * 描述：枚举值：
+   * SUCCESS：回补成功
+   * FAILED：回补失败，出款方账户余额不足时发生
+   * PROCESSING：处理中
+   * 示例值：SUCCESS
+   * </pre>
+   */
+  @SerializedName(value = "result")
+  private String result	;
+
+  /**
+   * <pre>
+   * 字段名：垫付回补完成时间
+   * 变量名：success_time
+   * 是否必填：否
+   * 类型：string（64）
+   * 描述：垫付回补完成的时间，遵循rfc3339标准格式，
+   * 格式为yyyy-MM-DDTHH:mm:ss+TIMEZONE，yyyy-MM-DD表示年月日，
+   * T出现在字符串中，表示time元素的开头，HH:mm:ss表示时分秒，
+   * TIMEZONE表示时区（+08:00表示东八区时间，领先UTC 8小时，即北京时间）。
+   * 例如：2015-05-20T13:29:35+08:00表示北京时间2015年05月20日13点29分35秒。
+   * 示例值：2018-06-08T10:34:56+08:00
+   * </pre>
+   */
+  @SerializedName(value = "success_time")
+  private String successTime;
+
+
+
+}

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/service/EcommerceService.java

@@ -364,6 +364,33 @@ public interface EcommerceService {
    */
   RefundQueryResult queryRefundByRefundId(String subMchid, String refundId) throws WxPayException;
 
+
+  /**
+   * <pre>
+   * 垫付退款回补API
+   * 文档地址: https://pay.weixin.qq.com/wiki/doc/apiv3_partner/apis/chapter7_6_4.shtml
+   * </pre>
+   *
+   * @param subMchid 二级商户号
+   * @param refundId 微信退款单号
+   * @return 返回数据 return refunds result
+   * @throws WxPayException the wx pay exception
+   */
+  ReturnAdvanceResult refundsReturnAdvance(String subMchid, String refundId) throws WxPayException;
+
+
+  /**
+   * <pre>
+   * 查询垫付回补结果API
+   * 文档地址: https://pay.weixin.qq.com/wiki/doc/apiv3_partner/apis/chapter7_6_5.shtml
+   * </pre>
+   *
+   * @param subMchid 二级商户号
+   * @param refundId 微信退款单号
+   * @return 返回数据 return refunds result
+   * @throws WxPayException the wx pay exception
+   */
+  ReturnAdvanceResult queryRefundsReturnAdvance(String subMchid, String refundId) throws WxPayException;
   /**
    * <pre>
    * 查询退款API

weixin-java-pay/src/main/java/com/github/binarywang/wxpay/service/impl/EcommerceServiceImpl.java

@@ -290,6 +290,25 @@ public class EcommerceServiceImpl implements EcommerceService {
     return GSON.fromJson(response, RefundQueryResult.class);
   }
 
+
+  @Override
+  public ReturnAdvanceResult refundsReturnAdvance(String subMchid, String refundId) throws WxPayException {
+    String url = String.format("%s/v3/ecommerce/refunds/%s/return-advance", this.payService.getPayBaseUrl(), refundId);
+    Map request = new HashMap();
+    request.put("sub_mchid",subMchid);
+    String response = this.payService.postV3(url, GSON.toJson(request));
+    return GSON.fromJson(response, ReturnAdvanceResult.class);
+  }
+
+
+  @Override
+  public ReturnAdvanceResult queryRefundsReturnAdvance(String subMchid, String refundId) throws WxPayException {
+    String url = String.format("%s/v3/ecommerce/refunds/%s/return-advance?sub_mchid=%s", this.payService.getPayBaseUrl(), refundId,subMchid);
+    String response = this.payService.getV3(url);
+    return GSON.fromJson(response, ReturnAdvanceResult.class);
+  }
+
+
   @Override
   public RefundQueryResult queryRefundByOutRefundNo(String subMchid, String outRefundNo) throws WxPayException {
     String url = String.format("%s/v3/ecommerce/refunds/out-refund-no/%s?sub_mchid=%s", this.payService.getPayBaseUrl(), outRefundNo, subMchid);