makemd/archive/handover/payment-api.md

支付服务 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格式

响应格式：

{
  "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	是	签名，用于验证回调真实性

响应格式：

{
  "success": true
}

3.3 发起退款

请求路径：POST /api/payments/refund

请求参数：

参数名	类型	必填	描述
tenantId	string	是	租户ID
paymentId	string	是	支付ID
orderId	string	是	订单ID
amount	number	是	退款金额
reason	string	是	退款原因

响应格式：

{
  "refundId": "REFUND-1234567890-12345"
}

3.4 查询支付状态

请求路径：GET /api/payments/{paymentId}/status

响应格式：

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

响应格式：

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

响应格式：

{
  "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	否	支付方式过滤

响应格式：

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

响应格式：

{
  "success": 5,
  "failed": 0
}

3.9 生成对账报表

请求路径：GET /api/payments/reconciliation-report

查询参数：

参数名	类型	必填	描述
tenantId	string	是	租户ID
startDate	string	是	开始日期，格式：YYYY-MM-DD
endDate	string	是	结束日期，格式：YYYY-MM-DD

响应格式：

{
  "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 创建支付示例

// 前端调用示例
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 处理支付回调示例

// 后端处理回调示例
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 提供了完整的支付处理功能，支持多种支付渠道，满足不同场景的支付需求。通过合理的缓存机制和异步处理，确保了支付处理的高效性和可靠性。