jiebanke/docs/支付系统API文档.md

# 支付系统API文档

## 概述

支付系统提供完整的支付流程管理，包括支付订单创建、状态查询、退款处理等功能。支持微信支付、支付宝支付和余额支付三种支付方式。

## 基础信息

- **基础URL**: `/api/v1/payments`
- **认证方式**: Bearer Token
- **数据格式**: JSON

## 数据模型

### 支付订单 (Payment)

```json
{
  "id": 1,
  "payment_no": "PAY202401010001",
  "order_id": 1,
  "user_id": 1,
  "amount": 299.00,
  "paid_amount": 299.00,
  "payment_method": "wechat",
  "status": "paid",
  "transaction_id": "wx_transaction_123",
  "paid_at": "2024-01-01T10:00:00Z",
  "created_at": "2024-01-01T09:00:00Z",
  "updated_at": "2024-01-01T10:00:00Z"
}
```

### 退款记录 (Refund)

```json
{
  "id": 1,
  "refund_no": "REF202401010001",
  "payment_id": 1,
  "user_id": 1,
  "refund_amount": 100.00,
  "refund_reason": "用户申请退款",
  "status": "completed",
  "processed_by": 2,
  "process_remark": "同意退款",
  "processed_at": "2024-01-01T11:00:00Z",
  "refunded_at": "2024-01-01T11:30:00Z",
  "created_at": "2024-01-01T10:30:00Z"
}
```

## API接口

### 1. 创建支付订单

**接口**: `POST /api/v1/payments`

**描述**: 为订单创建支付订单

**请求参数**:
```json
{
  "order_id": 1,
  "amount": 299.00,
  "payment_method": "wechat",
  "return_url": "https://example.com/success"
}
```

**参数说明**:
- `order_id` (必填): 订单ID
- `amount` (必填): 支付金额
- `payment_method` (必填): 支付方式 (wechat/alipay/balance)
- `return_url` (可选): 支付成功回调地址

**响应示例**:
```json
{
  "success": true,
  "message": "支付订单创建成功",
  "data": {
    "id": 1,
    "payment_no": "PAY202401010001",
    "order_id": 1,
    "amount": 299.00,
    "payment_method": "wechat",
    "status": "pending",
    "payment_params": {
      "prepay_id": "wx_prepay_123",
      "code_url": "weixin://wxpay/bizpayurl?pr=abc123"
    }
  }
}
```

### 2. 获取支付订单详情

**接口**: `GET /api/v1/payments/{paymentId}`

**描述**: 获取指定支付订单的详细信息

**路径参数**:
- `paymentId`: 支付订单ID

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "payment_no": "PAY202401010001",
    "order_id": 1,
    "user_id": 1,
    "amount": 299.00,
    "paid_amount": 299.00,
    "payment_method": "wechat",
    "status": "paid",
    "transaction_id": "wx_transaction_123",
    "paid_at": "2024-01-01T10:00:00Z",
    "order_no": "ORD202401010001",
    "username": "张三",
    "phone": "13800138000"
  }
}
```

### 3. 查询支付状态

**接口**: `GET /api/v1/payments/query/{paymentNo}`

**描述**: 根据支付订单号查询支付状态

**路径参数**:
- `paymentNo`: 支付订单号

**响应示例**:
```json
{
  "success": true,
  "data": {
    "payment_no": "PAY202401010001",
    "status": "paid",
    "amount": 299.00,
    "paid_at": "2024-01-01T10:00:00Z",
    "transaction_id": "wx_transaction_123"
  }
}
```

### 4. 支付回调接口

#### 微信支付回调

**接口**: `POST /api/v1/payments/callback/wechat`

**描述**: 微信支付异步通知接口

**请求格式**: XML

**响应格式**: XML

#### 支付宝回调

**接口**: `POST /api/v1/payments/callback/alipay`

**描述**: 支付宝异步通知接口

**请求格式**: Form Data

**响应格式**: 文本 (success/fail)

### 5. 申请退款

**接口**: `POST /api/v1/payments/{paymentId}/refund`

**描述**: 为已支付的订单申请退款

**路径参数**:
- `paymentId`: 支付订单ID

**请求参数**:
```json
{
  "refund_amount": 100.00,
  "refund_reason": "商品质量问题"
}
```

**参数说明**:
- `refund_amount` (必填): 退款金额
- `refund_reason` (必填): 退款原因

**响应示例**:
```json
{
  "success": true,
  "message": "退款申请提交成功",
  "data": {
    "id": 1,
    "refund_no": "REF202401010001",
    "payment_id": 1,
    "refund_amount": 100.00,
    "refund_reason": "商品质量问题",
    "status": "pending",
    "created_at": "2024-01-01T10:30:00Z"
  }
}
```

### 6. 获取退款详情

**接口**: `GET /api/v1/payments/refunds/{refundId}`

**描述**: 获取退款记录详情

**路径参数**:
- `refundId`: 退款ID

**响应示例**:
```json
{
  "success": true,
  "data": {
    "id": 1,
    "refund_no": "REF202401010001",
    "payment_id": 1,
    "refund_amount": 100.00,
    "refund_reason": "商品质量问题",
    "status": "completed",
    "processed_by": 2,
    "process_remark": "同意退款",
    "processed_at": "2024-01-01T11:00:00Z",
    "refunded_at": "2024-01-01T11:30:00Z",
    "payment_no": "PAY202401010001",
    "username": "张三",
    "processed_by_name": "管理员"
  }
}
```

### 7. 处理退款（管理员）

**接口**: `PUT /api/v1/payments/refunds/{refundId}/process`

**描述**: 管理员处理退款申请

**权限**: 管理员

**路径参数**:
- `refundId`: 退款ID

**请求参数**:
```json
{
  "status": "approved",
  "process_remark": "同意退款申请"
}
```

**参数说明**:
- `status` (必填): 退款状态 (approved/rejected/completed)
- `process_remark` (可选): 处理备注

**响应示例**:
```json
{
  "success": true,
  "message": "退款处理成功",
  "data": {
    "id": 1,
    "refund_no": "REF202401010001",
    "status": "approved",
    "processed_by": 2,
    "process_remark": "同意退款申请",
    "processed_at": "2024-01-01T11:00:00Z"
  }
}
```

### 8. 获取支付统计信息（管理员）

**接口**: `GET /api/v1/payments/statistics`

**描述**: 获取支付相关的统计信息

**权限**: 管理员

**查询参数**:
- `start_date` (可选): 开始日期 (YYYY-MM-DD)
- `end_date` (可选): 结束日期 (YYYY-MM-DD)
- `payment_method` (可选): 支付方式

**响应示例**:
```json
{
  "success": true,
  "data": {
    "total_count": 100,
    "total_amount": 29900.00,
    "success_count": 85,
    "success_amount": 25415.00,
    "refund_count": 5,
    "refund_amount": 1500.00,
    "method_stats": [
      {
        "payment_method": "wechat",
        "count": 50,
        "amount": 15000.00
      },
      {
        "payment_method": "alipay",
        "count": 35,
        "amount": 10415.00
      }
    ]
  }
}
```

## 状态说明

### 支付状态 (Payment Status)

- `pending`: 待支付
- `paid`: 已支付
- `failed`: 支付失败
- `refunded`: 已退款
- `cancelled`: 已取消

### 退款状态 (Refund Status)

- `pending`: 待处理
- `approved`: 已同意
- `rejected`: 已拒绝
- `completed`: 已完成

## 支付方式

- `wechat`: 微信支付
- `alipay`: 支付宝支付
- `balance`: 余额支付

## 错误码说明

| 错误码 | 说明 |
|--------|------|
| 400 | 参数错误 |
| 401 | 未授权 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

## 注意事项

1. **安全性**: 所有支付相关接口都需要用户认证
2. **权限控制**: 用户只能操作自己的支付订单和退款记录
3. **金额精度**: 所有金额字段保留两位小数
4. **回调验证**: 支付回调需要验证签名确保安全性
5. **幂等性**: 支付订单创建支持幂等性，避免重复创建
6. **超时处理**: 待支付订单会在24小时后自动取消

## 集成示例

### 创建支付订单示例

```javascript
// 创建支付订单
const createPayment = async (orderData) => {
  try {
    const response = await fetch('/api/v1/payments', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        order_id: orderData.orderId,
        amount: orderData.amount,
        payment_method: 'wechat',
        return_url: 'https://example.com/success'
      })
    });
    
    const result = await response.json();
    if (result.success) {
      // 跳转到支付页面或调用支付SDK
      handlePayment(result.data);
    }
  } catch (error) {
    console.error('创建支付订单失败:', error);
  }
};
```

### 查询支付状态示例

```javascript
// 轮询查询支付状态
const checkPaymentStatus = async (paymentNo) => {
  try {
    const response = await fetch(`/api/v1/payments/query/${paymentNo}`, {
      headers: {
        'Authorization': `Bearer ${token}`
      }
    });
    
    const result = await response.json();
    if (result.success) {
      const status = result.data.status;
      if (status === 'paid') {
        // 支付成功处理
        handlePaymentSuccess();
      } else if (status === 'failed') {
        // 支付失败处理
        handlePaymentFailed();
      }
    }
  } catch (error) {
    console.error('查询支付状态失败:', error);
  }
};
```