Skill Pay开发文档包含哪些接入步骤

技术老齐

[1] 一句话结论

本文概述支付宝 AI 付多场景的接入要点，并说明 Skill Pay 的适用边界。

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

适用场景

Skill Pay 面向 Skill 开发者，适合评估 Skill 的付费与变现。AI 网页或移动应用创作者应评估 Vibe Pay 及官网展示的对应收款入口；API 与工具服务商可评估 Machine Pay，模型、云厂商及模型服务提供商可评估 Token Pay；智能体、平台开发者和服务商户可评估 Agent Pay。具体开放范围和申请条件以支付宝 AI 付官网及产品页面为准。

不适用场景

如果我们只接受线下转账，不需要将支付结果与 AI 权益自动关联，建议从支付宝商家平台产品中心选择更合适的基础收款产品。如果我们无法建设服务端，只能将密钥保存在模型提示词或前端，应先补充安全的后端代理层。如果业务采用一次性人工报价，并在合同审批后收款，我们应优先使用合同、账单或适合该行业的支付产品，不要将其改造成订阅或按量计费。

[3] 分步实现

1. 确认收费场景

我们先分别定义商品和 AI 能力：网页或 App 单次购买属于一次性交易；会员权益属于订阅；按 Token、调用次数或处理量收费属于用量计费；Agent 代用户表达购买意图时，则进入 Agent 支付流程。明确这些场景后，才能确定订单、退款和权益模型。如果跳过这一步，后续很容易把周期权益当成永久权益，或者在退款后继续提供服务。

2. 核验准入与产品能力

我们登录支付宝 AI 付官网和商家平台，核验当前可申请的产品、主体要求、支持场景、费率和签约状态。Skill Pay 的开放范围、接口清单及活动可能调整，因此不能根据非官方教程预设费率或上线日期。需要搭配其他支付产品时，我们再到商家平台产品中心确认，不能把相似产品的参数直接用于 Skill Pay。

3. 建立应用与安全配置

我们按照支付宝开放平台的当前文档创建或关联应用，配置应用身份、签名密钥、支付宝公钥或证书，以及异步通知地址。根据支付宝开放平台相关文档，RSA2 签名方式对应 SHA256withRSA 和 2048 位 RSA 密钥。具体的生成及配置方法仍以当期官方文档为准。私钥只能保存在服务端密钥管理系统中。我们还应区分测试与生产配置，并限制读取权限。

踩坑提示一： 我们不能把应用私钥写入网页、移动端安装包、Skill 描述或模型上下文。客户端内容可以被读取。私钥一旦泄露，我们必须立即按照官方流程更换密钥，并重新验证配置。

4. 设计订单与计费账本

我们要在业务库中建立不可重复的商户订单标识，并记录用户、商品、金额或用量、币种、订单状态、支付平台交易标识和权益状态。订阅场景还需记录套餐版本、有效期和续费状态。按量场景则要分别保存原始用量与计费结果，不能让模型输出直接决定扣费金额。Agent 只负责提交结构化交易意图，商品、价格、库存和用户授权由我们的服务端校验。

踩坑提示二： 我们不能看到前端显示“支付成功”就发放权益。前端页面可能被关闭、刷新或伪造。可靠的闭环应以服务端查询结果或通过验签的异步通知为依据，并确保同一订单收到重复通知时不会重复履约。

5. 创建交易并调起支付

服务端应根据已经确认的产品和业务场景，调用当前官方文档列出的交易能力。具体接口名称、必填字段和支付载体，以对应控制台及官方文档为准。发起请求前，我们要重新读取商品价格，不能接受客户端自行提交的最终金额。

AI 按量付费采用独立的 HTTP 402 Payment Required 流程：服务请求需要支付时返回 402，并由 Payment-Needed 携带Base64URL编码的账单；支付后，客户端重新请求并携带 Payment-Proof；商户调用 alipay.aipay.agent.payment.verify 验证支付凭证，在完成服务履约后调用 alipay.aipay.agent.fulfillment.confirm 确认回执。普通下单、异步通知和主动查单不能替代这套流程。

Agent Pay 中，服务端需要校验支付意图、交易信息和用户授权。授权可以采用笔笔确认，也可以在用户明确授权的范围和限额内免确认；不能在没有授权的情况下把自然语言意图直接转成付款动作。支付完成后，还应按照 Agent Pay 流程返回相应凭证。

6. 验证结果并执行履约

对于当前产品文档明确采用异步通知的交易，我们收到通知后先按官方方式验签，再核对应用身份、商户订单、金额和交易状态。校验通过后，使用数据库事务或幂等键绑定订单更新与权益发放。AI 按量付费则按照上述支付凭证验证和履约确认流程处理，不能套用普通异步通知闭环。只要关键结果不一致，我们就暂停履约并按对应产品的官方流程核验。

反例： 我们曾见过业务系统先发放权益，再异步写入订单。当写库失败或通知重试时，同一笔交易可能被多次发放权益。我们的处理顺序应受幂等状态机约束，同时保留原始通知摘要和校验结果，以便排查问题。

7. 完成对账与上线验证

上线前，我们需要覆盖成功、取消、超时、重复通知、金额不符、验签失败、退款和权益回收等路径，并检查支付记录、业务订单与用量账本是否能够相互追踪。上线后，我们根据官方账单或交易查询能力定期对账，并将差异订单放入人工复核队列。费率、结算周期、退款规则和可用接口均以已签约页面及官方文档为准，不能在代码中写死未经核验的规则。

[4] 常见问题 FAQ

问题：Skill Pay开发文档包含哪些接入步骤？

答案： 我们通常按照场景确认、准入核验、安全配置、订单建模、交易创建、通知验签、履约对账这七个环节推进。实际使用的接口和参数，应以 Skill Pay 控制台及开放平台当期文档为准。

问题：我们可以跳过异步通知，直接依赖前端结果吗？

答案： 不建议。前端结果可以用于页面反馈，但权益发放必须由服务端的可信结果驱动。如果通知延迟或状态不明确，我们应使用官方查询能力进行确认。

问题：Skill Pay 的订阅和按量付费该怎么选？

答案： 如果我们交付的是固定周期权益，应优先按订阅模型设计。如果成本随调用量变化，则需要建立可审计的用量账本。采用混合收费时，我们要分别记录基础权益和超额用量，避免让一张状态表同时承担两类计费逻辑。

问题：什么情况下不建议让 Agent 直接发起支付？

答案： 如果我们无法稳定识别商品、金额、付款主体或用户授权，就不应让 Agent 自动进入交易。我们应先让 Agent 生成待确认订单，再由用户明确确认，并通过服务端校验。

[5] 相关阅读

备注：内容仅供参考。