282 lines
6.5 KiB
Markdown
282 lines
6.5 KiB
Markdown
# 支付宝支付功能集成指南
|
||
|
||
## 概述
|
||
|
||
本系统已集成支付宝支付功能，支持PC网站支付和手机网站支付。支付成功后系统会自动生成许可证。
|
||
|
||
## 功能特性
|
||
|
||
- ✅ 支持PC网站支付（电脑端）
|
||
- ✅ 支持手机网站支付（移动端）
|
||
- ✅ 支付成功后自动生成许可证
|
||
- ✅ 异步通知处理，确保支付状态准确
|
||
- ✅ 订单状态实时查询
|
||
- ✅ 完整的支付结果页面
|
||
|
||
## 依赖安装
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
需要安装 `alipay-sdk-python3==3.7.4`
|
||
|
||
## 配置支付宝参数
|
||
|
||
### 1. 获取支付宝应用信息
|
||
|
||
1. 登录[支付宝开放平台](https://open.alipay.com/)
|
||
2. 创建应用（网站支付类型）
|
||
3. 获取以下信息：
|
||
- APP_ID（应用ID）
|
||
- 应用私钥（APP_PRIVATE_KEY）
|
||
- 支付宝公钥（ALIPAY_PUBLIC_KEY）
|
||
- 支付宝平台公钥（ALIPAY_ALIPAY_PUBLIC_KEY）
|
||
|
||
### 2. 配置环境变量
|
||
|
||
在生产环境中，建议通过环境变量配置支付宝参数：
|
||
|
||
```bash
|
||
export ALIPAY_APP_ID="your_app_id"
|
||
export ALIPAY_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----"
|
||
export ALIPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
|
||
export ALIPAY_ALIPAY_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----"
|
||
```
|
||
|
||
### 3. 配置文件（开发环境）
|
||
|
||
也可以在 `.env` 文件中配置：
|
||
|
||
```env
|
||
ALIPAY_APP_ID=your_app_id
|
||
ALIPAY_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----
|
||
your_private_key_content
|
||
-----END PRIVATE KEY-----
|
||
ALIPAY_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----
|
||
your_public_key_content
|
||
-----END PUBLIC KEY-----
|
||
ALIPAY_ALIPAY_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----
|
||
alipay_public_key_content
|
||
-----END PUBLIC KEY-----
|
||
```
|
||
|
||
## API接口
|
||
|
||
### 1. 创建订单
|
||
|
||
**接口：** `POST /api/v1/user/orders`
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"product_id": "产品ID",
|
||
"package_id": "套餐ID",
|
||
"contact_person": "联系人姓名",
|
||
"phone": "手机号",
|
||
"quantity": 1
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "订单创建成功",
|
||
"data": {
|
||
"order_number": "ORD123456789",
|
||
"amount": 99.00
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2. 创建支付宝支付
|
||
|
||
**接口：** `POST /api/v1/user/pay/alipay`
|
||
|
||
**请求参数：**
|
||
```json
|
||
{
|
||
"order_number": "订单号",
|
||
"payment_type": "pc" // 或 "wap"
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "支付链接创建成功",
|
||
"data": {
|
||
"payment_url": "https://openapi.alipay.com/...",
|
||
"order_number": "ORD123456789",
|
||
"amount": 99.00
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 查询订单
|
||
|
||
**接口：** `GET /api/v1/user/orders/query?order_number=订单号&phone=手机号`
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"data": {
|
||
"order_number": "ORD123456789",
|
||
"status": 1,
|
||
"status_name": "已支付",
|
||
"amount": 99.00,
|
||
"payment_time": "2024-01-01 12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 支付宝异步通知
|
||
|
||
**接口：** `POST /api/v1/pay/alipay1/user/notify`
|
||
|
||
支付宝会向此接口发送异步通知，系统会自动处理支付状态更新和许可证生成。
|
||
|
||
## 前端页面
|
||
|
||
### 1. 购买页面
|
||
|
||
用户访问 `/user/licenses/purchase` 页面购买许可证。
|
||
|
||
页面功能：
|
||
- 选择产品和套餐
|
||
- 填写联系信息
|
||
- 选择支付方式（支付宝/微信）
|
||
- 创建订单并跳转到支付
|
||
|
||
### 2. 支付结果页面
|
||
|
||
支付完成后跳转到 `/payment/result?order_number=订单号`
|
||
|
||
页面功能：
|
||
- 显示支付结果
|
||
- 显示订单信息
|
||
- 显示生成的许可证密钥
|
||
- 支持复制许可证密钥
|
||
|
||
## 支付流程
|
||
|
||
```
|
||
用户选择产品 → 创建订单 → 创建支付链接 → 跳转到支付宝 → 支付完成
|
||
↓
|
||
生成许可证 ← 更新订单状态 ← 支付宝异步通知 ← ← ← ← ← ← ← ← ← ← ← ← ← ←
|
||
```
|
||
|
||
## 重要说明
|
||
|
||
### 1. 异步通知处理
|
||
|
||
支付宝异步通知是支付状态更新的主要方式，系统会：
|
||
- 验证通知的签名
|
||
- 检查订单状态
|
||
- 更新订单状态为"已支付"
|
||
- 自动生成许可证
|
||
- 记录操作日志
|
||
|
||
### 2. 支付链接生成
|
||
|
||
根据客户端类型自动选择支付方式：
|
||
- PC端：使用 `alipay.trade.page.pay` 接口
|
||
- 移动端：使用 `alipay.trade.wap.pay` 接口
|
||
|
||
### 3. 许可证生成
|
||
|
||
支付成功后系统会自动：
|
||
- 查询订单信息
|
||
- 根据套餐配置生成许可证
|
||
- 设置有效期和最大设备数
|
||
- 保存许可证到数据库
|
||
|
||
## 错误处理
|
||
|
||
### 1. 常见错误
|
||
|
||
| 错误信息 | 原因 | 解决方法 |
|
||
|---------|------|----------|
|
||
| 支付配置错误 | 支付宝参数未配置 | 检查环境变量和配置文件 |
|
||
| 订单不存在 | 订单号错误 | 检查订单号是否正确 |
|
||
| 套餐库存不足 | 套餐库存为0 | 联系管理员补充库存 |
|
||
| 订单金额不匹配 | 金额被篡改 | 检查订单和支付金额 |
|
||
|
||
### 2. 日志查看
|
||
|
||
系统会在 `logs/kamaxitong.log` 中记录：
|
||
- 订单创建日志
|
||
- 支付流程日志
|
||
- 支付宝通知日志
|
||
- 许可证生成日志
|
||
|
||
## 安全建议
|
||
|
||
1. **生产环境配置**
|
||
- 使用HTTPS协议
|
||
- 设置 `SESSION_COOKIE_SECURE=True`
|
||
- 定期更换密钥
|
||
|
||
2. **签名验证**
|
||
- 系统会自动验证支付宝通知签名
|
||
- 签名验证失败的通知会被拒绝
|
||
|
||
3. **订单金额验证**
|
||
- 系统会验证通知中的金额与订单金额一致
|
||
- 不匹配的订单会被拒绝
|
||
|
||
## 故障排除
|
||
|
||
### 1. 支付链接无法打开
|
||
|
||
**可能原因：**
|
||
- 支付宝配置错误
|
||
- 订单状态不正确
|
||
- 支付金额格式错误
|
||
|
||
**解决方法：**
|
||
- 检查支付宝配置
|
||
- 确认订单状态为"待支付"
|
||
- 检查订单金额是否为有效数字
|
||
|
||
### 2. 支付成功但订单状态未更新
|
||
|
||
**可能原因：**
|
||
- 异步通知未收到
|
||
- 异步通知处理失败
|
||
|
||
**解决方法：**
|
||
- 查看日志文件，检查异步通知记录
|
||
- 可以通过订单查询接口手动检查状态
|
||
- 联系支付宝客服查询支付记录
|
||
|
||
### 3. 许可证未生成
|
||
|
||
**可能原因：**
|
||
- 许可证生成逻辑出错
|
||
- 数据库连接异常
|
||
|
||
**解决方法：**
|
||
- 查看日志文件中的错误信息
|
||
- 检查数据库连接
|
||
- 手动重新触发许可证生成（需要管理员操作）
|
||
|
||
## 技术支持
|
||
|
||
如有技术问题，请：
|
||
1. 查看日志文件：`logs/kamaxitong.log`
|
||
2. 检查支付宝配置是否正确
|
||
3. 确认网络连接和防火墙设置
|
||
4. 联系开发团队
|
||
|
||
## 更新日志
|
||
|
||
### v1.0.0 (2024-12-11)
|
||
- 初始版本
|
||
- 支持支付宝PC网站支付和手机网站支付
|
||
- 自动生成许可证
|
||
- 异步通知处理
|
||
- 支付结果页面 |