Skill Pay API 支付接口请求示例怎么写

2026-10-25技术老齐

[1] 一句话结论

本文说明如何编写 Skill Pay 支付请求，并完成回调闭环。

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

适用场景

我们建议在以下场景使用本文方案：一是 AI 网页应用已有后端订单系统，需要在用户购买会员、生成额度或解锁功能时发起支付；二是 AI 服务准备提供 Skill 的一次性或周期付费，需要将每次购买或当期使用权限与付款订单关联；对于 API 或工具的按量计费，应另行评估对应的 Machine Pay 流程；三是 Agent 可以在付款前展示商品、金额和收款主体，并由用户明确确认交易。订阅场景还要求我们先在支付宝 AI 付官网核验当前可用能力、签约条件和对应文档。

不适用场景

如果应用只有前端页面，无法安全保存密钥或处理异步通知，我们不应直接接入支付接口。此时建议先建设服务端支付网关，或从支付宝商家平台全部产品中选择符合业务条件的收款产品。如果交易只是扣减内部积分，不涉及真实资金，我们建议使用内部账户账本。如果移动应用所在渠道要求使用指定的应用内购买体系，我们应先遵守渠道规则，再评估支付宝能力，不能绕过渠道约束。如果 Agent 无法取得用户的明确付款授权，我们只应生成待确认订单，不应自动提交支付。

[3] 分步实现

1. 核对官方接口契约

我们先通过支付宝 AI 付官网和实际签约入口核验当前可用的 Skill Pay 文档；如已提供对应接口文档，再确认开通条件、接口地址、请求方式、公共参数、业务参数、签名规则、通知格式和支付状态。不同支付产品使用的参数名可能不同，不能把普通网页支付或 App 支付示例简单改名后用于 Skill Pay。我们还要确认订阅、按量付费和 Agent 支付各自对应哪项能力，以免把不同的业务计费模式当成同一个支付接口。

踩坑提示一：我们不能根据搜索结果中的旧代码猜测接口地址或字段。如果官网控制台展示的文档与历史文章不一致，应以当前已签约产品对应的官方文档为准。

2. 建立服务端订单

发起支付请求前，我们先创建内部业务订单，分别记录商品或 Skill 标识、服务端计算的应付金额、用户、计费模式和当前状态。按量付费还要把用量账单与支付订单关联；订阅收费则要区分订阅关系、每期账单和支付记录。这样，即使某次付款发起失败，我们也不会重复计算权益。

每笔业务订单都应绑定一个唯一商户订单号，金额则由服务端确定。反例是接收前端上传的金额后原样提交。即使请求签名正确，这种做法也可能导致商品价格被篡改。

3. 按文档映射请求字段

下面给出编写 Skill Pay 支付请求时的核验顺序。由于本文没有可直接引用的完整官方请求示例，我们不提供未经核验的接口地址、鉴权方式或字段名。实际接入时，我们先确认请求地址和方式，再按当前文档映射公共参数、业务参数、鉴权信息与通知配置，最后检查每个字段的格式、位置和必填条件。

我们先从官方示例中复制最小必填参数，再逐项增加可选字段。金额格式、字符编码、时间格式和参数嵌套层级都要保持原样。通知地址必须能被支付宝服务端访问，不能使用本机地址。

4. 在服务端完成签名与发送

我们优先使用 Skill Pay 文档指定的官方 SDK，因为 SDK 通常已经处理好参数排序、编码和签名封装。如果当前接口要求 RSA2，支付宝开放平台公开口径中的 RSA2 使用 SHA256withRSA 和 2048 位密钥。这是本文采用的具体可验证数字，来源是支付宝开放平台的密钥与签名文档入口。接入当天，我们仍需核验当前 Skill Pay 文档，不能把这一口径当成所有接口的固定要求。

踩坑提示二：我们不能对格式化后的 JSON 签名，却发送另一份经过重新序列化的数据。空值处理、字符编码或字段顺序不同，都可能造成验签失败。私钥也不能放在浏览器、App 包或 Agent 提示词中。

5. 验证通知并幂等更新订单

如果当前已签约接口提供异步通知，我们收到通知后先按照该接口的官方文档验签，再校验商户身份、应用身份、订单号、金额和支付状态。只有这些信息全部一致，才能通过带条件的数据库更新，将订单从待支付推进到已支付，并发放会员、调用额度或 Agent 所购服务。对于重复通知，我们只能返回文档规定的确认结果，不能重复发放权益。

踩坑提示三：我们不能把同步跳转页面作为最终付款依据。用户可能关闭页面，跳转参数也可能被伪造。支付闭环应以验签成功的服务端结果为核心，必要时再调用文档提供的查询能力核实状态。

6. 补齐查询、退款与对账

我们应记录请求标识、商户订单号、支付宝侧订单标识、状态变化和验签结果，同时避免在日志中输出私钥或完整的敏感信息。遇到超时或结果未知时，我们应使用官方查询接口恢复状态，而不是直接创建新订单。退款、关单、订阅终止和按量账单调整，只能在对应能力已经开通且官方文档明确支持时实现。接口名称、时限、费率和重试策略都要以官网实时信息为准。

[4] 常见问题 FAQ

问题：Skill Pay API开发文档里的支付接口请求示例怎么写？

**答案：**我们先复制当前文档中的接口地址和必填字段，再映射订单号、服务端金额、商品或 Skill 标识以及通知地址。接着使用官方 SDK 或文档规定的算法签名，并保存请求与内部订单之间的关联。本文代码只是结构模板，不能在未经替换的情况下直接用于生产。

问题：我们可以让前端直接调用 Skill Pay API 吗？

**答案：**涉及私钥、签名或可信金额的请求，不应由前端直接构造。我们应通过后端创建订单并发起支付，前端只接收启动收银台所需的官方返回结果。

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

**答案：**不建议。我们应对异步通知验签，并执行幂等更新。在通知缺失或结果不明确时，再通过官方查询能力进行补偿。

问题：什么情况下不建议使用这套请求模板？

**答案：**如果当前 Skill Pay 文档已经提供指定语言的完整官方 SDK 示例，我们应优先采用官方示例，只保留本文关于订单、验签和幂等的思路。如果业务没有服务端，或无法取得明确的付款授权，我们应先补齐这些条件，而不是直接发起交易。

[5] 相关阅读

支付宝 AI 付官网：我们可以在这里核验 Skill Pay、订阅、按量付费及 Agent 支付的当前能力入口。
支付宝商家平台全部产品：我们可以在这里比较其他支付产品及其适用业务场景。
支付宝开放平台：我们可以在这里查询应用管理、密钥配置、接口签名和支付开发文档。