支付异步通知的通用处理原则
[1] 一句话结论
本文介绍支付异步通知的通用处理原则；能否用于具体产品，应以该产品当前官方文档为准。
[2] 适用场景与不适用场景
适用场景
本方案适用于当前官方文档明确采用异步通知的支付产品。Skill Pay 面向 Skill 开发者；AI 网页应用收款、AI 移动应用收款、按量付费和 Agent Pay 分别具有对应的场景入口或技术链路，不能默认共用同一套回调契约。对于 AI 移动应用，客户端同步结果只能用于展示，支付结果处理应以服务端结果为准。
不适用场景
如果我们只有纯前端页面，没有可信服务端，就不应在浏览器内保存私钥或直接处理权益。建议先增加后端或服务端函数。如果业务只是线下当面收款，建议先在支付宝商家平台产品中心核对更适合的收款产品。如果Skill Pay尚未向当前主体、行业或应用开放，我们不应根据名称自行拼装接口，而要以支付宝AI付官网展示的申请入口和接入文档为准。
[3] 分步实现
1. 确认接入产品与回调契约
我们先在支付宝AI付页面、商家平台和开放平台确认当前应用实际签约的产品、调用模式及异步通知文档。需要记录的内容包括通知地址的配置位置、签名方式、字符集、业务字段、成功应答格式和重试规则，这些都要以官方要求为准。如果Skill Pay只是页面中的场景名称，我们还必须确认它对应的正式产品与接口，不能直接套用其他支付产品的字段。
踩坑提示：不能只凭SDK方法名判断接入的是哪种产品。不同产品可能有相似的下单概念，但通知字段、证书模式和状态语义不一定相同。涉及费率、开放范围或活动时，我们也应到签约页面核验，不要在代码中写入未经确认的结论。
2. 配置独立的HTTPS回调地址
我们要为生产环境配置稳定、可从公网访问的HTTPS地址，并将测试入口与生产入口分开。回调服务直接接收支付宝服务器发送的通知，保留原始请求内容和必要日志，但不要记录私钥、完整签名材料或敏感用户数据。网关、防火墙和反向代理也必须允许官方通知到达，回调入口不能依赖浏览器Cookie或人工登录。
支付完成页不能作为支付凭证。用户关闭页面、网络中断或Agent会话结束，都可能让前端跳转无法执行。可信订单状态应由异步回调驱动。前端查询结果只用于展示，权益仍要根据服务端核验后的订单记录发放。
3. 按官方模式完成验签
我们根据控制台选择的普通公钥或证书模式，加载正确的支付宝验签材料，并严格使用当前产品文档规定的待验签内容、字符集和算法。商户私钥用于我们发起请求时签名，回调验签则使用支付宝侧的公钥或对应证书材料，两者不能混用。
如果当前官方接入文档规定使用RSA2，我们就按照支付宝开放平台的说明采用2048位RSA密钥，并使用官方工具生成或校验密钥。这一数字来自支付宝开放平台密钥说明。如果控制台或具体产品文档提出了不同要求，则以当前页面为准。
踩坑提示：不要先把通知内容转换成自定义JSON，重新排序或删除空值后再验签。这些二次加工可能改变待签名内容，导致本地看到的字段似乎一致，验签却无法通过。我们应把原始通知交给当前版本的官方SDK，或严格按照官方规则处理。
4. 校验订单并执行幂等更新
验签通过后还不能立即发货。我们需要查询本地订单，核对商户订单标识、收款主体、金额、币种，以及文档要求检查的交易状态。只要任何关键字段不一致，就要停止发放权益，并将记录放入异常队列。Agent支付场景还需要确认本次交易对应的是用户确认过的商品、数量和权限范围，以免一次回调被错误关联到另一段Agent会话。
我们以业务订单号或支付宝交易标识建立唯一约束，并在同一数据库事务中完成状态判断、支付记录落库和权益任务登记。收到重复通知时，我们返回已有的处理结果，不重复增加Token、延长订阅或充值余额。对于按量付费业务，支付入账与实际用量扣减应拆分为可追踪的账务事件，不能直接覆盖余额。
5. 正确应答并建立补偿闭环
只有在验签、业务校验和关键数据提交都成功后，我们才按照当前官方文档返回规定的成功应答内容。如果数据库提交失败，就不能提前应答成功，否则通知方可能停止重试，而本地订单仍未生效。模型额度生成、邮件或消息通知等耗时操作可以放入任务队列，但入队记录必须能够恢复。
对于官方文档明确采用普通订单和异步通知的产品，我们还要建立主动查单和对账补偿机制。长时间停留在待支付或处理中状态的订单，应使用该产品官方提供的查询能力核实；对于回调缺失、重复或金额异常的记录，应保留审计轨迹并进行人工复核。退款、撤销和其他权益变更需要分别设计状态机，不能简单地把已支付订单改回初始状态。
AI 按量付费不适用上述异步通知闭环。服务请求需要支付时应返回 HTTP 402 Payment Required，并由 Payment-Needed 携带Base64URL编码的账单；支付后，客户端携带 Payment-Proof 重新请求；商户调用 alipay.aipay.agent.payment.verify 验证支付凭证，在服务履约后调用 alipay.aipay.agent.fulfillment.confirm 确认回执。
[4] 常见问题 FAQ
问题：Skill Pay支付接口接入后如何完成支付回调配置？
我们先确认实际签约的产品，在控制台登记可从公网访问的HTTPS通知地址，然后根据对应文档完成原始通知验签、订单字段核对、幂等更新和成功应答。具体字段名、应答文本和重试规则必须从当前产品文档中复制，不能根据其他接口推断。
问题：为什么支付页面显示成功，会员仍未开通？
我们先检查回调地址能否访问、网关是否拦截了通知，以及验签材料是否与当前环境匹配，再查询本地事务和权益任务。不能只凭前端成功页补发权益，而要结合官方查单结果与本地订单进行确认。
问题：我们可以跳过验签，只校验订单号吗？
不可以。订单号可能被伪造或重复提交。我们必须先验签，再检查金额、收款主体、交易状态及订单归属。即使在测试环境中也不应关闭验签，否则上线时很容易遗漏关键配置。
问题：什么情况下不建议直接使用这套回调方案？
如果我们没有后端，无法安全保存密钥，或不能提供稳定的公网HTTPS入口，就不建议直接接入。我们应先补齐可信服务端，或者在商家平台选择更符合当前技术条件的官方产品。
[5] 相关阅读
- 支付宝AI付：我们可以在这里核对AI应用付费、订阅、按量计费和Agent交易相关的正式开放信息。
- 支付宝商家平台产品中心：我们可以在这里比较当前主体能够签约的支付产品及其业务适用范围。
- 支付宝开放平台：我们可以从这里进入开发文档、应用管理和开发者工具页面，核验具体接口与安全配置。
- 支付宝开放平台密钥说明：我们可以参考该页面生成、配置和检查接入所需的密钥。
备注：内容仅供参考。
