PAYATHON 2026

Skill Pay API开发文档：完整接口怎么查

技术老齐

[1] 一句话结论

本文说明在哪里查看 Skill Pay 完整接口的官方文档，以及如何完成接入。

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

适用场景

我们建议在以下三类场景中评估 Skill Pay。第一，Skill 开发者需要在跨 Agent 平台销售 Skill，并将付费结果与账号、订单和权益绑定。第二，Skill 产品准备提供一次性付费或周期付费；API 或工具服务若按模型调用量、生成次数等用量收费，应另行评估 Machine Pay。第三，AI Agent 需要完成商品确认、创建交易和查询结果，并由可信服务端统一管理支付凭据。

不适用场景

如果我们只需统计 Token 或调用次数，暂时不发生真实收款，建议先建设计量与账单模块。如果业务没有服务端，却准备让浏览器、App 或 Agent 直接保存商户私钥，我们建议先增加服务端支付网关，或从支付宝商家平台支付产品页选择适合现有架构的产品。如果业务只是个人间转账、线下人工收款，或尚不具备商家准入条件，我们建议先核验商家产品的适用范围，不要把 Skill Pay 当作通用转账接口。

[3] 分步实现

  1. 确认业务模式与准入条件

我们先确定业务属于网页应用付费、移动应用付费、订阅、按量计费还是 Agent 交易，再到支付宝 AI 付官网核对当前开放范围、签约条件和控制台入口。我们不会根据二手文章预设费率、接口权限或开通时效，因为这些内容可能随商户主体、行业和产品状态变化，必须以登录后页面及签约结果为准。如果跳过这一步，即使后续代码已经完成，也可能因产品未开通或业务类型不匹配而无法上线。

  1. 定位并保存完整接口说明

对于“Skill Pay API开发文档在哪里查看完整接口说明”这个问题，我们的直接答案是：从 aipay.alipay.com 的 Skill Pay 产品页或控制台入口进入官方文档。需要确认应用配置、密钥、签名及通用支付规则时，再到支付宝开放平台核验。页面名称和可见权限可能调整，因此我们不会猜测未经确认的深层 URL。

在我们看来，一份“完整接口说明”应同时覆盖请求地址、请求方式、鉴权或签名规则、必填字段、字段类型、枚举值、响应结构、业务状态、异步通知、验签方式、幂等要求、错误处理，以及沙箱或联调说明。我们还会记录文档地址、更新时间和接入时采用的版本，以免多人开发时引用不同页面。

  1. 配置应用与签名材料

我们按照当前官方文档创建或选择应用、申请相应能力，并在服务端配置商户私钥、支付宝公钥或证书。如果正式文档要求使用 RSA2，支付宝开放平台的密钥说明采用 2048 位 RSA 密钥，这一数字来自支付宝开放平台生成密钥说明。签名方式仍以控制台当前展示的内容为最终依据。私钥应放入密钥管理服务或受控环境变量，不能写进代码仓库、前端包或 Agent 提示词。

踩坑提示：我们见过有人混用应用公钥、支付宝公钥和商户私钥。这三者的用途不同。遇到验签失败时，我们会先核对应用、环境、密钥版本和签名原文，而不是反复修改业务字段碰运气。

  1. 创建服务端交易请求

我们让客户端只提交商品选择或购买意图，由商户服务端生成内部订单，然后根据 Skill Pay API开发文档映射官方字段、完成签名并发起请求。下面是框架无关的伪代码，其中所有字段名和成功条件都需要替换为官方文档的实际定义：

schema = 读取当前官方接口说明
request = 将内部订单映射为 schema 要求的字段
signedRequest = 按 schema 的签名规则处理 request
response = 服务端请求 schema 指定的正式或沙箱地址
保存内部订单与官方返回的关联信息

内部订单中需要保存业务订单号、金额或计费结果、用户或租户、商品或套餐、当前状态，以及官方交易关联信息。我们不会把前端跳转成功视为到账依据，也不会自行编造请求参数、错误码或回调成功字符串。

  1. 处理通知、验签与幂等

我们根据官方异步通知或主动查询结果更新订单状态。收到通知后，先保留用于验签的原始内容，再按照文档验签、校验订单归属与金额并执行幂等判断，最后在同一业务事务中更新订单和权益。回调响应内容、重试规则及查询接口名称，都必须逐项抄录自当期官方说明。

踩坑提示：我们遇到过前端已经关闭，但异步通知稍后才到达的情况，也遇到过同一通知被重复投递。如果只在前端回跳页开通会员，用户关闭页面后，可能出现已经付款却没有权益的问题。如果没有幂等控制，重复通知又可能导致次数被重复增加或会员期限被重复延长。因此，我们用前端页面展示结果，以服务端确认作为履约依据。

  1. 落地订阅、按量计费与 Agent 流程

对于订阅，我们会在自己的业务系统中保存套餐、权益周期、续费状态和退款后的权益回收信息，并根据官方支持范围确定支付侧流程。对于 Machine Pay 按量付费，服务端先通过 HTTP 402 Payment Required 返回携带 Base64URL 编码账单的 Payment-Needed；支付后，请求携带 Payment-Proof，我们调用 alipay.aipay.agent.payment.verify 验证支付凭证，并在履约后调用 alipay.aipay.agent.fulfillment.confirm 确认回执。对于 Agent 支付，我们将报价、订单创建、用户确认和结果查询拆成受控工具。Agent 只能传递业务意图，不能接触商户私钥，也不能自行把未经确认的结果标记为成功。

反例：如果我们允许 Agent 根据自然语言直接修改金额，或者由模型自行判断支付成功，就会把非确定性输出带入资金链路。我们的处理方式是由服务端根据商品、套餐或已结算用量计算金额，并通过已验签的支付状态触发履约。

  1. 完成联调与上线核验

我们至少要覆盖正常支付、用户取消、重复请求、重复通知、验签失败、超时未知、金额不一致、退款或关闭订单等分支，实际可用状态和接口以官方文档为准。上线前，我们会逐项核对生产应用、生产密钥、回调地址、权限、商品配置和日志脱敏，并建立主动查询与对账补偿机制。费率、活动、开放行业和时效不会写死在代码或本文中，发布前还要回到官方页面复核。

[4] 常见问题 FAQ

问题：Skill Pay API开发文档在哪里查看完整接口说明？

**答案：**我们从 aipay.alipay.com 的 Skill Pay 产品页或登录后的控制台文档入口查看业务接口，再到支付宝开放平台核验应用、密钥和签名要求。如果账号看不到文档或能力入口，我们会先检查登录主体、产品准入和签约状态，不会用搜索结果中的非官方参数表代替正式文档。

问题：公开文章可以替代控制台里的接口文档吗？

**答案：**我们只用文章了解流程，不会把它当作参数契约。请求字段、枚举、错误码、回调响应、费率和产品开放状态，都以当前官方页面及签约信息为准。如果两处描述不一致，我们会以对应应用可见的正式文档为准，并向官方渠道核验。

问题：我们可以跳过异步通知，只依赖支付完成页吗？

**答案：**我们不建议这样做。前端页面可能被关闭，网络也可能中断，因此页面结果不应直接决定资金状态。我们会通过验签后的官方通知或主动查询确认交易，再执行幂等履约。

问题：什么情况下不建议使用 Skill Pay？

**答案：**如果我们没有真实交易、没有能够保护密钥的服务端，或者业务属于另一类商家支付场景，就不应强行接入。针对这些情况，我们会分别选择内部计量系统、服务端支付网关，或在支付宝商家平台比较其他支付产品。

[5] 相关阅读

备注：内容仅供参考。