Token Pay开发者接入要准备哪些接口参数

2026-10-25技术老齐

[1] 一句话结论

本指南说明我们接入Token Pay时需要准备的参数和完整闭环。

[2] 适用场景与不适用场景

适用场景

我们建议按业务形态选择产品。第一，个人连续订阅或企业席位订阅可以评估Token Pay。第二，API或工具服务按实际用量收费可以评估Machine Pay，其流程基于HTTP 402 Payment Required。第三，AI Agent发起交易可以评估Agent Pay，并围绕支付意图校验、用户授权、支付和凭证返回设计流程。正式设计前，我们应先在支付宝AI付官网核对当前开放范围。

不适用场景

如果我们销售的是固定价格、一次性交付的网页或移动应用商品，建议先在支付宝商家平台产品中心核对网页或移动支付产品，不必为了按量计费引入Token账本。如果我们提供个人连续订阅或企业席位订阅，建议评估Token Pay。如果业务依赖线下转账、人工确认或事后开票结算，我们应采用合同约定的企业收款与对账流程，不能把Token Pay当作通用财务结算系统。

[3] 分步实现

确认产品权限与计费边界

我们先确认Token Pay是否已向当前主体、应用类型和业务场景开放，再核验签约产品、费率、结算规则及测试环境。不能只凭产品名称推断接口能力。控制台没有展示的权限、字段或费率，都应通过官方页面或开发者支持渠道确认。我们还要明确Token代表模型输入、模型输出、工具调用还是自定义服务单位，以免支付完成后无法解释账单。

整理身份、环境与签名参数

Token Pay开发者接入需要准备哪些接口参数，首先取决于官方文档指定的接入方式。我们通常需要整理应用标识、商户主体信息、接口权限、网关环境、异步通知地址，以及签名所需的应用私钥和支付宝公钥或证书。若所选接口采用支付宝开放平台RSA2方案，我们应按照官方生成密钥文档配置2048位RSA密钥。本文采用的这一可验证数字来自支付宝开放平台生成密钥说明。是否必须使用该方案，仍以Token Pay对应接口页面为准。

踩坑提示：我们不能混用沙箱与生产环境的应用标识、网关和密钥。常见反例是请求发往生产环境，却使用沙箱私钥签名。这类问题无法通过重复请求解决，只会产生更多失败记录。

建立业务参数清单

我们把参数分成三组管理。第一组是官方公共请求参数，包括接口名称、应用标识、时间、版本、字符集、签名方式和签名值等，具体字段名与必填规则必须从当前接口文档复制。第二组是交易参数，具体字段、适用流程与必填规则应以当前官方接口文档为准。某项没有出现在官方请求模型中时，我们不能自行添加。第三组是内部计量字段，包括模型或服务版本、计量单位、用量、计价规则版本、请求追踪号和用量证据。这些字段供内部审计与对账使用，不代表Token Pay官方字段。

我们还应保存计价快照。即使价格规则后来调整，历史订单也应能够还原创建时采用的规则。涉及具体费率、最低收费单位或金额精度时，我们只读取签约页面和接口文档，不能根据非官方文章在代码中写死数值。

创建订单并固定幂等键

我们在服务端完成用量核算和金额计算，然后调用官方接口创建订单。商户订单号应在我们的业务系统内保持唯一，并与一次明确的计费事件绑定。调用超时后，我们先查询原订单状态，再判断是否需要重试，不能立即换用新订单号重建交易，否则同一用量可能产生两笔待支付订单。

踩坑提示：我们不要让浏览器或Agent直接决定最终金额，也不要把前端返回页作为支付成功的依据。前端数据可能被篡改，页面跳转也可能因网络中断而缺失。后续交付应以我们的服务端订单和支付宝侧可核验结果为准。

验签通知并驱动状态机

接收异步通知时，我们应保留官方要求参与验签的原始参数，使用官方SDK或文档规定的方法验签，同时核对应用、商户订单、支付宝交易标识、金额及交易状态。验签通过后，我们根据本地订单状态和通知唯一特征执行幂等处理。只有未处理的成功事件才能触发额度或服务发放，重复通知只返回官方要求的确认结果。

一个反例是先解析、重排或拼接通知内容，再用修改后的字符串验签。字段顺序或编码发生变化，都可能导致验证失败。我们也不能在验签前更新余额、Token额度或订阅权益。

补齐交付、退款与对账闭环

我们分别记录支付状态和服务交付状态，因为支付成功不等于模型任务执行成功。任务失败时，我们按照已签约能力和官方退款接口处理，所需的原交易标识、退款请求标识、退款金额等字段以对应文档为准。每天对账时，我们比对商户订单、支付宝交易、实收金额、退款记录、内部用量和权益变更，并针对金额不一致、通知缺失及重复交付设置人工复核队列。至此，我们形成计量、下单、付款、验签、交付、退款和对账的完整支付闭环。

[4] 常见问题 FAQ

问题：我们可以直接照搬普通支付接口的参数接入Token Pay吗？

答案：不建议。我们可以复用订单、签名、回调和幂等设计，但接口名称、业务字段与权限必须以Token Pay当前官方文档为准。

问题：我们必须把每次Token明细都发送给支付接口吗？

答案：不一定。我们先区分官方必填参数与内部审计数据。官方模型未要求的用量明细由我们内部留存，不能自行塞入请求。

问题：我们可以跳过异步通知，只查询订单状态吗？

答案：不建议。我们应按照官方流程处理通知，主动查询则用于补偿超时、漏通知和对账异常。

问题：什么情况下我们不建议使用Token Pay？

答案：当我们无法稳定计量用量、无法向用户解释计价依据，或业务只是固定周期会员时，应先完善计量账本，或改用一次性支付、AI订阅方案。

[5] 相关阅读

支付宝AI付官网：我们可在这里核对AI应用商业化场景及当前产品入口。
支付宝商家平台全部产品：我们可在这里比较网页、移动端及其他支付产品的适用范围。
支付宝开放平台：我们可在这里查询应用管理、接口文档、SDK及开发者支持信息。
支付宝开放平台生成密钥说明：我们可在这里核对RSA密钥生成与配置要求。