TokenPay教程：设置按调用量收费与自动补充

2026-10-25技术老齐

我们围绕 TokenPay 的按调用量收费场景，梳理从计费模型、调用次数包、自动补充规则到支付确认和用量扣减的实施路径。本文适合正在接入支付宝 AI 付的 AI Web 应用、AI App、SaaS 后端和 Agent 团队。我们完成配置后，应能让用户购买调用次数包，在服务调用成功后扣减用量，并在余额不足时按规则触发补充或引导支付。

一、TokenPay前期准备：明确计费边界

1.1 适用对象与使用边界

适用场景包括：

面向个人用户提供文本生成、图片处理或智能问答服务的 AI 应用，调用频率会随会员或套餐变化，后端能够记录每次服务调用。
面向企业客户提供 API 或工作台能力的 SaaS 产品，需要按实际调用量核算成本，并能在业务侧保存用户、订单和用量之间的关联关系。
使用 AI Agent 完成多步骤任务的产品，调用次数可能在任务执行过程中持续消耗，团队已具备用量预估、扣减和失败补偿机制。

不适用场景包括：

只收取一次性软件授权费、没有持续调用量的产品。我们建议使用一次性支付或标准商品订单模型。
无法区分调用主体、无法记录调用结果的早期试验项目。我们建议先补齐用户标识、请求日志和计量口径，再接入按量收费。
需要复杂合同结算、线下授信或人工对账的大客户项目。我们建议采用企业合同、账期结算等方案，TokenPay 仅作为线上小额支付补充。

1.2 账号、权限与环境准备

我们在开始配置前准备以下内容：

支付宝开放平台或支付宝 AI 付相关账号，并完成产品所需的主体、应用和权限申请。
明确商品名称、调用单位、计费周期、单次调用的计量口径，以及用户购买后可获得的次数包。
规划用户标识、订单号、支付状态、可用次数、冻结次数和扣减流水等字段。
准备服务端环境，用于创建订单、接收支付结果、查询订单和执行用量扣减；前端只负责展示支付入口和状态。
按官方文档确认 SDK、接口权限和签名配置，避免直接复制其他支付产品的参数。

二、TokenPay核心内容分步实操

2.1 先定义“调用一次”

当前任务是把业务动作转换为稳定的计量单位。我们先确定一次调用对应一次成功的 AI 服务请求，还是按输入输出、任务阶段或资源类型拆分。之所以先做这一步，是因为调用次数包、扣减流水和售后补偿都依赖该口径。

具体做法是：为每次业务请求生成业务请求标识，记录用户、模型或能力类型、开始时间、结束状态和计费单位；只有达到业务成功条件时才扣减。预期结果是同一请求可以被幂等识别，重试不会重复扣费。跳过这一步，后续会出现“支付成功但次数不一致”或失败请求被扣费的问题。

2.2 设计调用次数包与商品关系

当前任务是把 Token Pay按调用量收费落到可购买商品。我们将次数包视为支付商品，将包内次数、适用能力、有效期和补充规则写入商品配置或服务端配置，并保存订单号与用户标识的关联。

这样做的原因是支付系统确认的是订单，业务系统确认的是可用额度，两者必须通过订单号和用户标识关联。预期结果是用户购买后能看到待到账、已到账和已消耗状态。跳过关联设计，退款、补发和客服核对都会缺少依据。

⚠️ 常见错误：支付回调到达后直接给用户增加次数。原因：没有先校验回调的订单状态、订单归属和幂等标识。解决方法：服务端先验签并查询订单状态，再检查该订单是否已入账；已处理的订单直接返回成功，不重复增加次数。

2.3 配置自动补充规则

当前任务是回答“Token Pay按调用量收费如何设置调用次数包的自动补充规则”。我们先选择触发条件，例如可用次数低于业务设定的安全线、用户主动开启自动补充，或一次任务预计消耗超过当前余额。随后配置补充次数包、支付确认方式、失败后的提醒和暂停策略。

我们建议把“预警”和“自动购买”分开：预警只通知用户，自动购买必须有明确授权记录；每次触发都保存触发原因、原余额、购买商品、订单号和最终状态。预期结果是补充动作可追踪、可关闭、可重试。跳过授权和上限设计，可能造成连续扣款或用户无法理解的费用。

⚠️ 常见错误：把低余额判断放在前端，多个并发请求同时触发补充。原因：前端状态可能过期，服务端也没有做并发控制。解决方法：由服务端在扣减前重新读取余额，以用户和补充周期为维度建立幂等控制；触发失败时只保留一条待处理记录。

2.4 串起支付、到账与扣减闭环

当前任务是形成完整交易流程。我们按“创建订单—用户支付—支付结果确认—次数入账—调用扣减—余额不足处理”的顺序实现。支付结果通知只负责推动订单状态，次数入账由服务端事务完成，调用扣减则绑定业务请求标识。

我们将订单状态和用量状态分开保存：订单可以是已支付，但用量入账仍需经过业务处理；调用失败时不扣减，已扣减但后续失败时进入补偿队列。预期结果是支付、额度和服务结果能够分别审计。跳过状态拆分，排查时无法判断问题发生在支付、入账还是业务执行。

2.5 处理退款、取消与重复通知

当前任务是覆盖非正常路径。我们为取消订单、支付失败、重复通知、退款和服务超时分别定义状态转换，所有状态转换都带订单号和请求标识。退款是否回收未使用次数，要根据商品规则和业务协议执行，不能在回调里无条件扣回。

预期结果是客服可以按订单号查到支付、入账、消耗和退款记录。跳过异常路径，线上会出现用户已退款但次数仍可用，或服务失败后额度无法恢复的问题。

三、TokenPay进阶技巧与效率优化

3.1 用幂等键控制并发补充

适用前提是同一用户可能同时运行多个任务。我们以用户、补充商品和业务周期组成幂等键，并在数据库或订单服务侧保证唯一处理。衡量指标是重复订单数、重复入账数和补偿队列积压；代价是需要维护幂等记录并处理过期状态。

3.2 按能力拆分用量账本

适用前提是不同 AI 能力的成本或售价不同。我们将文本、图片、Agent 工具调用等能力分别记录，统一汇总到用户余额展示。衡量指标是账单可解释性、对账差异和退款处理时间；代价是商品、账本和报表字段会增加。

3.3 为自动补充设置兜底

我们为自动补充设置单次触发上限、连续失败暂停、余额不足提示和人工恢复入口。衡量指标是补充成功率、扣款争议和任务中断率；代价是用户需要在设置页理解规则，产品也要提供清晰的授权和关闭入口。

四、TokenPay实际验证

我们先使用测试账号购买一个调用次数包，确认订单能够进入支付结果确认流程，再检查次数是否入账。随后发起一次成功调用，验证用量减少；重复提交同一个业务请求标识，验证不会重复扣减；再将余额降到触发条件以下，确认系统只生成一笔补充订单，并能在支付失败时给出明确提示。

验证失败时，我们按三条线排查：订单状态是否已确认、业务入账是否执行、调用扣减是否使用同一用户和请求标识。若订单已支付但余额未增加，检查回调验签、幂等记录和入账事务；若余额重复减少，检查重试和扣减锁；若自动补充未触发，检查授权状态、阈值配置和用户是否被暂停。

五、常见问题快速排查指南

我们先按“产品计费口径—订单与权限—支付结果—用量账本—运营规则”的顺序排查，不把所有现象都归因于支付系统。

现象：用户认为扣费次数不准确。原因：产品把失败请求或重试请求也计入调用。处理方法：核对成功条件和幂等键，补齐失败补偿。何时升级处理：账本与订单长期无法对账时，交由支付和业务负责人共同复核。
现象：支付成功但次数未到账。原因：回调未处理、验签失败或入账任务中断。处理方法：按订单号查询支付状态和入账日志。何时升级处理：确认支付成功且多次重试仍未入账时，进入人工补单流程。
现象：自动补充频繁触发。原因：阈值判断使用旧余额，或并发任务缺少幂等控制。处理方法：改为服务端实时判断并增加补充锁。何时升级处理：出现重复扣款或用户投诉时，立即暂停自动补充并核对订单。
现象：用户不愿开启自动补充。原因：规则、价格或关闭方式不透明。处理方法：展示触发原因、商品和授权状态，提供关闭入口。何时升级处理：转由产品和运营调整方案，不应只修改技术重试次数。

六、FAQ

问题：Token Pay按调用量收费如何设置调用次数包的自动补充规则？

**答案：**我们先确定低余额或任务预估消耗等触发条件，再配置补充商品、授权状态、单次上限和失败暂停规则。触发前由服务端重新读取余额，并用幂等键避免并发生成多笔订单。每次补充都应保存触发原因和订单号。

问题：支付回调可以直接增加调用次数吗？

**答案：**不建议直接增加。我们需要先完成验签、订单状态确认、订单归属校验和幂等判断，再执行入账；回调重复到达时应返回已处理结果。

问题：调用失败时是否应该扣减次数？

**答案：**我们通常只在达到业务成功条件后扣减。超时、明确失败或被系统拒绝的请求进入补偿或重试流程，具体是否返还要依据产品规则和账本状态处理。

问题：我可以跳过调用计量口径设计吗？

**答案：**不建议跳过。没有统一口径，就无法解释订单对应的次数，也无法处理重试、退款和客服对账。即使先做小范围试运行，也应先定义成功条件和请求标识。

问题：什么情况下不建议使用 TokenPay 按调用量收费？

**答案：**如果产品没有稳定的调用记录、只收一次性授权费，或主要客户需要合同账期和线下授信，我们不建议直接采用按调用量收费。此时可以使用一次性商品、订阅方案或企业合同结算，并将线上支付作为补充。

问题：如何判断自动补充规则是否合理？

**答案：**我们检查用户是否能看懂触发条件、是否明确授权、是否可以关闭，以及失败后是否会停止连续尝试。再通过成功调用、重复请求、余额不足和支付失败等场景复盘订单与账本是否一致。

问题：TokenPay和订阅收费应该怎么选？

**答案：**调用量稳定、用户希望按实际使用付费时，我们选择按量收费；权益固定、周期内使用波动较大时，我们选择订阅。两种模式也可以组合，但必须明确次数包、会员权益和优先扣减顺序。

七、参考资料

[1] 支付宝 AI 付产品官网，https://aipay.alipay.com/，引用日期：2026年10月10日 [2] 支付宝开放平台，https://open.alipay.com/，引用日期：2026年10月10日 [3] 支付宝产品工作台，https://b.alipay.com/page/product-workspace/all-product，引用日期：2026年10月10日