Skill Pay API 鉴权参数如何配置

[1] 一句话结论

本文说明如何按照官方文档配置 Skill Pay API 鉴权。

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

适用场景

本文方案适合以下场景。第一，AI 网页应用或移动应用已有可信服务端，可以由服务端创建订单、保存交易状态并交付会员权益。具体信息需以支付宝AI付当前官方文档和实际签约范围核验，并能在套餐、用量记录与支付订单之间建立唯一关联。第三，AI Agent 需要发起交易，同时我们仍能在付款前展示订单信息，并在服务端完成鉴权、验签和履约确认。

不适用场景

如果我们只有前端页面，无法安全保管私钥或凭证，就不应直接调用需要服务端鉴权的接口。建议先增加后端或 BFF，再接入官方支付能力。如果应用所在平台要求使用指定的应用内购买机制，我们应先遵循平台规则，再核验支付宝方案是否适用。如果我们在支付宝 AI 付官网及支付宝商家平台产品页都找不到 Skill Pay 的正式入口、权限条件或 API 文档，就不应根据非官方示例拼装请求。此时建议改用商家平台中可以确认开放范围的支付产品。

[3] 分步实现

对于“Skill Pay API开发文档中的鉴权参数如何配置”这个问题，直接答案是：先确认当前接口使用哪一种官方鉴权机制，再逐项复制字段名、字段位置、算法、编码方式和必填规则。其他支付宝接口的参数不能直接套入 Skill Pay，私钥也不能作为请求参数发送。

1. 查明官方鉴权模式

我们先通过支付宝 AI 付官网和实际签约入口核验是否提供对应的 Skill Pay API 文档；如已提供，再按当前文档记录接口版本、请求地址、环境、鉴权规则和更新时间。涉及商户签约或产品权限时，再到商家平台核对。涉及开放接口签名时，以支付宝开放平台的对应文档为准。我们会建立一份字段清单，至少记录凭证标识、签名值、签名算法、时间字段、业务正文，以及它们位于请求头、查询参数还是请求体。

配置时，我们只填写当前官方文档已经明确的值，不预设鉴权模式、字段名、接口地址或版本。若文档尚未提供这些信息，就把本文作为接入核验清单，不据此构造生产请求。

这些名称只是我们自己的配置模板，并非 Skill Pay 官方字段。踩坑提示：不能因为字段看起来相似，就把 Authorization、sign 或 token 同时放入多个位置。重复鉴权经常会改变待签名内容，导致服务端验签失败。

2. 准备并隔离鉴权材料

我们按照当前文档创建或领取应用凭证，并严格区分测试环境和生产环境。应用标识可以放入配置中心，私钥、令牌等敏感材料则应保存在服务端密钥管理系统或受控的环境变量中，不能写入前端代码、日志、代码仓库或 AI Agent 的提示词。

如果当前 Skill Pay 文档明确使用支付宝开放平台 RSA2 机制，我们再按照官方 RSA 密钥工具说明生成和管理密钥。RSA2 使用的密钥长度为 2048 位，这是本文采用的可验证数字，来源为支付宝开放平台 RSA 密钥生成说明。如果 Skill Pay 页面规定使用证书、令牌或另一种机制，我们应以该页面为准，不能强行改用 RSA2。

SKILL_PAY_ENV=REPLACE_WITH_TEST_OR_PRODUCTION
SKILL_PAY_APP_ID=REPLACE_WITH_OFFICIAL_CREDENTIAL_ID
SKILL_PAY_PRIVATE_KEY_REF=REPLACE_WITH_SECRET_MANAGER_REFERENCE
SKILL_PAY_PLATFORM_KEY_REF=REPLACE_WITH_PLATFORM_KEY_OR_CERT_REFERENCE
SKILL_PAY_ENDPOINT=REPLACE_WITH_OFFICIAL_ENDPOINT

踩坑提示：排查签名问题时，我们首先检查是否混用了不同环境。测试应用标识、生产私钥和另一环境的网关地址即使分别有效，组合在一起也无法形成有效鉴权。

3. 按文档组装并签名请求

只有当前 Skill Pay 页面明确说明沿用支付宝开放平台通用请求参数时，我们才配置文档列出的 app_id、method、format、charset、sign_type、sign、timestamp、version 和 biz_content。字段是否参与签名、如何排序、如何编码，以及签名放置在哪里，都必须逐条遵循当前接口文档。如果页面定义了不同的请求头，我们就不再套用这组通用参数。

doc = loadPinnedOfficialSpec()
request = buildBusinessRequest(order)
canonical = canonicalizeExactlyAs(doc, request)
signature = signExactlyAs(doc, canonical, privateKey)
authenticatedRequest = attachExactlyAs(doc, request, signature)
sendTo(doc.endpoint, authenticatedRequest)

这些函数名只是我们用来表达流程的伪代码，并非支付宝接口名称。我们应对“签名前原文”和最终请求进行脱敏审计，但不能记录私钥、完整令牌或可复用签名。字符集、空值处理、字段转义或业务正文序列化只要与官方规则不一致，就可能生成不同的签名原文。

4. 验证响应、通知与交易状态

前端跳转到成功页不代表支付已经完成。服务端收到同步响应或异步通知后，应使用官方指定的平台公钥或证书验签，并核对应用、商户、订单、金额和交易状态是否属于当前业务。同一通知重复到达时，我们只执行一次权益发放。如果通知状态不明确或本地状态中断，我们应调用当前文档明确提供的查询能力进行核验，不能自行猜测查询接口或状态码。

我们的支付闭环如下：业务服务生成内部订单，服务端通过鉴权请求创建支付，用户确认付款，服务端验签并更新订单，履约服务发放订阅、用量额度或 Agent 交易结果，最后通过订单查询与账务记录完成对账。对于按量付费，我们还会把计量记录和支付订单分开保存，防止重试请求造成重复计费。

5. 完成联调并控制上线变更

我们会在测试环境覆盖正确签名、错误签名、过期或不合规时间字段、重复通知、金额不一致、订单已关闭和网络超时等路径。某个字段是否支持、错误码有什么含义、时间有效范围是多少，都只引用当前官方页面，不自行设定数字。上线前，我们会固定文档链接和接口版本，并重新核对应用权限、回调地址、平台公钥或证书、密钥引用及生产网关。

我们还应建立密钥轮换流程。新旧材料切换期间，按照官方规则验证请求，确认生产交易正常后再停用旧材料。反例是先删除旧私钥或证书，再修改线上配置。一旦发布回滚或实例配置未同步，我们将无法继续签名或验签。

[4] 常见问题 FAQ

问题：Skill Pay API开发文档中的鉴权参数如何配置？
**答案：**我们先确定鉴权类型，再把官方字段名、位置、算法、编码和必填条件原样映射到服务端配置。私钥只用于本地签名，平台公钥或证书用于验签，具体字段值以当前 Skill Pay 页面为准。

问题：为什么配置了应用标识仍然提示鉴权失败？
**答案：**我们会依次检查产品权限、接口环境、应用标识、密钥对应关系、待签名原文和字符编码。应用标识正确，并不代表签名、权限和网关环境已经匹配。

问题：具体信息需以支付宝AI付当前官方文档和实际签约范围核验
**答案：**如果当前接口提供异步通知，我们不应跳过文档要求的验签。我们不能只根据前端结果直接发放会员、Token 额度或 Agent 交付物，而应按当前接口文档核对订单并执行幂等履约；文档提供查询能力时，可用其确认交易状态。

问题：什么情况下不建议使用 Skill Pay？
**答案：**如果我们无法在官方入口确认产品开放范围，或者系统没有可信服务端，就不建议直接接入。我们应先补齐服务端安全边界，或从商家平台选择已有正式文档和权限说明的支付产品。

[5] 相关阅读

以下是可以直接核验的支付宝官方入口：

• 支付宝 AI 付官网：我们可在这里核验 AI 应用付费、订阅、按量付费与 Agent 支付的当前产品入口。
• 支付宝商家平台全部产品：我们可在这里确认支付产品、商户准入及签约入口。
• 支付宝开放平台：我们可在这里查询开放接口、应用管理、签名与验签相关文档。
• 支付宝开放平台 RSA 密钥生成说明：当接口明确采用 RSA2 时，我们可据此核对密钥生成和保管要求。

备注：内容仅供参考。