WxJava/weixin-java-pay/SUBSCRIPTION_BILLING_USAGE.md

微信支付预约扣费功能使用说明

概述

微信支付预约扣费功能（连续包月功能）允许商户在用户授权的情况下，按照约定的时间和金额，自动从用户的支付账户中扣取费用。主要适用于连续包月、订阅服务等场景。

功能特性

• 预约扣费：创建未来某个时间点的扣费计划
• 查询预约：查询已创建的扣费计划状态
• 取消预约：取消已创建的扣费计划
• 立即扣费：立即执行扣费操作
• 扣费记录查询：查询历史扣费记录

快速开始

1. 获取服务实例

// 通过 WxPayService 获取预约扣费服务
SubscriptionBillingService subscriptionService = wxPayService.getSubscriptionBillingService();

2. 创建预约扣费

// 创建预约扣费请求
SubscriptionScheduleRequest request = new SubscriptionScheduleRequest();
request.setOutTradeNo("subscription_" + System.currentTimeMillis());
request.setOpenid("用户的openid");
request.setDescription("腾讯视频VIP会员");
request.setScheduleTime("2024-09-01T10:00:00+08:00");

// 设置扣费金额
SubscriptionAmount amount = new SubscriptionAmount();
amount.setTotal(3000); // 30元，单位为分
amount.setCurrency("CNY");
request.setAmount(amount);

// 设置扣费计划（可选）
BillingPlan billingPlan = new BillingPlan();
billingPlan.setPlanType("MONTHLY"); // 按月扣费
billingPlan.setPeriod(1); // 每1个月
billingPlan.setTotalCount(12); // 总共12次
request.setBillingPlan(billingPlan);

// 发起预约扣费
SubscriptionScheduleResult result = subscriptionService.scheduleSubscription(request);
System.out.println("预约扣费ID: " + result.getSubscriptionId());

3. 查询预约扣费

// 通过预约扣费ID查询
String subscriptionId = "从预约扣费结果中获取的ID";
SubscriptionQueryResult queryResult = subscriptionService.querySubscription(subscriptionId);
System.out.println("预约状态: " + queryResult.getStatus());

4. 取消预约扣费

// 创建取消请求
SubscriptionCancelRequest cancelRequest = new SubscriptionCancelRequest();
cancelRequest.setSubscriptionId(subscriptionId);
cancelRequest.setCancelReason("用户主动取消");

// 取消预约扣费
SubscriptionCancelResult cancelResult = subscriptionService.cancelSubscription(cancelRequest);
System.out.println("取消结果: " + cancelResult.getStatus());

5. 立即扣费

// 创建立即扣费请求
SubscriptionInstantBillingRequest instantRequest = new SubscriptionInstantBillingRequest();
instantRequest.setOutTradeNo("instant_" + System.currentTimeMillis());
instantRequest.setOpenid("用户的openid");
instantRequest.setDescription("补扣上月会员费");

// 设置扣费金额
SubscriptionAmount instantAmount = new SubscriptionAmount();
instantAmount.setTotal(3000); // 30元
instantAmount.setCurrency("CNY");
instantRequest.setAmount(instantAmount);

// 执行立即扣费
SubscriptionInstantBillingResult instantResult = subscriptionService.instantBilling(instantRequest);
System.out.println("扣费结果: " + instantResult.getTradeState());

6. 查询扣费记录

// 创建查询请求
SubscriptionTransactionQueryRequest queryRequest = new SubscriptionTransactionQueryRequest();
queryRequest.setOpenid("用户的openid");
queryRequest.setBeginTime("2024-08-01T00:00:00+08:00");
queryRequest.setEndTime("2024-08-31T23:59:59+08:00");
queryRequest.setLimit(20);
queryRequest.setOffset(0);

// 查询扣费记录
SubscriptionTransactionQueryResult transactionResult = subscriptionService.queryTransactions(queryRequest);
System.out.println("总记录数: " + transactionResult.getTotalCount());
for (SubscriptionTransactionQueryResult.SubscriptionTransaction transaction : transactionResult.getData()) {
    System.out.println("订单号: " + transaction.getOutTradeNo() + ", 状态: " + transaction.getTradeState());
}

扣费计划类型

• MONTHLY：按月扣费
• WEEKLY：按周扣费
• DAILY：按日扣费
• YEARLY：按年扣费

预约状态说明

• SCHEDULED：已预约
• CANCELLED：已取消
• EXECUTED：已执行
• FAILED：执行失败

交易状态说明

• SUCCESS：支付成功
• REFUND：转入退款
• NOTPAY：未支付
• CLOSED：已关闭
• REVOKED：已撤销(刷卡支付)
• USERPAYING：用户支付中
• PAYERROR：支付失败

注意事项

1. 用户授权：使用预约扣费功能前，需要用户在微信内完成签约授权
2. 商户资质：需要具备相应的业务资质才能开通此功能
3. 金额限制：扣费金额需要在签约模板规定的范围内
4. 频率限制：API调用有频率限制，请注意控制调用频次
5. 异常处理：建议对所有API调用进行异常处理

相关文档

• 微信支付预约扣费API文档
• 微信支付开发指南

示例完整代码

import com.github.binarywang.wxpay.service.SubscriptionBillingService;
import com.github.binarywang.wxpay.bean.subscriptionbilling.*;

public class SubscriptionBillingExample {
    
    private SubscriptionBillingService subscriptionService;
    
    public void example() throws Exception {
        // 1. 创建预约扣费
        SubscriptionScheduleRequest request = new SubscriptionScheduleRequest();
        request.setOutTradeNo("subscription_" + System.currentTimeMillis());
        request.setOpenid("用户openid");
        request.setDescription("VIP会员续费");
        request.setScheduleTime("2024-09-01T10:00:00+08:00");
        
        SubscriptionAmount amount = new SubscriptionAmount();
        amount.setTotal(3000);
        amount.setCurrency("CNY");
        request.setAmount(amount);
        
        BillingPlan plan = new BillingPlan();
        plan.setPlanType("MONTHLY");
        plan.setPeriod(1);
        plan.setTotalCount(12);
        request.setBillingPlan(plan);
        
        SubscriptionScheduleResult result = subscriptionService.scheduleSubscription(request);
        
        // 2. 查询预约状态
        SubscriptionQueryResult query = subscriptionService.querySubscription(result.getSubscriptionId());
        
        // 3. 如需取消
        if ("SCHEDULED".equals(query.getStatus())) {
            SubscriptionCancelRequest cancelReq = new SubscriptionCancelRequest();
            cancelReq.setSubscriptionId(result.getSubscriptionId());
            cancelReq.setCancelReason("用户取消");
            
            SubscriptionCancelResult cancelResult = subscriptionService.cancelSubscription(cancelReq);
        }
    }
}