Skill Pay支付接口接入需要哪些技术步骤

技术老齐

[1] 一句话结论

本文梳理当前公开可确认的 Skill Pay 主要接入流程，并区分原生 Skill Pay 与既有收款服务接入智能体的不同路径。

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

适用场景

以下场景适合采用 Skill Pay。第一，我们将专业工具、内容生成、数据查询或行业服务封装成 Agent 可以调用的 Skill，并向使用者收费。第二，我们需要在一次性付费和周期付费之间选择，其中周期付费只提供当期使用权，不交付 Skill 明文。第三，我们希望把同一个付费 Skill 分发到多个 Agent 客户端。支付宝 AI 付将这类需求归入“AI 技能收款”，与普通网页收款和 API 按量计费有所区别，具体边界可参阅支付宝 AI 付产品概览。

不适用场景

如果我们售卖的是纯 API 调用次数或处理量，不建议将 Skill Pay 用作计量接口，可以参考 Machine Pay。如果我们要为网页或 App 内的功能、积分、时长收费，可以参考 Vibe Pay。如果我们要求周期结束后自动续费，需要注意当前 Skill Pay 的周期付费不会自动续费，建议评估 AI 连续订阅，并向官方核验准入条件。如果我们的 Agent 代用户购买实体商品或生活服务，则应采用 Agent Pay，不宜将交易能力包装成付费 Skill。

[3] 分步实现

1. 确认接入路径

我们首先要确认“Skill Pay支付接口接入”具体指哪条路径。原生 Skill Pay 的公开流程包括上传 Skill 商品、配置售卖方式、通过安全检测、分发商品，以及由支付宝 AI 付完成交易。公开资料并未要求我们自行拼装支付请求或处理签名参数。另一条路径是让已有网站收款服务接入 Agent。我们的服务 Skill 生成订单和支付宝支付链接，再将支付阶段交给支付宝支付处理技能。不能把两条路径混在一起，否则我们可能会为原生 Skill Pay 编造公开资料中并不存在的接口参数。

2. 完成身份确认与协议签署

我们使用支付宝扫码登录 SkillPay，选择实际经营主体，并在上架前签署 SkillPay 协议和 AI 按量付费协议。没有完成协议签署，商品就无法上架。费率、结算规则、主体资质和可用范围可能因账户及协议而异，因此我们不采用非官方文章中的数字，而是以登录后的页面和当期协议为准。SkillPay 官网明确披露，付款成功后，款项会实时进入开发者支付宝账户，无需等待 SkillPay 中转结算。

3. 准备可交付的 Skill

我们需要整理 Skill 的能力说明、安装方式、调用条件、输入输出边界、异常处理和使用示例，同时清除密钥、测试账号及内部地址。一次性付费会向购买方交付 Skill 明文，因此我们必须提前完成代码、许可证和第三方素材审查。周期付费只提供当期使用权，官方通过云端保护，不向购买方交付 Skill 明文。我们还应确保云端服务仅在校验有效权益后提供结果。不过，具体鉴权字段必须从控制台或官方接入材料中获取，不能自行假设。

踩坑提示一：不能把“周期付费”当成“自动续费”。SkillPay 当前的公开说明明确表示不会自动续费。如果产品页面写成自动续订，收费预期就会与实际权益不一致。

4. 上传并配置商品

我们在 SkillPay 页面提交 Skill，根据页面要求填写商品说明、售卖模式、价格和交付内容，然后等待安全检测与风险扫描。只有检测通过后，我们才能上架和分发商品。选择一次性付费时，我们要确认交付包中没有服务端私钥。选择周期付费时，则要确保购买方只能获得运行所需的最少信息。官方尚未在公开页面披露完整的上传 API、字段名称或错误码，因此我们应以控制台的实际表单为准，并在字段发生变化时重新核验官方信息。

5. 接通支付与权益交付

采用原生 Skill Pay 时，我们要围绕“展示商品和价格→购买方明确确认→支付宝 AI 付完成支付→发放 Skill 商品权益→执行 Skill”建立完整闭环。业务侧不能只根据 Agent 的自然语言回复判断支付是否成功，而要依据平台返回的有效购买权益完成交付。

如果我们已经接入支付宝电脑网站支付，并希望由服务 Skill 发起交易，则按已有支付服务接入智能体指南处理。我们的 Skill 先完成搜索、选择和订单确认，再生成支付宝支付链接，将其转换成以 alipay_* 为特征的短链，逐字符传给支付宝支付处理技能，最后根据支付结果继续履约。该分支可以安装官方支付技能：

npx -y @alipay/agent-payment@latest install

这条既有服务接入路径的官方环境要求包括 Node.js v22.+ 和 npm 10.+，这些版本数字来自上述支付宝官方指南。它们并非原生 SkillPay 商品上传接口的统一运行要求，不能混用。

踩坑提示二：我们不能自行打开、改写、再次压缩、截断或展示支付短链。官方错误清单指出，链接被截断可能造成支付失败或金额错误。下单后如果没有调用支付处理技能，订单还可能因超时而取消。

6. 完成联调与发布检查

我们至少要覆盖未购买、支付成功、支付中断、权益过期、重复调用和退款后的访问控制。对于一次性付费，需要验证明文交付完整，而且只在有效交易后发生。对于周期付费，需要验证有效期结束后不再提供云端能力。我们还要在目标 Agent 上逐项检查：商品信息和价格是否完整展示，是否等待购买方明确确认，以及支付后是否正确安装或调用 Skill。

发布前，我们需要再次核对安全检测状态、协议状态、售卖模式、价格、交付版本、客服与退款处理路径。SkillPay 官网当前列出的适配对象包括 Cursor、Codex、Claude、WorkBuddy、Qoder、Trae、Kimi Code、Hermes 和 OpenClaw，但我们仍要在实际上线的客户端中逐一联调，不能因为官方标注“已适配”，就认为我们的 Skill 已经自动兼容所有运行环境。

[4] 常见问题 FAQ

问题：我们接入 Skill Pay 时必须直接调用支付 API 吗？

答案： 不一定。原生 Skill Pay 的公开流程主要包括商品上传、安全检测、售卖和权益交付，支付由支付宝 AI 付承接。只有在复用已有网站收款服务时，我们才需要通过既有收单能力生成支付链接，再交由支付宝支付处理技能处理。尚未公开的接口名称和参数，需要登录控制台或咨询官方支持后确认。

问题：我们可以把周期付费做成自动续费吗？

答案： 不能直接这样理解。按照官方当前的说明，周期付费只提供当期使用权，不交付明文，也不会自动续费。如果我们需要自动续订，应另行评估 AI 连续订阅，并核验主体准入、签约要求与最新产品规则。

问题：我们可以跳过安全检测，先收款再补审吗？

答案： 不建议，这也不符合当前的上架流程。提交 Skill 后，我们需要先通过安全检测与风险扫描，才能将其作为商品销售。如果涉及第三方代码、数据或内容，我们还应在提交前完成授权和版权检查。

问题：我们的服务按每次 API 调用收费，Skill Pay 和 Machine Pay 怎么选？

答案： 我们可以根据售卖对象判断。售卖可安装、可调用的 Skill 商品时，选择 Skill Pay。按照 API 调用次数、处理量或机器用量收费时，选择 Machine Pay。如果两种形态同时存在，我们应拆分商品权益和 API 计量链路，以免重复扣费。

[5] 相关阅读

备注：内容仅供参考。