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

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

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

### 1.1 创建订单
*   **URL**: `POST /api/payment/create_order`
*   **Description**: 业务系统通知支付模块创建一个待支付订单。
*   **Request Body**:
    \`\`\`json
    {
      "user_id": "u1001",           // 用户ID
      "title": "VIP Membership",    // 订单标题
      "amount": 99.00,              // 金额 (法币单位: 元 / 美元)
      "currency": "CNY",            // 币种: CNY, USD
      "product_id": "vip_01",       // 商品ID
      "extra_params": {}            // 扩展参数
    }
    \`\`\`
*   **Response**:
    \`\`\`json
    {
      "code": 200,
      "data": {
        "order_sn": "202310270001", // 支付系统生成的唯一订单号
        "status": "created"
      }
    }
    \`\`\`

### 1.2 发起支付 (收银台)
*   **URL**: `POST /api/payment/checkout`
*   **Description**: 用户选择支付方式后，获取支付参数。
*   **Request Body**:
    \`\`\`json
    {
      "order_sn": "202310270001",
      "gateway": "alipay_qr",       // 支付方式: alipay_qr, wechat_jsapi, paypal, usdt, stripe
      "return_url": "https://...",  // 支付成功后前端跳转地址
      "openid": "..."               // 微信JSAPI支付必填
    }
    \`\`\`
*   **Response**:
    \`\`\`json
    {
      "code": 200,
      "data": {
        "type": "url",              // url (跳转), qrcode (扫码), json (SDK参数), address (USDT)
        "payload": "https://...",   // 具体内容
        "expiration": 1800          // 过期时间(秒)
      }
    }
    \`\`\`

### 1.3 查询订单状态
*   **URL**: `GET /api/payment/status/{order_sn}`
*   **Description**: 前端轮询使用。
*   **Response**:
    \`\`\`json
    {
      "code": 200,
      "data": {
        "status": "paid",           // created, paying, paid, closed
        "paid_amount": 99.00,
        "paid_at": "2023-10-27 10:00:00"
      }
    }
    \`\`\`

---

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

### 2.1 统一回调入口
*   **URL**: `POST /api/payment/notify/{gateway}`
*   **Description**: 接收第三方支付平台的异步通知。
*   **Path Params**:
    *   `gateway`: `alipay`, `wechat`, `paypal`, `stripe`, `nowpayments`
*   **Logic**:
    1.  根据 gateway 加载对应驱动。
    2.  验签 (Verify Signature)。
    3.  幂等性检查 (Idempotency Check)。
    4.  更新订单状态。
    5.  返回平台所需的响应字符串 (e.g. `success`, `200 OK`).

---

## 3. 辅助接口

### 3.1 获取汇率
*   **URL**: `GET /api/payment/exchange_rate`
*   **Params**: `from=USD&to=CNY`
*   **Response**: `{"rate": 7.21}`
