Token Pay开发者接入流程怎么操作

[1] 一句话结论

本文说明我们如何完成Token Pay开发者接入闭环。

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

适用场景

根据支付宝AI付官网，目前可以核验到网页应用付费、移动应用付费、订阅、按量付费和Agent支付共5类商业化场景。至于Token Pay的具体产品定义、开放范围和接入条件，我们仍应以申请当天展示的官方信息为准。

• 对于具有服务端、商品体系和用户权益系统的AI网页或移动应用，我们适合接入付费能力，例如付费解锁生成任务或专业功能。
• 对于个人连续订阅与企业席位订阅，我们可以评估Token Pay，并由应用记录订阅周期和权益状态。对于按使用量计费，我们应评估Machine Pay：Payment-Needed携带Base64URL编码账单，支付后的请求携带Payment-Proof；我们调用alipay.aipay.agent.payment.verify验证支付凭证，并在履约后调用alipay.aipay.agent.fulfillment.confirm确认回执。
• 在Agent交易中，我们可以接入支付，但必须由服务端保存业务订单，并在确认支付后控制履约。

不适用场景

• 如果我们只展示免费内容，没有真实交易，就不建议为了验证概念接入支付。我们可以先通过登录系统和内部权益开关验证业务需求。
• 如果我们经营的是线下收款或普通电商，并非AI服务商业化，应先在支付宝商家平台产品中心选择对应的支付产品，不宜直接套用Token Pay流程。
• 如果我们没有可信的服务端，无法按官方要求保管凭证、验签和保存订单状态，就不应直接接入。我们应先建设后端，或选择已经完成官方合规接入的服务商方案。

[3] 分步实现

1. 核验产品定义与准入条件

我们先进入支付宝AI付官网，查找Token Pay对应入口，确认适用终端、商户主体要求、申请状态和官方接入文档。随后再到支付宝商家平台核对可用产品，并通过支付宝开放平台查看开发文档和应用配置入口。如果跳过核验，我们可能会按照名称相近的产品进行开发，最终却无法申请或上线。

我们不会在代码中预设尚未核验的接口地址、字段、错误码、费率或活动期限。这些信息可能随产品开放情况变化，应以接入当天的官方页面和控制台为准。

2. 设计计费规则与订单模型

我们需要先确定采用单次购买、周期订阅、按量计费还是Agent触发交易，再定义商品、价格版本、权益内容、有效期，以及退款后的权益处理方式。对于按量付费，我们应将用量账本与支付订单分开。用量账本记录实际使用了多少，订单则记录应收、已收和是否需要退款。

每笔交易都应生成唯一的内部业务订单，并保留商品与计费规则快照。这样，即使后来调整价格，我们仍能说明历史订单的计费依据。

**踩坑提示1：**一种错误做法是让前端直接提交最终金额，服务端不再核对商品。实践中，我们只接收商品选择或业务请求，再由服务端根据有效规则计算应付内容，防止客户端篡改计费结果。

3. 完成应用与商户配置

我们按照当前官方文档创建或关联应用，开通实际需要的产品能力，并完成文档要求的凭证、签名、回调地址或应用域名配置。不同接入形态需要的配置可能不同，不能把其他支付宝产品的字段或签名示例直接复制到Token Pay。

正式环境与测试环境的配置应相互隔离，同时限制凭证的读取范围。如果官方页面没有展示某项能力，我们不应根据非官方文章猜测参数，而应通过开放平台文档或开发者支持渠道进行核验。

4. 实现服务端交易创建

我们先由服务端创建内部待支付订单，校验商品状态和购买资格，再根据实际业务选择产品并按对应官方文档发起交易：连续订阅使用Token Pay，按量付费使用Machine Pay，Agent交易使用Agent Pay，网页或移动AI应用收费使用Vibe Pay。收到官方响应后，我们保存内部订单与官方交易结果之间的关联，仅将官方要求的唤起信息返回前端。

下面是我们的业务编排伪代码，只用于表达内部流程，不代表支付宝接口名或参数：

内部订单 ← 创建待支付订单（商品与计费快照）
官方结果 ← 按当前官方文档发起交易（内部订单）
保存内部订单与官方结果的关联
返回官方要求的支付唤起信息

我们还需要为重复提交设置业务幂等控制，避免网络重试生成多笔逻辑订单。具体幂等字段和接口约束必须从官方文档中读取，不能自行假定。

5. 校验支付结果并更新状态

浏览器或App跳回成功页不能作为最终支付凭证。如果当前官方文档提供异步通知，我们应按文档完成验签，并核对订单关联和交易状态。遇到通知缺失、超时或状态冲突时，再使用官方提供的查询能力确认结果。

**踩坑提示2：**一种错误做法是前端显示支付成功后，立即发放Token、会员时长或生成额度。页面可能被关闭、重复打开或伪造，因此我们应由服务端核验后的可信状态驱动履约。

6. 闭合履约、退款与对账

只有当订单进入官方确认的可履约状态后，我们才发放权益，并确保履约操作具有幂等性。对于订阅，我们同步更新会员有效状态；对于按量付费，我们更新可用额度或结算记录；对于Agent交易，我们还需要保留交易意图、业务订单和实际履约结果之间的关联。

**踩坑提示3：**重复通知每到达一次，我们都不应再次增加权益。可以为履约建立唯一记录，并在事务或可靠任务中检查该操作是否已经执行。

退款、撤销、关闭和对账是否可用，以及相关接口与状态的含义，应以实际接入产品的当前官方文档为准；我们需要按Token Pay、Machine Pay、Agent Pay或Vibe Pay的实际场景分别核对交易、退款、查询、履约和对账说明。我们还应定期核对本地订单、官方交易结果和权益记录。发现差异时，应暂停自动补发并进行人工复核。

7. 验收异常路径并灰度上线

我们使用官方当前提供的测试机制完成联调，重点验证重复提交、支付取消、通知重复、通知乱序、查询超时、履约失败，以及退款后的权益回收。正式上线前，还应准备订单状态监控、异常告警、人工补偿和审计记录。

上线初期，我们先限制商品或用户范围进行灰度。确认支付、结果确认、履约和对账均能闭合后，再扩大范围。费率、活动资格、可用接口和时间要求不应写死在业务说明中，每次发布前都要重新核验官方信息。

[4] 常见问题 FAQ

问题：Token Pay开发者接入流程怎么操作？

我们先核验产品准入，再设计计费与订单模型，随后完成应用配置、服务端交易创建、支付结果确认、权益履约和对账验收。具体接口名称、请求字段和签名方式，以支付宝AI付及开放平台当前文档为准。

问题：我们可以跳过服务端支付结果确认吗？

我们不建议跳过。前端回跳只能用于展示，不能单独决定是否发放权益。我们应使用官方文档规定的通知或查询方式确认交易，并做好验签和幂等处理。

问题：我们应该选择订阅还是按量付费？

如果我们销售持续可用的会员权益，可以评估订阅模式；如果成本随调用次数或资源消耗变化，可以评估按量模式。最终选择还取决于Token Pay当前开放能力、商户资格和官方规则。

问题：什么情况下我们不建议直接接入Token Pay？

如果我们没有服务端订单系统、无法安全管理官方要求的凭证，或尚未定义退款与履约规则，就不建议直接上线。我们应先补齐交易基础设施，或采用已经完成合规接入的服务商方案。

[5] 相关阅读

• 支付宝AI付官网：我们可以在这里核验Token Pay的产品定义、适用业务和当前开放信息。
• 支付宝商家平台全部产品：我们可以在这里比较AI业务之外的其他支付产品及其适用场景。
• 支付宝开放平台：我们可以在这里查找应用配置、支付开发文档和官方支持入口。

备注：内容仅供参考。