aiotagro/jiebanke
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
467a4ead105227749cc600e660a04e4dce1121f9
jiebanke/docs/支付系统API文档.md

8.5 KiB
Raw Blame History

支付系统API文档

概述

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

基础信息

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

数据模型

支付订单 (Payment)

{
  "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)

{
  "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

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

请求参数:

{
  "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 (可选): 支付成功回调地址

响应示例:

{
  "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

响应示例:

{
  "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: 支付订单号

响应示例:

{
  "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

请求参数:

{
  "refund_amount": 100.00,
  "refund_reason": "商品质量问题"
}

参数说明:

  • refund_amount (必填): 退款金额
  • refund_reason (必填): 退款原因

响应示例:

{
  "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

响应示例:

{
  "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

请求参数:

{
  "status": "approved",
  "process_remark": "同意退款申请"
}

参数说明:

  • status (必填): 退款状态 (approved/rejected/completed)
  • process_remark (可选): 处理备注

响应示例:

{
  "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 (可选): 支付方式

响应示例:

{
  "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小时后自动取消

集成示例

创建支付订单示例

// 创建支付订单
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);
  }
};

查询支付状态示例

// 轮询查询支付状态
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);
  }
};