rent/docs/WECHAT_PAY_SETUP.md

微信支付配置说明

环境变量配置

在 apps/server/.env.local 文件中添加以下配置：

# 微信小程序配置
WECHAT_APPID=你的小程序AppID
WECHAT_SECRET=你的小程序AppSecret

# 微信支付配置
WECHAT_MCHID=你的商户号
WECHAT_SERIAL_NO=你的API证书序列号
WECHAT_APIV3_KEY=你的APIv3密钥

# 微信支付私钥（需要转义换行符）
WECHAT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n你的私钥内容\n-----END PRIVATE KEY-----"

# 支付回调地址（需要配置为外网可访问的地址）
WECHAT_PAY_NOTIFY_URL=https://你的域名/api/app/payment/wechat/notify

# API基础地址
API_BASE_URL=https://你的域名

获取微信支付配置参数

1. 获取商户号 (WECHAT_MCHID)

• 登录微信支付商户平台：https://pay.weixin.qq.com
• 在"账户中心" -> "商户信息"中查看商户号

2. 获取API证书序列号 (WECHAT_SERIAL_NO)

• 在微信支付商户平台，进入"账户中心" -> "API安全"
• 下载API证书（apiclient_cert.pem）
• 使用以下命令查看证书序列号：

  openssl x509 -in apiclient_cert.pem -noout -serial
  

3. 获取APIv3密钥 (WECHAT_APIV3_KEY)

• 在微信支付商户平台，进入"账户中心" -> "API安全"
• 设置APIv3密钥（32位字符串）

4. 获取API私钥 (WECHAT_PRIVATE_KEY)

• 下载API证书后，会得到 apiclient_key.pem 文件
• 将文件内容复制到环境变量中，注意：
  • 需要将换行符替换为 \n
  • 整个内容用双引号包裹
  • 示例："-----BEGIN PRIVATE KEY-----\nMIIEvQI...\n-----END PRIVATE KEY-----"

配置支付回调地址

1. 在微信支付商户平台配置

• 登录微信支付商户平台
• 进入"产品中心" -> "开发配置"
• 配置"JSAPI支付"回调地址：https://你的域名/api/app/payment/wechat/notify

2. 确保回调地址可访问

• 回调地址必须是外网可访问的HTTPS地址
• 本地开发可以使用内网穿透工具（如ngrok、frp）

小程序端使用

在小程序页面中调用支付：

import { wxPay } from '@/api/user/order';

// 创建订单后调用支付
async function handlePay(orderNo: string) {
  try {
    uni.showLoading({ title: '正在支付...' });
    
    await wxPay(orderNo);
    
    uni.hideLoading();
    uni.showToast({ title: '支付成功', icon: 'success' });
    
    // 跳转到订单详情或订单列表
    uni.navigateTo({ url: `/pages/order/detail?orderNo=${orderNo}` });
  } catch (error) {
    uni.hideLoading();
    uni.showToast({ 
      title: error.message || '支付失败', 
      icon: 'none' 
    });
  }
}

支付流程

1. 用户创建订单：调用 POST /api/app/orders 创建订单，订单状态为 pending_pay
2. 发起支付：调用 POST /api/app/orders/pay，后端调用微信支付统一下单接口
3. 小程序调起支付：使用返回的支付参数调用 uni.requestPayment
4. 支付回调：微信支付成功后回调 POST /api/app/payment/wechat/notify
5. 更新订单状态：后端验证签名后更新订单状态为 pending_confirm

注意事项

1. 证书安全：

   • 不要将私钥提交到代码仓库
   • 使用 .env.local 文件存储敏感信息
   • .env.local 应该在 .gitignore 中

2. 回调验证：

   • 后端会自动验证微信支付回调的签名
   • 确保回调地址配置正确且可访问

3. 订单幂等性：

   • 支付回调可能会重复通知
   • 代码已处理订单状态判断，避免重复处理

4. 测试环境：

   • 微信支付需要使用真实的商户号和证书
   • 可以使用微信支付的沙箱环境进行测试

退款功能

退款功能已集成在 WechatPayService 中，可以通过以下方式调用：

await this.wechatPayService.refund({
  orderNo: '订单号',
  refundNo: '退款单号',
  totalAmount: 100, // 订单总金额（元）
  refundAmount: 100, // 退款金额（元）
  reason: '退款原因',
  notifyUrl: '退款回调地址（可选）',
});

退款回调地址：POST /api/app/payment/wechat/refund-notify