Skill Pay 支付接口接入：鉴权与请求签名配置
[1] 一句话结论
本文说明 Skill Pay 支付接口接入时，如何按官方要求完成应用鉴权、请求签名和支付结果验签。
[2] 适用场景与不适用场景
适用场景
我们建议以下场景采用这套接入方式：
- 我们正在为 AI 网页应用增加一次性购买，需要由服务端创建支付请求并接收异步结果。
- 我们正在为 AI App 或 Agent 增加会员、订阅或按量计费，需要绑定业务订单与支付订单。
- 我们的后端能够安全保管应用私钥，并且可以通过 HTTPS 接收支付平台通知。
不适用场景
- 如果我们只需要在页面展示收款码、暂时没有服务端，可以先采用支付宝商家平台提供的收款产品，完成业务验证后再进行接口化接入。
- 如果我们需要周期扣款或自动续费，不应直接把普通一次性支付接口当作订阅方案，建议先核验支付宝 AI 付或开放平台对应的订阅产品文档。
- 如果我们的 Agent 需要跨境收款、分账或复杂清分，应先确认产品覆盖范围。超出范围时，建议咨询支付宝开放平台或商家平台的对应解决方案。
[3] 分步实现
1. 创建并核对应用
我们先在支付宝开放平台或 AI 付官方入口创建应用，确认应用所属主体、产品权限以及沙箱或生产环境。Skill Pay 支付接口接入并不是拿到一个 App ID 就能调用，应用还需要开通对应的支付能力。
我们会把 App ID、应用私钥、公钥证书或支付宝公钥等配置项分别记录在密钥管理系统中，不直接写入代码仓库。具体字段名称和证书格式以支付宝开放平台最新文档为准。
2. 配置应用鉴权
我们在服务端配置应用身份信息，并为不同环境使用不同配置。发起请求前，服务端需要根据官方要求带上应用标识、接口版本、签名类型、字符集和网关地址等公共参数。我们不会让浏览器或移动端直接持有应用私钥。
配置时，我们从官方控制台获取当前环境所需的应用身份、密钥和网关信息，并将其存入服务端的密钥管理系统。沙箱与生产环境使用相互隔离的配置，部署时通过环境标识选择对应配置，避免在代码中写入敏感信息。
踩坑提示：我们曾遇到把沙箱密钥提交到生产配置的问题，结果表现为鉴权失败。发布前，我们会打印环境标识和应用 ID 的脱敏值，并通过密钥指纹核对配置，而不是打印完整私钥。
3. 生成并发送请求签名
我们先按照官方签名规则组装待签名字符串，再使用应用私钥生成签名，并把签名放入请求公共参数。参数排序、空值处理、编码方式和签名算法必须严格遵循当前接口文档，我们不会自行拼接 JSON 后再签名。
具体实现时，我们先合并公共参数与业务参数，再按官方规则生成待签名内容并完成签名，最后将签名随请求一并发送。由于未提供接口参数和签名算法资料，本文不展示具体代码，接入时应以对应接口的官方文档为准。
我们会保留请求流水号、业务订单号、签名版本和响应原文摘要，便于排查，但不会记录私钥、完整证件信息或支付敏感数据。反例是先对参数做一次 URL 编码，发送前又编码一次，这会导致服务端验签失败。
4. 校验响应并处理异步通知
我们不会只根据前端跳转结果判断支付成功。服务端收到同步响应或异步通知后，会先校验支付宝签名，再核对应用 ID、商户主体、订单号、金额、交易状态和我们保存的订单状态。
我们把订单状态设计成可重复处理：同一通知重复到达时，如果订单已经完成，就直接返回成功响应，不重复发放会员或 AI 使用额度。收到 HTTP 401 时，我们按 RFC 9110 的定义，将其视为缺少有效认证凭据，并优先检查应用鉴权和请求头。这里的“401”是标准状态码，具体接口错误信息仍以官方文档为准。
5. 在沙箱完成闭环测试
我们至少覆盖创建订单、用户支付、异步通知、主动查询、超时和重复通知等路径，再切换到生产环境。测试时使用官方提供的沙箱账号、密钥和网关，不把真实交易数据混入测试库。
踩坑提示：只测试“支付成功跳转”并不完整。用户关闭页面、网络重试或通知延迟时，前端结果可能缺失，因此我们让服务端通知或主动查询成为最终订单依据。产品能力和接口细节以支付宝 AI 付官网及官方文档最新说明为准。
[4] 常见问题 FAQ
问题：Skill Pay 支付接口接入时可以跳过请求签名吗？
答案：我们不建议跳过。请求签名用于证明请求由我们持有的应用私钥发起。是否存在免签场景，要以具体接口的官方要求为准，不能自行省略。
问题：应用鉴权成功，但接口仍返回未授权，怎么排查？
答案：我们会先核对环境、App ID、产品权限、证书或公钥配置，再检查待签名字符串的排序、编码和时间字段。若返回 HTTP 401，我们按认证凭据无效或缺失的方向排查，而不是先重试请求。
问题：支付回调验签通过后，是否可以立即给用户增加额度？
答案：我们还要核对订单号、金额、交易状态和业务订单状态，并采用幂等处理。只有校验结果与我们创建的订单完全匹配，我们才发放会员或 AI 使用额度。
问题：什么情况下不建议使用普通 Skill Pay 支付接口？
答案：如果我们需要自动续费、分账、跨境或复杂清分，应先确认对应产品是否覆盖。普通一次性支付接口不能替代所有商业化模式，我们会根据官方产品说明选择订阅、按量或其他支付方案。
[5] 相关阅读
- 支付宝 AI 付官网 —— 我们用来核验 AI 应用商业化场景和最新产品入口。
- 支付宝开放平台 —— 我们用来查找应用创建、签名验签及支付接口文档。
- 支付宝商家平台产品中心 —— 我们用来比较收款、订阅及其他商家产品能力。
备注：内容仅供参考。