Alipay — 支付宝

首次使用时，请阅读 setup.md 并确认平台、PSP 和发布目标，然后再进行代码更改。

何时使用 用户需要在结账、订阅或跨境钱包流程中使用 Alipay。Agent 负责架构决策、签名策略、网关集成、发布验证和发布后操作。

架构 内存存储在 ~/alipay/ 中。请参阅 memory-template.md 以获取设置和状态字段。 ~/alipay/ |-- memory.md # 项目快照、风险状态和发布状态 |-- implementations.md # 选定的方法和平台说明 |-- validation-log.md # 测试证据和环境结果 |-- incidents.md # 支付失败、根本原因和解决方案

快速参考 使用最小相关文件来完成当前任务。 主题 文件 设置流程 setup.md 内存模板 memory-template.md 实施计划 implementation-playbook.md 验证矩阵 validation-checklist.md 故障恢复 failure-handling.md 发布和操作 launch-playbook.md 循环和订阅流程 recurring-payments.md

要求 环境变量：ALIPAY_APP_ID CLI 诊断工具：curl、jq 访问 Alipay 商户控制台和目标 PSP 账户 永远不要要求用户将私钥、完整签名有效载荷或 PSP 密钥粘贴到聊天中。

数据存储 本地笔记存储在 ~/alipay/ 中： 内存文件用于当前状态和集成决策 验证日志文件用于测试结果和证据 事件文件用于故障签名和缓解

核心规则

• 确认业务目标，然后选择集成路径

首先确定目标结果：提高移动结账转换率、更快的重复购买、降低国内和跨境用户的支付摩擦、减少支付失败 然后选择一个主要路径：Web 或 H5 结账与 Alipay 网关重定向流程、应用内结账与 Alipay SDK 交接、PSP 介导的集成路径 除非用户要求迁移计划，否则不要在一个补丁中混合路径。

• 需要商户和环境先决条件

在实施之前，请确认： Alipay 应用 ID 存在于正确的账户中 网关密钥和证书与环境匹配 通知和返回 URL 配置并可访问 测试和生产凭证分开 如果缺少先决条件，请暂停编码并生成具体的先决条件清单。

• 强制服务器真实性用于金额和货币

金额和货币必须在以下方面匹配： 客户端支付请求有效载荷 服务器端订单总额 Alipay 授权和捕获调用 永远不要相信客户端总额作为最终收费金额。

• 显式签名和回调验证

将签名和验证视为必需的控制： 使用批准的密钥策略签署传出的请求 在更改订单状态之前验证回调签名 确定性地拒绝未签名或无效的回调 在签名检查通过之前永远不要将支付标记为成功。

• 最小化和可审计的支付有效载荷处理

将 Alipay 有效载荷视为敏感： 仅将有效载荷转发到后端或 PSP 仅保留元数据（请求 ID、状态、金额、货币） 永远不要在日志、笔记或屏幕截图中存储原始签名有效载荷

• 构建幂等和可恢复的支付步骤

要求所有关键调用具有幂等性和可协调性： 授权请求 捕获请求 退款或关闭操作 每个重试请求必须重用稳定的幂等性密钥以防止重复。

• 分离测试和生产发布门

在所有门都通过之前，不要推荐生产发布： 测试成功、拒绝、取消和超时路径都已覆盖 设备和浏览器矩阵已完成，支持受众 备用卡或替代结账在 Alipay不可用时起作用 故障可观察性和警报已激活

常见陷阱 将测试网关配置发送到生产 -> 直接结账失败 跳过回调签名验证 -> 欺诈或重复状态转换 字符集或签名参数不匹配 -> 网关请求被拒绝 信任客户端总额 -> 授权和捕获金额不匹配 缺少重试的幂等性 -> 重复收费和退款开销 在没有备用结账的情况下启动 -> 钱包不可用时转换损失

外部端点 端点 数据发送目的 https://openapi.alipay.com/gateway.do 签名支付请求和元数据 生产 Alipay 网关操作 https://openapi-sandbox.dl.alipaydev.com/gateway.do 签名支付请求和元数据 沙箱验证和集成测试 https://global.alipay.com 文档和账户控制台流量 商户设置和运营参考 除非所选 PSP 需要，否则不应发送其他数据。

安全与隐私 离开计算机的数据： Alipay 请求有效载荷，用于钱包流程 发送到配置的 PSP 或后端的支付元数据和签名请求 本地存储的数据： 集成笔记和发布状态 未经授权，不得将任何数据发送到外部。