在线支付系列【17】微信支付实战篇之集成退款相关API

向右看齐 2023-10-09 15:32 13阅读 0赞

> **有道无术，术尚可求，有术无道，止于术。**

#### 文章目录 ####

*   *  前言
     *  申请退款
     *   *  1. 环境搭建
         *  2. 集成微信退款API
         *  3. 退款接口
         *  4. 测试
     *  查询单笔退款
     *   *  1. 集成微信查询单笔退款API
         *  2. 查询单笔退款接口
         *  3. 测试
     *  退款结果通知

### 前言 ###

我们实际在退款时，也是微信和用户之间数据交互，商户需要知道当前退款单的具体情况，也主要进行和下单相同的方式处理，保证状态一致。

**包括：**

*  查询获取退款信息
 *  接收通知，获取退款信息
 *  定时任务或者延迟队列，获取退款信息

### 申请退款 ###

[申请退款API][API]

**当交易发生之后一年内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付金额退还给买家，微信支付将在收到退款请求并且验证成功之后，将支付款按原路退还至买家账号上。**

**注意事项：**  
![在这里插入图片描述][eee411a5020b4f32878fcacc45334794.png]  
**退款状态转变如下：**  
![在这里插入图片描述][3330c5a54a3a4aeeb5e2bfc5dad77bf6.png]

#### 1. 环境搭建 ####

首先**创建退款表**。

SET NAMES utf8mb4;
    SET FOREIGN_KEY_CHECKS = 0;
    
    DROP TABLE IF EXISTS `t_refund`;
    CREATE TABLE `t_refund`  (
      `id` bigint(0) UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '退款单id',
      `order_no` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '商户订单编号',
      `refund_no` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '商户退款单编号',
      `refund_id` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '支付系统退款单号',
      `total_fee` int(0) NULL DEFAULT NULL COMMENT '原订单金额(分)',
      `refund` int(0) NULL DEFAULT NULL COMMENT '退款金额(分)',
      `reason` varchar(50) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '退款原因',
      `refund_status` varchar(10) CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL DEFAULT NULL COMMENT '退款状态',
      `content_return` text CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL COMMENT '申请退款返回参数',
      `content_notify` text CHARACTER SET utf8mb4 COLLATE utf8mb4_0900_ai_ci NULL COMMENT '退款结果通知参数',
      `create_time` datetime(0) NULL DEFAULT CURRENT_TIMESTAMP(0) COMMENT '创建时间',
      `update_time` datetime(0) NULL DEFAULT CURRENT_TIMESTAMP(0) ON UPDATE CURRENT_TIMESTAMP(0) COMMENT '更新时间',
      PRIMARY KEY (`id`) USING BTREE
    ) ENGINE = InnoDB AUTO_INCREMENT = 1 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_0900_ai_ci ROW_FORMAT = Dynamic;
    
    SET FOREIGN_KEY_CHECKS = 1;

使用[代码生成器][Link 1]生成基础代码。

#### 2. 集成微信退款API ####

枚举类`WechatPayNativeApiEnum`添加退款API地址：

DOMESTIC_REFUNDS("https://api.mch.weixin.qq.com/v3/refund/domestic/refunds", "申请退款"),

添加退款状态枚举类：

/**
     * 退款到银行发现用户的卡作废或者冻结了，导致原路退款银行卡失败，可前往商户平台-交易中心，手动处理此笔退款。
     * 枚举值：
     * SUCCESS：退款成功
     * CLOSED：退款关闭
     * PROCESSING：退款处理中
     * ABNORMAL：退款异常
     */
    @AllArgsConstructor
    @Getter
    public enum  WechatRefundStatus {
        
        SUCCESS("SUCCESS"),
        CLOSED("CLOSED"),
        PROCESSING("PROCESSING"),
        ABNORMAL("ABNORMAL");
        private final String type;
    }

微信支付服务接口声明微信退款方法：

/**
         * 集成微信退款API
         *
         * @param outTradeNo 商户订单号
         * @param reason     退款原因
         */
        String refund(String outTradeNo, String reason, String outRefundNo, String notifyUrl,
                    Integer total, Integer refund) throws Exception;

实现上述方法：

@Override
        public String refund(String outTradeNo, String reason, String outRefundNo, String notifyUrl,
                             Integer total, Integer refund) throws Exception {
        
            // 1. 请求对象
            HttpPost httpPost = new HttpPost(WechatPayNativeApiEnum.DOMESTIC_REFUNDS.getAddress());
            httpPost.addHeader("Accept", "application/json");
            httpPost.addHeader("Content-type", "application/json; charset=utf-8");
            ByteArrayOutputStream bos = new ByteArrayOutputStream();
            ObjectNode rootNode = objectMapper.createObjectNode();
            rootNode.put("out_trade_no", outTradeNo) // 商户订单
                    .put("out_refund_no", outRefundNo) // 退款单编号
                    .put("reason", reason)// 商品描述
                    .put("notify_url", notifyUrl); // //退款通知地址
            rootNode.putObject("amount")
                    .put("total", total) // 订单金额对象
                    .put("refund", total) //退款金额
                    .put("currency", "CNY") // 退款币种
                    .put("total", total); // 原订单金额，单位为分
            objectMapper.writeValue(bos, rootNode);
            httpPost.setEntity(new StringEntity(bos.toString("UTF-8"), "UTF-8"));
            // 2. 执行请求
            CloseableHttpResponse response = httpClient.execute(httpPost);
            String bodyAsString = EntityUtils.toString(response.getEntity()); // 返回结果
            int statusCode = response.getStatusLine().getStatusCode();
            if (statusCode == 200 || (statusCode == 204)) {
        
                log.info("退款成功，返回结果：" + bodyAsString);
                return bodyAsString;
            } else {
        
                throw new RuntimeException("退款异常, 响应码 :" + statusCode);
            }
        }

#### 3. 退款接口 ####

退款服务类中，编写生成退款单、微信退款逻辑：

@Service
    @RequiredArgsConstructor
    public class RefundServiceImp extends ServiceImpl<RefundMapper, RefundEntity> implements RefundService {
        
    
        private final RefundMapper refundMapper;
    
        private final OrderService orderService;
    
        private final WechatPayService wechatPayService;
    
        @Override
        @Transactional
        public RefundEntity saveRefund(String orderId) {
        
            // 1. 查询商品订单
            OrderEntity order = orderService.getById(orderId);
            if (ObjectUtil.isNull(order)) {
        
                throw new IllegalArgumentException("订单不存在");
            }
            // 2. 创建退款单
            RefundEntity refund = new RefundEntity();
            refund.setTotalFee(order.getMoney());
            refund.setRefund(order.getMoney());
            refund.setOrderNo(order.getOutTradeNo());
            refund.setRefundStatus(WechatRefundStatus.PROCESSING.getType());
            refund.setRefundNo(IdUtil.fastUUID());
            refund.setReason("测试退款");
            refund.setCreateTime(LocalDateTime.now());
            save(refund);
            return refund;
        }
    
        @Override
        public void applyRefund(String orderId) {
        
            // 1. 创建退款单
            RefundEntity refund = saveRefund(orderId);
            // 2. 调用微信退款API
            try {
        
                String result = wechatPayService.refund(refund.getOrderNo(),
                        refund.getReason(),
                        refund.getRefundNo(),
                        "https://99a2-218-77-107-102.ap.ngrok.io/refund/notify",
                        refund.getTotalFee(),
                        refund.getRefund());
            } catch (Exception e) {
        
                throw new RuntimeException("退款失败，原因：" + e.getMessage());
            }
            // 3. 修改退款单
            refund.setRefundStatus(WechatRefundStatus.SUCCESS.getType());
            updateById(refund);
        }
    }

提供对外访问接口：

@RestController
    @RequestMapping("/refund")
    @RequiredArgsConstructor
    @Tag(name = "退款管理", description = "管理")
    public class RefundController {
        
    
        private final RefundService refundService;
    
        @Operation(summary = "申请退款")
        @PostMapping("/applyRefund")
        public R<?> applyRefund(String orderId) throws Exception {
        
            refundService.applyRefund(orderId);
            return R.success();
        }
    }

#### 4. 测试 ####

选择一个已支付的订单：  
![在这里插入图片描述][6223058b99d84bedb4cf24ab44e4e847.png]  
访问申请退款接口：  
![在这里插入图片描述][86e158a1f4fd4f86a0c2648d6f42578e.png]  
微信返回退款信息：  
![在这里插入图片描述][58865c5323be453c91c48a624f0d10a4.png]  
微信成功收到退款：  
![在这里插入图片描述][69c2f4173bcd4642b81ce4d8dd6ab162.png]

### 查询单笔退款 ###

[微信查询单笔退款API文档][API 1]

**提交退款申请后，通过调用该接口查询退款状态**。

退款有一定延时，建议在提交退款申请后1分钟发起查询退款状态，一般来说零钱支付的退款5分钟内到账，银行卡支付的退款1-3个工作日到账。

用户在申请退款后，商户需要提供**订单查询退款详情接口**。

#### 1. 集成微信查询单笔退款API ####

枚举类`WechatPayNativeApiEnum`添加微信查询单笔退款API地址：

DOMESTIC_REFUNDS_QUERY("https://api.mch.weixin.qq.com/v3/refund/domestic/refunds/%s", "查询单笔退款"),

微信支付服务类集成微信查询单笔退款API：

/**
         * 查询单笔退款API
         *
         * @param outRefundNo 退款订单号
         */
        String getRefund(String outRefundNo) throws Exception;
        
        @Override
        public String getRefund(String outRefundNo) throws Exception {
        
            // 1. 构建请求对象
            HttpGet httpGet = new HttpGet(String.format(WechatPayNativeApiEnum.DOMESTIC_REFUNDS_QUERY.getAddress(), outRefundNo));
            httpGet.setHeader("Accept", "application/json");
            // 2. 执行请求
            CloseableHttpResponse response = httpClient.execute(httpGet);
            // 3. 获取响应
            String bodyAsString = EntityUtils.toString(response.getEntity());
            int statusCode = response.getStatusLine().getStatusCode();
            if (statusCode == 200 || statusCode == 204) {
        
                log.info("成功, 查询退款返回结果 = " + bodyAsString);
                return bodyAsString;
            } else {
        
                throw new RuntimeException("查询退款异常，状态码：" + statusCode);
            }
        }

#### 2. 查询单笔退款接口 ####

添加查询单笔退款服务类：

public String selectRefund(String refundId) throws Exception {
        
            // 1. 退款单
            RefundEntity refund = getById(refundId);
            // 2. 微信查询
            String result = wechatPayService.getRefund(refund.getRefundNo());
            // 3. 如果微信和商户的退款状态不一致，更新
            Map<String, String> resultMap = objectMapper.readValue(result, Map.class);
            String refund_id = resultMap.get("refund_id"); // 微信支付退款单号
            String status = resultMap.get("status"); // 退款状态
            if (refund.getRefundStatus().equals(status)){
        
                refund.setRefundId(refund_id);
                refund.setRefundStatus(status);
            }
            return result;
        }

添加查询单笔退款访问接口：

@Operation(summary = "查询退款")
        @PostMapping("/selectRefund")
        public R<?> selectRefund(String refundId) throws Exception {
        
            String refund =refundService.selectRefund(refundId);
            return R.success(refund);
        }

#### 3. 测试 ####

返回结果如下：  
![在这里插入图片描述][aa5c4c4a7ddc4e5288ae4717e1f68204.png]

### 退款结果通知 ###

[微信退款结果通知API文档][API 1]

**和支付通知一样，退款也会有结果通知。退款状态改变后，微信会把相关退款结果发送给商户。**

![在这里插入图片描述][1471b5b6401349dc8a7ca3bea2055024.png]`退款结果通知`和支付通知处理流程都是一样的。参考官网API集成即可，也比较简单，这里就不赘述了。

[API]: https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_4_9.shtml
[eee411a5020b4f32878fcacc45334794.png]: https://img-blog.csdnimg.cn/eee411a5020b4f32878fcacc45334794.png
[3330c5a54a3a4aeeb5e2bfc5dad77bf6.png]: https://img-blog.csdnimg.cn/3330c5a54a3a4aeeb5e2bfc5dad77bf6.png
[Link 1]: https://gitee.com/pearl-organization/pearl-code-generator
[6223058b99d84bedb4cf24ab44e4e847.png]: https://img-blog.csdnimg.cn/6223058b99d84bedb4cf24ab44e4e847.png
[86e158a1f4fd4f86a0c2648d6f42578e.png]: https://img-blog.csdnimg.cn/86e158a1f4fd4f86a0c2648d6f42578e.png
[58865c5323be453c91c48a624f0d10a4.png]: https://img-blog.csdnimg.cn/58865c5323be453c91c48a624f0d10a4.png
[69c2f4173bcd4642b81ce4d8dd6ab162.png]: https://img-blog.csdnimg.cn/69c2f4173bcd4642b81ce4d8dd6ab162.png
[API 1]: https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_4_10.shtml
[aa5c4c4a7ddc4e5288ae4717e1f68204.png]: https://img-blog.csdnimg.cn/aa5c4c4a7ddc4e5288ae4717e1f68204.png
[1471b5b6401349dc8a7ca3bea2055024.png]: https://img-blog.csdnimg.cn/1471b5b6401349dc8a7ca3bea2055024.png