xiaoquan/rent

Fork 0

Files

T

xiaoquan e471b75f59 feat: 迭代

2026-05-13 17:49:33 +08:00

4.2 KiB

Raw Permalink Blame History

微信支付退款配置指南

概述

本项目已集成微信支付V3版本的退款功能，支持用户取消订单后自动退款到微信账户。

前置条件

已开通微信支付商户号
已获取微信支付API证书
已配置微信支付API密钥

配置步骤

1. 获取微信支付配置信息

登录微信支付商户平台，获取以下信息：

WECHAT_APPID: 小程序AppID（已有）
WECHAT_MCHID: 商户号
WECHAT_SERIAL_NO: API证书序列号
WECHAT_APIV3_KEY: APIv3密钥
WECHAT_PRIVATE_KEY: API证书私钥内容

2. 下载API证书

进入 账户中心 > API安全 > 申请API证书
下载证书文件（apiclient_key.pem）
复制私钥内容到环境变量

3. 配置环境变量

编辑 apps/server/.env.local 文件，添加以下配置：

# 微信支付配置
WECHAT_MCHID=1234567890
WECHAT_SERIAL_NO=3B2XXXXXXXXXXXXXXXXXXXXXXXXX
WECHAT_APIV3_KEY=your_apiv3_key_32_characters
WECHAT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
-----END PRIVATE KEY-----"
WECHAT_REFUND_NOTIFY_URL=https://your-domain.com/api/payment/wechat/refund-notify

注意事项：

WECHAT_PRIVATE_KEY 需要包含完整的私钥内容（包括头尾标记）
私钥内容可以使用换行符，也可以使用 \n 转义
WECHAT_REFUND_NOTIFY_URL 需要替换为实际的域名

4. 配置退款回调地址

在微信支付商户平台配置退款通知URL：

进入 产品中心 > 开发配置
设置退款通知URL: https://your-domain.com/api/payment/wechat/refund-notify

功能说明

退款流程

用户发起退款：在订单详情页点击"取消订单"
状态检查：只有 pending_confirm（待确认）和 pending_checkin（待入住）状态的订单可退款
调用微信退款API：系统自动调用微信支付退款接口
更新订单状态：退款成功后，订单状态变更为 refunded
恢复库存：自动恢复房态库存
记录平台账户：记录退款支出交易（仅记账）

退款时间

微信支付退款：1-3个工作日到账
退款原路返回至用户微信账户

退款重试

如果退款失败，订单会保持 refunding 状态，可以通过管理后台手动重试：

// 调用重试接口
await refundService.retryRefund(orderId);

测试模式

如果未配置微信支付参数，系统会自动进入模拟模式：

退款接口调用会被模拟（仅打印日志）
订单状态正常更新
库存正常恢复
适用于开发和测试环境

数据库变更

需要执行以下迁移脚本：

mysql -u root -p rent_platform < database/migrations/002_add_transaction_id_to_orders.sql

该脚本会在 orders 表添加 transaction_id 字段，用于存储微信支付交易号。

API文档

退款接口

接口: POST /api/orders/:id/refund

请求参数:

{
  "reason": "用户主动取消"
}

响应:

{
  "code": 200,
  "message": "退款成功，款项将原路返回",
  "data": null
}

退款重试接口（管理员）

接口: POST /api/admin/orders/:id/retry-refund

响应:

{
  "code": 200,
  "message": "退款重试成功",
  "data": null
}

常见问题

1. 退款失败：签名验证失败

原因：私钥配置错误或证书序列号不匹配

解决：

检查 WECHAT_PRIVATE_KEY 是否包含完整内容
确认 WECHAT_SERIAL_NO 与证书匹配

2. 退款失败：商户号不匹配

原因：WECHAT_MCHID 配置错误

解决：登录商户平台确认商户号

3. 退款失败：订单缺少交易号

原因：订单的 transaction_id 字段为空

解决：

确保支付成功后保存了微信支付交易号
检查支付回调逻辑是否正确

技术支持

如有问题，请联系技术团队或查看微信支付官方文档。

4.2 KiB Raw Permalink Blame History Unescape Escape