soul/addons/Universal_Payment_Module copy/1_核心设计_通用协议/API接口定义.md

# 通用支付模块 API 接口定义 (Universal Payment API) v4.0

> 无论后端使用何种语言（Python/Node/Go/Java/PHP），请严格实现以下 RESTful 接口

## 🎯 设计原则

1. **RESTful 风格**: 资源命名统一，动词语义清晰
2. **统一响应格式**: 所有接口返回 `{code, message, data}` 结构
3. **幂等性**: 重复请求不产生副作用
4. **安全性**: 敏感操作需签名验证

---

## 📦 统一响应格式

### 成功响应
```json
{
  "code": 200,
  "message": "success",
  "data": { ... }
}
```

### 错误响应
```json
{
  "code": 400,
  "message": "参数错误：order_sn 不能为空",
  "data": null
}
```

### 常用错误码
| Code | 含义 |
|:---|:---|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权/登录过期 |
| 403 | 无权限 |
| 404 | 资源不存在 |
| 409 | 状态冲突 (如重复支付) |
| 500 | 服务器内部错误 |

---

## 1. 核心交易接口 (Core Transaction)

### 1.1 创建订单
业务系统调用，创建一个待支付订单。

```http
POST /api/payment/create_order
Content-Type: application/json
Authorization: Bearer {token}
```

**Request Body**:
```json
{
  "user_id": "u1001",             // [必填] 用户ID
  "title": "VIP会员月卡",          // [必填] 订单标题 (≤30字符)
  "amount": 99.00,                // [必填] 金额 (单位: 元)
  "currency": "CNY",              // [可选] 币种，默认 CNY
  "product_id": "vip_monthly",    // [可选] 商品ID
  "product_type": "membership",   // [可选] 商品类型
  "extra_params": {               // [可选] 扩展参数 (会透传到回调)
    "coupon_id": "C001",
    "referrer": "user_123"
  }
}
```

**Response**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "order_sn": "202401170001",   // 系统生成的订单号
    "status": "created",          // 订单状态
    "amount": 99.00,
    "expire_at": "2024-01-17T11:30:00Z"  // 订单过期时间
  }
}
```

---

### 1.2 发起支付 (收银台)
用户选择支付方式后，获取支付参数。

```http
POST /api/payment/checkout
Content-Type: application/json
Authorization: Bearer {token}
```

**Request Body**:
```json
{
  "order_sn": "202401170001",     // [必填] 订单号
  "gateway": "wechat_jsapi",      // [必填] 支付网关 (见下方枚举)
  "return_url": "https://...",    // [可选] 支付成功后跳转地址
  "openid": "oXxx...",            // [条件] 微信JSAPI必填
  "coin_amount": 0                // [可选] 使用虚拟币抵扣金额
}
```

**Gateway 支付网关枚举**:
| Gateway | 说明 | 返回类型 |
|:---|:---|:---|
| `alipay_web` | 支付宝PC网页 | url (跳转) |
| `alipay_wap` | 支付宝H5 | url (跳转) |
| `alipay_qr` | 支付宝扫码 | qrcode |
| `wechat_native` | 微信扫码 | qrcode |
| `wechat_jsapi` | 微信公众号/小程序 | json (SDK参数) |
| `wechat_h5` | 微信H5 | url (跳转) |
| `wechat_app` | 微信APP | json (SDK参数) |
| `paypal` | PayPal | url (跳转) |
| `stripe` | Stripe | url (Checkout Session) |
| `usdt` | USDT-TRC20 | address (钱包地址) |
| `coin` | 纯虚拟币支付 | direct (直接完成) |

**Response**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "trade_sn": "T20240117100001",  // 交易流水号
    "type": "qrcode",               // 响应类型: url/qrcode/json/address/direct
    "payload": "weixin://wxpay/...",// 支付数据 (根据type不同)
    "expiration": 1800,             // 过期时间 (秒)
    "amount": 99.00,                // 实际支付金额 (扣除抵扣后)
    "coin_deducted": 0              // 虚拟币抵扣金额
  }
}
```

**不同 type 的 payload 格式**:

```javascript
// type: "url" - 跳转链接
payload: "https://openapi.alipay.com/gateway.do?..."

// type: "qrcode" - 二维码内容
payload: "weixin://wxpay/bizpayurl?pr=xxx"

// type: "json" - SDK调起参数 (微信JSAPI)
payload: {
  "appId": "wx...",
  "timeStamp": "1705470600",
  "nonceStr": "xxx",
  "package": "prepay_id=wx...",
  "signType": "RSA",
  "paySign": "xxx"
}

// type: "address" - 加密货币地址
payload: {
  "address": "TXxx...",
  "amount_usdt": 13.88,
  "memo": "202401170001"
}

// type: "direct" - 直接完成 (纯虚拟币支付)
payload: { "status": "paid" }
```

---

### 1.3 查询订单状态
前端轮询使用，判断支付是否完成。

```http
GET /api/payment/status/{order_sn}
Authorization: Bearer {token}
```

**Response**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "order_sn": "202401170001",
    "status": "paid",              // created/paying/paid/closed/refunded
    "paid_amount": 99.00,
    "paid_at": "2024-01-17T10:05:00Z",
    "payment_method": "wechat_jsapi",
    "trade_sn": "T20240117100001"
  }
}
```

**订单状态机**:
```
created → paying → paid → (refunded)
    ↓        ↓
  closed   closed
```

---

### 1.4 关闭订单
主动关闭未支付的订单。

```http
POST /api/payment/close/{order_sn}
Authorization: Bearer {token}
```

**Response**:
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "order_sn": "202401170001",
    "status": "closed",
    "closed_at": "2024-01-17T10:10:00Z"
  }
}
```

---

## 2. 回调通知接口 (Webhook)

### 2.1 统一回调入口
接收第三方支付平台的异步通知。

```http
POST /api/payment/notify/{gateway}
```

**Path Params**:
- `gateway`: `alipay` / `wechat` / `paypal` / `stripe` / `nowpayments`

**处理逻辑**:
1. 根据 gateway 加载对应驱动
2. 验签 (Verify Signature)
3. 幂等性检查 (防重复处理)
4. 更新订单状态
5. 触发业务回调 (发货/开通权限等)
6. 返回平台所需响应

**返回格式**:
```
# 支付宝
success

# 微信
<xml><return_code><![CDATA[SUCCESS]]></return_code><return_msg><![CDATA[OK]]></return_msg></xml>

# Stripe
HTTP 200 OK

# PayPal
HTTP 200 OK
```

---

### 2.2 同步返回 (Return)
用户支付完成后的页面跳转。

```http
GET /api/payment/return/{gateway}
```

**Query Params**: 各平台不同，由平台自动附加

**处理逻辑**:
1. 解析回传参数
2. 验签
3. 重定向到成功页面

---

## 3. 辅助接口

### 3.1 获取可用支付方式
```http
GET /api/payment/methods
```

**Response**:
```json
{
  "code": 200,
  "data": {
    "methods": [
      {
        "gateway": "wechat_jsapi",
        "name": "微信支付",
        "icon": "/icons/wechat.png",
        "enabled": true,
        "available": true  // 当前环境是否可用 (如微信内)
      },
      {
        "gateway": "alipay_wap",
        "name": "支付宝",
        "icon": "/icons/alipay.png",
        "enabled": true,
        "available": true
      }
    ]
  }
}
```

### 3.2 获取汇率
```http
GET /api/payment/exchange_rate?from=CNY&to=USD
```

**Response**:
```json
{
  "code": 200,
  "data": {
    "from": "CNY",
    "to": "USD",
    "rate": 0.139,
    "updated_at": "2024-01-17T00:00:00Z"
  }
}
```

---

## 4. 管理接口 (Admin)

### 4.1 订单列表
```http
GET /api/admin/payment/orders?page=1&limit=20&status=paid
Authorization: Bearer {admin_token}
```

### 4.2 交易流水列表
```http
GET /api/admin/payment/trades?page=1&limit=20
Authorization: Bearer {admin_token}
```

### 4.3 发起退款
```http
POST /api/admin/payment/refund
Authorization: Bearer {admin_token}
Content-Type: application/json

{
  "trade_sn": "T20240117100001",
  "amount": 99.00,
  "reason": "用户申请退款"
}
```

---

## 5. 接口签名规范 (可选)

对于安全要求高的场景，可启用接口签名：

```javascript
// 请求头
X-Sign: sha256(timestamp + nonce + body + secret)
X-Timestamp: 1705470600
X-Nonce: abc123
```

---

## 📌 注意事项

1. **金额单位**: 所有金额均以**元**为单位，小数点后2位
2. **时间格式**: ISO 8601 格式 `YYYY-MM-DDTHH:mm:ssZ`
3. **字符编码**: UTF-8
4. **HTTPS**: 生产环境必须使用 HTTPS
5. **幂等性**: 相同订单号重复请求返回相同结果