169 lines
4.2 KiB
Markdown
169 lines
4.2 KiB
Markdown
# 微信支付退款配置指南
|
||
|
||
## 概述
|
||
|
||
本项目已集成微信支付V3版本的退款功能，支持用户取消订单后自动退款到微信账户。
|
||
|
||
## 前置条件
|
||
|
||
1. 已开通微信支付商户号
|
||
2. 已获取微信支付API证书
|
||
3. 已配置微信支付API密钥
|
||
|
||
## 配置步骤
|
||
|
||
### 1. 获取微信支付配置信息
|
||
|
||
登录 [微信支付商户平台](https://pay.weixin.qq.com/)，获取以下信息：
|
||
|
||
- **WECHAT_APPID**: 小程序AppID（已有）
|
||
- **WECHAT_MCHID**: 商户号
|
||
- **WECHAT_SERIAL_NO**: API证书序列号
|
||
- **WECHAT_APIV3_KEY**: APIv3密钥
|
||
- **WECHAT_PRIVATE_KEY**: API证书私钥内容
|
||
|
||
### 2. 下载API证书
|
||
|
||
1. 进入 **账户中心 > API安全 > 申请API证书**
|
||
2. 下载证书文件（apiclient_key.pem）
|
||
3. 复制私钥内容到环境变量
|
||
|
||
### 3. 配置环境变量
|
||
|
||
编辑 `apps/server/.env.local` 文件，添加以下配置：
|
||
|
||
```bash
|
||
# 微信支付配置
|
||
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：
|
||
|
||
1. 进入 **产品中心 > 开发配置**
|
||
2. 设置退款通知URL: `https://your-domain.com/api/payment/wechat/refund-notify`
|
||
|
||
## 功能说明
|
||
|
||
### 退款流程
|
||
|
||
1. **用户发起退款**：在订单详情页点击"取消订单"
|
||
2. **状态检查**：只有 `pending_confirm`（待确认）和 `pending_checkin`（待入住）状态的订单可退款
|
||
3. **调用微信退款API**：系统自动调用微信支付退款接口
|
||
4. **更新订单状态**：退款成功后，订单状态变更为 `refunded`
|
||
5. **恢复库存**：自动恢复房态库存
|
||
6. **记录平台账户**：记录退款支出交易（仅记账）
|
||
|
||
### 退款时间
|
||
|
||
- 微信支付退款：1-3个工作日到账
|
||
- 退款原路返回至用户微信账户
|
||
|
||
### 退款重试
|
||
|
||
如果退款失败，订单会保持 `refunding` 状态，可以通过管理后台手动重试：
|
||
|
||
```typescript
|
||
// 调用重试接口
|
||
await refundService.retryRefund(orderId);
|
||
```
|
||
|
||
## 测试模式
|
||
|
||
如果未配置微信支付参数，系统会自动进入**模拟模式**：
|
||
|
||
- 退款接口调用会被模拟（仅打印日志）
|
||
- 订单状态正常更新
|
||
- 库存正常恢复
|
||
- 适用于开发和测试环境
|
||
|
||
## 数据库变更
|
||
|
||
需要执行以下迁移脚本：
|
||
|
||
```bash
|
||
mysql -u root -p rent_platform < database/migrations/002_add_transaction_id_to_orders.sql
|
||
```
|
||
|
||
该脚本会在 `orders` 表添加 `transaction_id` 字段，用于存储微信支付交易号。
|
||
|
||
## API文档
|
||
|
||
### 退款接口
|
||
|
||
**接口**: `POST /api/orders/:id/refund`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"reason": "用户主动取消"
|
||
}
|
||
```
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "退款成功，款项将原路返回",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
### 退款重试接口（管理员）
|
||
|
||
**接口**: `POST /api/admin/orders/:id/retry-refund`
|
||
|
||
**响应**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "退款重试成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
### 1. 退款失败：签名验证失败
|
||
|
||
**原因**：私钥配置错误或证书序列号不匹配
|
||
|
||
**解决**：
|
||
- 检查 `WECHAT_PRIVATE_KEY` 是否包含完整内容
|
||
- 确认 `WECHAT_SERIAL_NO` 与证书匹配
|
||
|
||
### 2. 退款失败：商户号不匹配
|
||
|
||
**原因**：`WECHAT_MCHID` 配置错误
|
||
|
||
**解决**：登录商户平台确认商户号
|
||
|
||
### 3. 退款失败：订单缺少交易号
|
||
|
||
**原因**：订单的 `transaction_id` 字段为空
|
||
|
||
**解决**：
|
||
- 确保支付成功后保存了微信支付交易号
|
||
- 检查支付回调逻辑是否正确
|
||
|
||
## 相关文档
|
||
|
||
- [微信支付退款API文档](https://pay.weixin.qq.com/wiki/doc/apiv3/apis/chapter3_5_9.shtml)
|
||
- [微信支付开发指引](https://pay.weixin.qq.com/wiki/doc/apiv3/index.shtml)
|
||
|
||
## 技术支持
|
||
|
||
如有问题，请联系技术团队或查看微信支付官方文档。
|