164 lines
4.7 KiB
Markdown
164 lines
4.7 KiB
Markdown
# 支付网关集成指南
|
||
|
||
## 概述
|
||
本文档说明如何配置和集成支付宝和微信支付网关。
|
||
|
||
## 环境配置
|
||
|
||
### 1. 配置文件
|
||
在 `.env` 文件中添加以下配置：
|
||
|
||
```env
|
||
# 支付宝配置
|
||
ALIPAY_APP_ID=your_app_id
|
||
ALIPAY_MERCHANT_PRIVATE_KEY=your_merchant_private_key
|
||
ALIPAY_PUBLIC_KEY=your_alipay_public_key
|
||
ALIPAY_NOTIFY_URL=https://yourdomain.com/api/order/alipay-notify
|
||
ALIPAY_RETURN_URL=https://yourdomain.com/order
|
||
ALIPAY_GATEWAY_URL=https://openapi.alipay.com/gateway.do
|
||
|
||
# 微信支付配置
|
||
WECHAT_APP_ID=your_app_id
|
||
WECHAT_MCH_ID=your_mch_id
|
||
WECHAT_API_KEY=your_api_key
|
||
WECHAT_NOTIFY_URL=https://yourdomain.com/api/order/wechat-notify
|
||
WECHAT_GATEWAY_URL=https://api.mch.weixin.qq.com
|
||
```
|
||
|
||
### 2. 数据库迁移
|
||
运行以下SQL添加 `trade_no` 字段到订单表：
|
||
|
||
```sql
|
||
ALTER TABLE `la_order` ADD COLUMN `trade_no` varchar(100) DEFAULT NULL COMMENT '第三方交易号' AFTER `payment_time`;
|
||
```
|
||
|
||
## 支付流程
|
||
|
||
### 正常支付流程
|
||
1. 用户点击"支付"按钮
|
||
2. 选择支付方式（支付宝或微信）
|
||
3. 点击"确认支付"
|
||
4. 前端调用 `/order.order/alipay` 或 `/order.order/wechat` 接口
|
||
5. 后端生成支付链接/数据并返回
|
||
6. 前端跳转到支付页面或显示二维码
|
||
7. 用户完成支付
|
||
8. 支付网关回调 `/api/order/alipay-notify` 或 `/api/order/wechat-notify`
|
||
9. 后端验证签名并更新订单状态
|
||
|
||
### 补单支付流程
|
||
1. 用户选择"补单支付"
|
||
2. 输入支付订单号
|
||
3. 选择支付方式
|
||
4. 点击"确认支付"
|
||
5. 前端调用支付接口，参数中 `is_supplement=1`
|
||
6. 后端不校验订单是否存在，直接生成支付链接/数据
|
||
7. 用户完成支付
|
||
8. 支付网关回调更新订单状态
|
||
|
||
## 支付宝集成
|
||
|
||
### 获取密钥
|
||
1. 登录 [支付宝开放平台](https://open.alipay.com/)
|
||
2. 进入"开发者中心" -> "应用管理"
|
||
3. 创建应用或选择已有应用
|
||
4. 在"应用信息"中获取 App ID
|
||
5. 在"开发设置"中生成密钥对
|
||
6. 下载商户私钥和支付宝公钥
|
||
|
||
### 配置回调
|
||
1. 在应用设置中配置"异步通知地址"
|
||
2. 地址格式：`https://yourdomain.com/api/order/alipay-notify`
|
||
3. 配置"同步返回地址"（可选）
|
||
4. 地址格式：`https://yourdomain.com/order`
|
||
|
||
### 测试
|
||
支付宝提供沙箱环境用于测试：
|
||
- 沙箱网址：https://openapi.alipaydev.com/gateway.do
|
||
- 在 `.env` 中设置 `ALIPAY_GATEWAY_URL=https://openapi.alipaydev.com/gateway.do`
|
||
|
||
## 微信支付集成
|
||
|
||
### 获取密钥
|
||
1. 登录 [微信商户平台](https://pay.weixin.qq.com/)
|
||
2. 进入"账户中心" -> "API安全"
|
||
3. 获取商户号（Mch ID）
|
||
4. 在"API密钥"中生成 API Key
|
||
5. 在"证书管理"中下载证书（如需要）
|
||
|
||
### 配置回调
|
||
1. 在商户平台配置"回调地址"
|
||
2. 地址格式：`https://yourdomain.com/api/order/wechat-notify`
|
||
|
||
### 测试
|
||
微信支付提供沙箱环境用于测试：
|
||
- 沙箱网址：https://api.mch.weixin.qq.com
|
||
- 使用测试商户号和 API Key
|
||
|
||
## 后端实现
|
||
|
||
### 支付逻辑（OrderLogic.php）
|
||
- `alipayPay()` - 生成支付宝支付URL
|
||
- `wechatPay()` - 生成微信支付数据
|
||
- `generateAlipayUrl()` - 生成支付宝支付链接
|
||
- `generateWechatPayData()` - 生成微信支付数据
|
||
- `generateAlipaySign()` - 生成支付宝签名
|
||
- `generateWechatSign()` - 生成微信签名
|
||
|
||
### 回调处理
|
||
- `AlipayNotifyController::notify()` - 处理支付宝异步通知
|
||
- `WechatNotifyController::notify()` - 处理微信异步通知
|
||
|
||
### 签名验证
|
||
- 支付宝：使用 RSA2 算法验证签名
|
||
- 微信：使用 MD5 算法验证签名
|
||
|
||
## 前端实现
|
||
|
||
### 支付流程
|
||
1. 用户选择支付方式
|
||
2. 调用 `alipayPay()` 或 `wechatPay()` API
|
||
3. 获取支付链接或支付数据
|
||
4. 支付宝：跳转到支付页面
|
||
5. 微信：显示二维码或其他处理
|
||
|
||
### 支付状态更新
|
||
- 支付完成后，后端通过回调更新订单状态
|
||
- 前端定时刷新订单列表以获取最新状态
|
||
|
||
## 常见问题
|
||
|
||
### 1. 签名验证失败
|
||
- 检查密钥是否正确
|
||
- 检查签名算法是否匹配
|
||
- 检查参数排序是否正确
|
||
|
||
### 2. 回调未收到
|
||
- 检查回调地址是否正确
|
||
- 检查防火墙是否允许回调
|
||
- 检查日志中是否有错误信息
|
||
|
||
### 3. 金额不匹配
|
||
- 检查前端传递的金额是否正确
|
||
- 检查后端计算的金额是否正确
|
||
- 微信支付需要将金额转换为分
|
||
|
||
## 安全建议
|
||
|
||
1. 不要在代码中硬编码密钥，使用环境变量
|
||
2. 验证所有回调请求的签名
|
||
3. 使用 HTTPS 传输敏感信息
|
||
4. 定期更新密钥
|
||
5. 记录所有支付相关的日志
|
||
6. 实现幂等性处理，防止重复支付
|
||
|
||
## 测试清单
|
||
|
||
- [ ] 支付宝支付流程测试
|
||
- [ ] 微信支付流程测试
|
||
- [ ] 补单支付流程测试
|
||
- [ ] 回调处理测试
|
||
- [ ] 签名验证测试
|
||
- [ ] 金额验证测试
|
||
- [ ] 异常处理测试
|
||
- [ ] 并发支付测试
|