wurenzhi
136c2fa579
- 新增文档模板和导航结构 - 实现服务器基础API路由和控制器 - 添加扩展插件配置和前端框架 - 引入多租户和权限管理模块 - 集成日志和数据库配置 - 添加核心业务模型和类型定义
410 lines
9.7 KiB
Markdown
410 lines
9.7 KiB
Markdown
# 支付服务 API 文档
|
||
|
||
## 1. 概述
|
||
|
||
支付服务（PaymentService）提供了全面的支付处理功能，支持多种支付渠道（支付宝、微信支付、银联等），包括支付创建、回调处理、退款处理、对账等核心功能。
|
||
|
||
## 2. 核心功能
|
||
|
||
- **支付创建**：支持多种支付渠道的支付请求创建
|
||
- **支付回调**：处理支付渠道的异步回调通知
|
||
- **退款处理**：支持发起和处理退款请求
|
||
- **支付状态查询**：查询支付状态
|
||
- **支付列表**：获取支付记录列表，支持分页和过滤
|
||
- **支付统计**：获取支付相关的统计数据
|
||
- **对账功能**：支持单日对账和批量对账
|
||
- **对账报表**：生成对账报表
|
||
- **批量处理**：支持批量处理支付记录
|
||
|
||
## 3. API 端点
|
||
|
||
### 3.1 创建支付
|
||
|
||
**请求路径**：`POST /api/payments`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| tenantId | string | 是 | 租户ID |
|
||
| orderId | string | 是 | 订单ID |
|
||
| amount | number | 是 | 支付金额 |
|
||
| currency | string | 是 | 货币类型，如 USD、CNY |
|
||
| paymentMethod | string | 是 | 支付方式：ALIPAY、WECHAT、UNIONPAY、STRIPE |
|
||
| returnUrl | string | 否 | 支付完成后返回地址 |
|
||
| notifyUrl | string | 否 | 支付回调通知地址 |
|
||
| metadata | object | 否 | 附加信息，JSON格式 |
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"paymentId": "PAY-1234567890-12345",
|
||
"redirectUrl": "https://openapi.alipay.com/gateway.do?orderId=PAY-1234567890-12345",
|
||
"qrCodeUrl": "https://wx.tenpay.com/qrcode?orderId=PAY-1234567890-12345",
|
||
"status": "PENDING"
|
||
}
|
||
```
|
||
|
||
### 3.2 处理支付回调
|
||
|
||
**请求路径**：`POST /api/payments/callback`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| paymentId | string | 是 | 支付ID |
|
||
| orderId | string | 是 | 订单ID |
|
||
| status | string | 是 | 支付状态：SUCCESS、FAILED |
|
||
| transactionId | string | 是 | 交易ID |
|
||
| amount | number | 是 | 支付金额 |
|
||
| currency | string | 是 | 货币类型 |
|
||
| timestamp | string | 是 | 回调时间戳 |
|
||
| signature | string | 是 | 签名，用于验证回调真实性 |
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
### 3.3 发起退款
|
||
|
||
**请求路径**：`POST /api/payments/refund`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| tenantId | string | 是 | 租户ID |
|
||
| paymentId | string | 是 | 支付ID |
|
||
| orderId | string | 是 | 订单ID |
|
||
| amount | number | 是 | 退款金额 |
|
||
| reason | string | 是 | 退款原因 |
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"refundId": "REFUND-1234567890-12345"
|
||
}
|
||
```
|
||
|
||
### 3.4 查询支付状态
|
||
|
||
**请求路径**：`GET /api/payments/{paymentId}/status`
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"status": "SUCCESS"
|
||
}
|
||
```
|
||
|
||
### 3.5 获取支付列表
|
||
|
||
**请求路径**：`GET /api/payments`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| tenantId | string | 是 | 租户ID |
|
||
| page | number | 否 | 页码，默认1 |
|
||
| pageSize | number | 否 | 每页数量，默认20 |
|
||
| status | string | 否 | 支付状态过滤 |
|
||
| paymentMethod | string | 否 | 支付方式过滤 |
|
||
| startDate | string | 否 | 开始日期，格式：YYYY-MM-DD |
|
||
| endDate | string | 否 | 结束日期，格式：YYYY-MM-DD |
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"payments": [
|
||
{
|
||
"id": "PAY-1234567890-12345",
|
||
"tenant_id": "tenant-1",
|
||
"order_id": "order-1",
|
||
"amount": 100,
|
||
"currency": "USD",
|
||
"payment_method": "ALIPAY",
|
||
"status": "SUCCESS",
|
||
"transaction_id": "trans-123456",
|
||
"created_at": "2026-03-17T10:00:00Z",
|
||
"updated_at": "2026-03-17T10:05:00Z"
|
||
}
|
||
],
|
||
"total": 100
|
||
}
|
||
```
|
||
|
||
### 3.6 获取支付统计
|
||
|
||
**请求路径**：`GET /api/payments/stats`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| tenantId | string | 是 | 租户ID |
|
||
| startDate | string | 是 | 开始日期，格式：YYYY-MM-DD |
|
||
| endDate | string | 是 | 结束日期，格式：YYYY-MM-DD |
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"totalAmount": 10000,
|
||
"completedAmount": 8000,
|
||
"failedAmount": 1000,
|
||
"refundedAmount": 500,
|
||
"statusCounts": [
|
||
{
|
||
"status": "SUCCESS",
|
||
"count": 80,
|
||
"amount": 8000
|
||
},
|
||
{
|
||
"status": "FAILED",
|
||
"count": 10,
|
||
"amount": 1000
|
||
}
|
||
],
|
||
"paymentMethodStats": [
|
||
{
|
||
"paymentMethod": "ALIPAY",
|
||
"count": 50,
|
||
"amount": 5000
|
||
},
|
||
{
|
||
"paymentMethod": "WECHAT",
|
||
"count": 30,
|
||
"amount": 3000
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.7 对账
|
||
|
||
**请求路径**：`GET /api/payments/reconcile`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| tenantId | string | 是 | 租户ID |
|
||
| date | string | 是 | 对账日期，格式：YYYY-MM-DD |
|
||
| paymentMethod | string | 否 | 支付方式过滤 |
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"date": "2026-03-17",
|
||
"paymentMethod": "ALIPAY",
|
||
"payments": {
|
||
"total": 10,
|
||
"successful": 8,
|
||
"pending": 1,
|
||
"failed": 1,
|
||
"totalAmount": 1000
|
||
},
|
||
"refunds": {
|
||
"total": 2,
|
||
"successful": 2,
|
||
"totalAmount": 200
|
||
},
|
||
"netAmount": 800
|
||
}
|
||
```
|
||
|
||
### 3.8 批量处理支付
|
||
|
||
**请求路径**：`POST /api/payments/batch`
|
||
|
||
**请求参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| tenantId | string | 是 | 租户ID |
|
||
| paymentIds | array | 是 | 支付ID数组 |
|
||
| action | string | 是 | 操作类型：SYNC_STATUS、CANCEL |
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"success": 5,
|
||
"failed": 0
|
||
}
|
||
```
|
||
|
||
### 3.9 生成对账报表
|
||
|
||
**请求路径**：`GET /api/payments/reconciliation-report`
|
||
|
||
**查询参数**：
|
||
|
||
| 参数名 | 类型 | 必填 | 描述 |
|
||
|-------|------|------|------|
|
||
| tenantId | string | 是 | 租户ID |
|
||
| startDate | string | 是 | 开始日期，格式：YYYY-MM-DD |
|
||
| endDate | string | 是 | 结束日期，格式：YYYY-MM-DD |
|
||
|
||
**响应格式**：
|
||
|
||
```json
|
||
{
|
||
"tenantId": "tenant-1",
|
||
"period": {
|
||
"startDate": "2026-03-01",
|
||
"endDate": "2026-03-31"
|
||
},
|
||
"summary": {
|
||
"totalPayments": 300,
|
||
"successfulPayments": 250,
|
||
"totalPaymentAmount": 30000,
|
||
"totalRefunds": 50,
|
||
"successfulRefunds": 45,
|
||
"totalRefundAmount": 5000,
|
||
"netAmount": 25000
|
||
},
|
||
"dailyResults": [
|
||
{
|
||
"date": "2026-03-01",
|
||
"payments": {
|
||
"total": 10,
|
||
"successful": 8,
|
||
"pending": 1,
|
||
"failed": 1,
|
||
"totalAmount": 1000
|
||
},
|
||
"refunds": {
|
||
"total": 2,
|
||
"successful": 2,
|
||
"totalAmount": 200
|
||
},
|
||
"netAmount": 800
|
||
}
|
||
],
|
||
"generatedAt": "2026-03-31T23:59:59Z"
|
||
}
|
||
```
|
||
|
||
## 4. 数据模型
|
||
|
||
### 4.1 支付记录 (cf_payments)
|
||
|
||
| 字段名 | 类型 | 描述 |
|
||
|-------|------|------|
|
||
| id | string | 支付ID，格式：PAY-时间戳-随机数 |
|
||
| tenant_id | string | 租户ID |
|
||
| order_id | string | 订单ID |
|
||
| amount | decimal(10,2) | 支付金额 |
|
||
| currency | string | 货币类型 |
|
||
| payment_method | string | 支付方式 |
|
||
| status | string | 支付状态：PENDING、SUCCESS、FAILED |
|
||
| transaction_id | string | 交易ID |
|
||
| redirect_url | string | 支付跳转URL |
|
||
| qr_code_url | string | 二维码URL |
|
||
| metadata | text | 附加信息，JSON格式 |
|
||
| created_at | datetime | 创建时间 |
|
||
| updated_at | datetime | 更新时间 |
|
||
|
||
### 4.2 退款记录 (cf_refunds)
|
||
|
||
| 字段名 | 类型 | 描述 |
|
||
|-------|------|------|
|
||
| id | string | 退款ID，格式：REFUND-时间戳-随机数 |
|
||
| tenant_id | string | 租户ID |
|
||
| payment_id | string | 支付ID |
|
||
| order_id | string | 订单ID |
|
||
| amount | decimal(10,2) | 退款金额 |
|
||
| currency | string | 货币类型 |
|
||
| status | string | 退款状态：PENDING、SUCCESS、FAILED |
|
||
| reason | string | 退款原因 |
|
||
| transaction_id | string | 退款交易ID |
|
||
| created_at | datetime | 创建时间 |
|
||
| updated_at | datetime | 更新时间 |
|
||
|
||
## 5. 错误处理
|
||
|
||
| 错误码 | 描述 |
|
||
|-------|------|
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未授权 |
|
||
| 404 | 支付记录不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
## 6. 性能指标
|
||
|
||
- **支付创建响应时间**：< 1秒
|
||
- **支付状态查询响应时间**：< 500ms
|
||
- **支付列表查询响应时间**：< 1秒
|
||
- **支付统计响应时间**：< 2秒
|
||
- **对账响应时间**：< 3秒
|
||
|
||
## 7. 安全注意事项
|
||
|
||
- 支付回调必须验证签名，确保回调的真实性
|
||
- 敏感信息（如支付凭证）不应存储在数据库中
|
||
- 所有API请求必须进行身份验证和权限检查
|
||
- 支付相关操作应记录详细的审计日志
|
||
|
||
## 8. 集成示例
|
||
|
||
### 8.1 创建支付示例
|
||
|
||
```javascript
|
||
// 前端调用示例
|
||
async function createPayment() {
|
||
const response = await fetch('/api/payments', {
|
||
method: 'POST',
|
||
headers: {
|
||
'Content-Type': 'application/json',
|
||
'Authorization': 'Bearer YOUR_TOKEN'
|
||
},
|
||
body: JSON.stringify({
|
||
tenantId: 'tenant-1',
|
||
orderId: 'order-123',
|
||
amount: 100,
|
||
currency: 'USD',
|
||
paymentMethod: 'ALIPAY',
|
||
returnUrl: 'https://example.com/return',
|
||
notifyUrl: 'https://example.com/notify'
|
||
})
|
||
});
|
||
|
||
const result = await response.json();
|
||
if (result.paymentId) {
|
||
// 跳转到支付页面或显示二维码
|
||
window.location.href = result.redirectUrl;
|
||
}
|
||
}
|
||
```
|
||
|
||
### 8.2 处理支付回调示例
|
||
|
||
```javascript
|
||
// 后端处理回调示例
|
||
app.post('/api/payments/callback', async (req, res) => {
|
||
try {
|
||
const callbackData = req.body;
|
||
const success = await PaymentService.handleCallback(callbackData);
|
||
res.json({ success });
|
||
} catch (error) {
|
||
res.status(500).json({ success: false, error: error.message });
|
||
}
|
||
});
|
||
```
|
||
|
||
## 9. 总结
|
||
|
||
支付服务 API 提供了完整的支付处理功能，支持多种支付渠道，满足不同场景的支付需求。通过合理的缓存机制和异步处理，确保了支付处理的高效性和可靠性。
|