# Cozsweet 咖啡打赏接口

## 1. 用途

前端展示三个一次性咖啡打赏档位，并复用现有支付建单、支付跳转和订单轮询流程。

## 2. 接口地址

| 功能 | 方法 | 路径 | 鉴权 |
| --- | --- | --- | --- |
| 查询打赏品类 | GET | `/api/payment/tip-plans` | 不需要 |
| 创建打赏订单 | POST | `/api/payment/create-order` | Bearer Token |
| 查询订单状态 | GET | `/api/payment/order-status?order_id=...` | Bearer Token |

## 3. 查询打赏品类

```bash
curl 'https://api.banlv-ai.com/api/payment/tip-plans'
```

成功响应：

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "plans": [
      {
        "planId": "tip_coffee_usd_4_99",
        "planName": "Small Coffee",
        "orderType": "tip",
        "tipType": "coffee_small",
        "description": "Buy Elio a small coffee",
        "amountCents": 499,
        "currency": "USD",
        "autoRenew": false,
        "isFirstRechargeOffer": false,
        "firstRechargeDiscountPercent": 0
      },
      {
        "planId": "tip_coffee_usd_9_99",
        "planName": "Medium Coffee",
        "orderType": "tip",
        "tipType": "coffee_medium",
        "description": "Buy Elio a medium coffee",
        "amountCents": 999,
        "currency": "USD",
        "autoRenew": false,
        "isFirstRechargeOffer": false,
        "firstRechargeDiscountPercent": 0
      },
      {
        "planId": "tip_coffee_usd_19_99",
        "planName": "Large Coffee",
        "orderType": "tip",
        "tipType": "coffee_large",
        "description": "Buy Elio a large coffee",
        "amountCents": 1999,
        "currency": "USD",
        "autoRenew": false,
        "isFirstRechargeOffer": false,
        "firstRechargeDiscountPercent": 0
      }
    ]
  }
}
```

当前三个档位如下，顺序就是接口返回顺序：

| `planId` | `tipType` | 价格 |
| --- | --- | ---: |
| `tip_coffee_usd_4_99` | `coffee_small` | USD 4.99 |
| `tip_coffee_usd_9_99` | `coffee_medium` | USD 9.99 |
| `tip_coffee_usd_19_99` | `coffee_large` | USD 19.99 |

三个档位都不按国家换币、不参与首充半价，也不发会员或积分。前端必须使用接口返回的 `planId`，不要根据价格自行拼接。

## 4. 创建打赏订单

```bash
curl -X POST 'https://api.banlv-ai.com/api/payment/create-order' \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "planId": "tip_coffee_usd_9_99",
    "payChannel": "stripe",
    "autoRenew": false
  }'
```

| 字段 | 类型 | 必填 | 固定/可选值 | 说明 |
| --- | --- | --- | --- | --- |
| `planId` | string | 是 | 上表三个 ID 之一 | 咖啡打赏产品 ID。 |
| `payChannel` | string | 是 | `stripe` / `ezpay` | 支付渠道。 |
| `autoRenew` | boolean | 是 | `false` | 打赏是一次性支付，必须传 false。 |

成功响应与现有充值相同：

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "orderId": "pay_xxx",
    "payParams": {
      "url": "https://checkout.example/..."
    },
    "expiresAt": "2026-07-14T10:30:00+00:00",
    "expiresInSeconds": 1800
  }
}
```

前端必须打开 `payParams` 中的支付 URL，并每 3-5 秒轮询订单状态。

## 5. 订单状态与 WebSocket

支付完成后：

```json
{
  "orderId": "pay_xxx",
  "status": "paid",
  "orderType": "tip",
  "planId": "tip_coffee_usd_9_99",
  "creditsAdded": 0
}
```