cozsweet-frontend-nextjs/docs/backend/FRONTEND_TIP_PAYMENT_API.md

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. 查询打赏品类

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

成功响应：

{
  "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. 创建打赏订单

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。

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

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

支付完成后：

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