充值与订阅套餐配置
支付通道打通之后(见 Z-Pay 支付宝收款配置),站点可以出售两种形态的商品:余额充值和订阅套餐。两者的计费模型完全不同,先分清楚再定价,否则很容易把两个换算汇率配反。
计费链路的内部机制(Preflight 检查顺序、余额扣减、订阅窗口)见计费与配额;本文只讲运营侧怎么配置和定价。
两种商品形态
| 余额充值 | 订阅套餐 | |
|---|---|---|
| 用户买到什么 | USD 余额,按量计费,用完为止 | 某个分组(Group)的限时使用权 |
| 额度约束 | 余额扣完不能再用 | 分组上的日 / 周 / 月 USD 限额,窗口自动重置 |
| 是否过期 | 不过期 | 有效期(天/周/月)到期失效 |
| 配置位置 | 支付设置(全局参数,无需建商品) | 分组管理(权益)+ 订阅套餐管理(售卖信息) |
| 扣费关系 | 请求没有可用订阅时才检查并扣余额 | 请求优先消耗有效订阅的窗口额度,不动余额 |
用户同时持有余额和订阅时,请求按「有效订阅优先,余额兜底」的顺序结算,所以两种商品可以并存出售,也可以打开「禁用余额充值」只卖订阅。
OneSeat AI 前端（C 端）注意
OneSeat AI 充值页展示的档位（¥9.9 入门包、¥39/¥79/¥149、滑块上限 ¥1000）是前端预设，不在后台配置，改面额需改前端仓库 app/modules/payment/presets.ts 并发版。除此之外的一切——倍率、手续费、限额、套餐——都在本文所述的后台位置配置，前端实时跟随。详见前端仓库 支付集成设计.md §3.3 改价操作指南。
余额充值配置
位置:管理后台 → 系统设置 → 支付设置。充值不需要创建商品,用户在充值页自行输入金额,系统按以下参数结算:
| 配置项 | 作用 | 定价含义 |
|---|---|---|
| 余额充值倍率 | 每支付 1 CNY 到账多少 USD 余额 | 这就是余额的售价。界面有实时预览,如填 0.14 即 1 CNY = 0.14 USD,折合约 7.14 CNY/USD |
| 充值手续费率 | 在支付金额上加收的百分比,0 为不收 | 用于覆盖支付通道费率(Z-Pay 等聚合平台通常抽 2%~4%) |
| 最低金额 / 最高金额 / 每日限额 | 单笔与每日充值上限 | 最低金额别设太低,通道有单笔下限;验收测试时可临时调低 |
| 最大待支付订单数 / 订单超时时间 | 防刷单参数 | 超时订单自动过期,晚到的成功通知仍有有限宽限处理 |
| 禁用余额充值 | 关闭余额售卖 | 只做订阅制站点时打开 |
定价时把三层成本算进倍率:上游账号成本、分组费率倍率(用户侧计费 = 模型价 × 分组倍率)、支付通道手续费。
订阅套餐配置
一个订阅套餐 = 「买多久 + 多少钱 + 进哪个分组」。额度权益不在套餐上,而在分组上——套餐只是分组使用权的售卖包装。所以配置分两步:
第一步:在分组上定义权益
位置:管理后台 → 分组管理。为要出售的分组设置:
- 日限额 / 周限额 / 月限额(USD):订阅用户在对应窗口内可消耗的用量上限,按自然日零点重置,三个都可以留空(不限)。「订阅是每天能用多少 USD」指的就是这里的日限额。
- 费率倍率、平台、可用模型、专属分组等常规分组配置(见分组、渠道与模型)。
建议出售的分组与免费/内部分组隔离,一个套餐档位对应一个独立分组,权益调整互不影响。
用量按「模型计费价 × 分组倍率」折算成 USD 累计;窗口打满后该订阅拒绝请求,直到窗口重置。管理员可在用户订阅详情中手动重置日/周/月窗口(处理投诉或补偿时用)。
第二步:创建订阅套餐
位置:管理后台 → 订单管理 → 订阅套餐(订阅套餐管理页)。字段:
| 字段 | 说明 |
|---|---|
| 套餐名称 / 套餐描述 | 展示给用户的商品信息 |
| 分组 | 购买后用户获得哪个分组的订阅 |
| 价格 | 实际收款定价,币种含义见下节「两个汇率」 |
| 原价 | 仅展示用的划线价,可不填 |
| 有效期 + 有效期单位 | 数字 + 天/周/月,如 30 天、1 月 |
| 功能特性 | 每行一个卖点,渲染成套餐卡片的权益列表 |
| 上架状态 / 排序 | 控制充值页是否展示及展示顺序 |
支付成功后系统自动履约:给用户分配或顺延该分组的订阅(已持有同分组订阅时到期时间顺延,不会作废重算),写入审计日志并发送订阅成功邮件;重复的支付通知有幂等保护,不会重复加时长。履约失败的订单可在后台订单详情「重试履约」。
两个汇率,方向相反,别配反
| 配置项 | 方向 | 影响范围 |
|---|---|---|
| 余额充值倍率 | CNY → USD:1 CNY 买多少 USD 余额 | 只影响余额充值 |
| 订阅 CNY 换算汇率 | USD → CNY:套餐每 1 USD 价格收多少 CNY | 只影响 CNY 通道下的订阅收款 |
「订阅 CNY 换算汇率」决定套餐「价格」字段的币种语义,全站二选一:
- 按 CNY 定价(推荐,最简单):汇率填
0或留空,套餐价格直接按 CNY 数值收款。价格填30就是收 30 元。 - 按 USD 定价:汇率填换算值(如
7.15),所有套餐价格一律按 USD 填写,走支付宝/微信/易支付等 CNY 通道时按汇率折算收款。价格填10、汇率7.15,实收 71.5 元(手续费另算)。
**开启换算后所有套餐的价格都必须按 USD 定价,不能混用。**套餐编辑框里有「CNY 通道实扣预览」,保存前先看预览金额对不对。
只接了 Z-Pay(纯 CNY 通道)的站点,建议直接按 CNY 定价、汇率留 0;将来接入 Stripe 等外币通道再考虑切换 USD 定价。
验收清单
- 建一个测试分组(日限额设小,如 0.5 USD)和一个绑定它的低价测试套餐并上架。
- 用测试账号购买:确认收款金额与「CNY 通道实扣预览」一致(含手续费)。
- 支付成功后,用户中心应出现该订阅及正确到期时间,并收到订阅成功邮件(如已配邮件)。
- 用该账号发请求:确认消耗的是订阅窗口额度,余额不变。
- 打满日限额:请求应被拒绝,次日零点(或管理员手动重置)后恢复。
- 再买一次同套餐:到期时间应顺延,而不是重置。
- 验收后下架测试套餐,把测试分组停用或清理。
常见问题
| 现象 | 原因 |
|---|---|
| 充值页看不到套餐 | 套餐未上架;支付系统未启用;套餐绑定的分组已停用 |
| 套餐收款金额不对 | 「订阅 CNY 换算汇率」与价格币种语义不匹配(按 CNY 定价却填了汇率,或反之);手续费率漏算 |
| 用户买了订阅仍扣余额 | 请求没有命中订阅分组(API Key 所属分组与订阅分组不一致),按余额兜底结算 |
| 订阅购买成功但未生效 | 履约失败(如分组已停用),订单会停在失败态,后台订单详情「重试履约」;排查见计费 Runbook |
| 改了分组限额,老用户没变化 | 限额是分组属性,即时生效;但当前窗口已累计的用量不会回退,等窗口重置后按新限额执行 |