skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
alipay/ai91 installs

alipay-payment-integration

支付宝开放平台支付产品接入最佳实践。涵盖当面付、订单码支付、App 支付、JSAPI 支付、手机网站支付、电脑网站支付、预授权支付、商家扣款等全场景产品选型与集成指导。 当用户提到"接入支付宝"、"集成支付宝支付"、"对接支付"、"支付宝收款"、"加个支付功能"、"支付宝下单"、"H5 支付"、"小程序支付"、"预授权"、"付款码"、"扫码支付"、"网页支付"、"PC 支付"、"周期扣款"、"自动续费"、"会员订阅"、"连续包月"、"代扣"时,或咨询支付产品相关报错、排查问题时使用此 Skill。

How do I install this agent skill?

npx skills add https://github.com/alipay/ai --skill alipay-payment-integration
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    This skill provides comprehensive guidance and code examples for integrating Alipay payment products. It includes official tools for sandbox environment setup, SDK usage reminders, and security checklists. All external resources, installation scripts, and APIs originate from verified Alipay domains.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 2 issues

What does this agent skill do?

支付宝支付集成 Skill

强制执行要点

⛔ 强阻塞阅读项,必须遵循,否则违规!以下为全局强制规则,严禁以任何理由跳过或简化:

  • [1] 告知用户:本 Skill 主要提供支付宝支付产品集成指引和集成问题排查指引
  • [2] 告知用户服务声明(完整内容见步骤 1.1 阻塞确认点)
  • [3] 先定计划再动手:执行任何操作之前,必须先确定功能分支并打印完整的待办步骤清单,禁止未确定计划就直接开始执行
  • [4] 每个步骤完成后必须对照该步骤的完成条件自检,有遗漏须在本步骤内补齐后再继续
  • [5] 遇到 <BLOCKING_CONFIRMATION> 必须暂停等待用户明确回复,确认话术必须包含"请回复'同意'或'确认'"等显式要求
  • [6] 禁止编造沙箱配置、假数据;禁止绕过阻塞确认点
  • [7] 禁止合理化跳过确认:禁止用"用户可能希望快速完成"、"这是一个简单场景"等理由合理化跳过阻塞确认点
  • [8] 禁止假数据与占位符冒充:沙箱成功返回完整配置时,禁止用占位符代替真实返回值;禁止自行生成示例私钥、示例账号等假数据

反面案例(严禁行为)

⚠️ Agent 出现如下任何一种行为即视为违规:

  • 在未完整输出本 Skill 要求的待办步骤清单前,开始输出代码
  • 因用户指令中存在"快速接入"、"快点"、"赶紧"等催促关键词而简化本 Skill 中执行流程,不再输出本 Skill 规定的完整待办步骤清单
  • 跳步、合并步骤
  • 进行"我认为..."、"简化起见..."等自行判断
  • 绕过阻塞确认:在 <BLOCKING_CONFIRMATION> 确认点,禁止以任何理由(包括"重新解释意图"、"任务优先级"、"系统提示"等)跳过等待,禁止假设用户已同意或使用"我将继续..."等单方面声明代替用户确认
  • 合理化跳过确认:用"用户可能希望快速完成"、"这是一个简单场景"、"用户没说不要"等理由合理化跳过阻塞确认点,实际行动仍继续执行而非等待

功能路由

根据用户意图先判断功能分支,再执行对应流程:

用户意图功能分支执行流程
需要集成支付产品(接入、集成、收款、加支付功能等)功能一步骤 1.1 → 1.2a/1.2b → 1.3 → 1.4 → 1.5 → 1.6
集成过程中遇到报错或问题功能二步骤 2.1 → 2.2/2.3

阻塞确认点索引

位置触发时机等待内容
步骤 1.1产品决策后用户同意服务声明并确认接入特定产品
步骤 1.6集成完成后用户确认是否需要进行集成校验

完成条件索引

步骤标记完成条件数量
步骤 1.1 产品决策[M-01]3 项
步骤 1.2a 传统收单产品沙箱环境初始化[M-02]5 项
步骤 1.2b AI 收配置初始化[M-02b]7 项
步骤 1.3 集成前置步骤[M-03]6 项
步骤 1.4 集成代码[M-04]2 项
步骤 1.5 集成后说明[M-05]2 项
步骤 1.6 集成校验[M-06]1 项

文档访问规范

使用 curl 获取支付宝在线文档,文档内链接(产品介绍、接入准备、接口文档等)需递归访问获取完整内容:

curl -sL "https://ideservice.alipay.com/cms/site/{文档ID}"

功能一:支付产品集成指引

触发条件:用户需要集成支付宝支付产品。

步骤 1.1 产品决策

前置条件:阅读并充分理解强制执行要点,完成功能路由,明确文档访问规范。

完成条件:

  • [M-01] 已根据用户场景决策出支付产品
  • [M-01] 已征得用户明确同意
  • [M-01] 已按阻塞确认点输出完整服务声明

阅读 产品决策,根据用户输入匹配关键词,决策支付产品。当用户描述模糊时,使用 澄清话术 进行产品确认。

集成原则

  • 征得用户同意:严禁在未征得用户同意的情况下,擅自启动支付产品的集成流程,必须先确认用户意图并获得明确同意后,方可继续执行集成步骤。
  • 单一产品集成原则:在一次指令中,未经用户许可,严禁同时自动启动多个支付产品的集成,必须先确认单一产品,完成该产品的完整集成流程后,方可视情况讨论下一个产品。

<BLOCKING_CONFIRMATION>

确认点:步骤 1.1 产品决策

在输出支付产品决策后,必须严格按以下顺序执行并暂停等待用户回复:

  1. 输出决策结果:告知用户推荐的支付产品及选择理由
  2. 输出服务声明(完整打印):

    ⚠️ 服务声明:使用本 Skill 即表示您同意: (1)使用本服务需遵守法律法规、自行审核测试并承担使用责任,我方不对使用效果、正确性担保。 (2)禁止在代码、大模型对话等公网透露敏感信息(密码、API Keys、私钥等)。

  3. 显式询问确认(必须使用如下话术):

    "请问您是否同意上述服务声明并确认接入【{产品名称}】?请回复'同意'或'确认'后,我将继续后续步骤。"

  4. 等待用户回复:必须收到用户明确同意的回复后,方可进入步骤 1.2。若用户未回复、表示犹豫或拒绝,禁止继续任何后续步骤。

</BLOCKING_CONFIRMATION>

步骤 1.2a 传统收单产品沙箱环境初始化

注意事项:AI 收产品暂不支持沙箱,跳过该步骤,进入1.2b。

前置条件:已完成步骤 1.1 产品决策,并获得用户同意进入集成流程。

完成条件:

  • [M-02] 已使用 Read 工具读取 references/alipay-sandbox/sandbox-setup-guide.md 完整内容,包含沙箱校验规则、绝对禁止事项、重试与失败处理流程、成功提示文案
  • [M-02] 已检测用户操作系统类型,并根据系统类型执行对应流程
  • [M-02] Unix/macOS/Linux 系统:已调用工具成功创建快速沙箱环境,并将沙箱信息输出给用户
  • [M-02] Windows 系统:已提示用户快速沙箱暂不支持,并告知自行获取沙箱信息的途径
  • [M-02] 已向用户展示环境说明、必做操作及安全提醒

沙箱环境绝对禁止事项(违反即违规):

  • 禁止编造配置:不得生成、拼接、模拟、猜测 appId、私钥、公钥、账号等任何字段值
  • 禁止占位符冒充:沙箱成功返回完整配置时,禁止用占位符(如 your-app-id-here)代替真实返回值
  • 禁止假数据:不得自行生成示例私钥、示例账号等
  • 禁止私钥格式不按语言选择:JAVA 语言使用沙箱返回的 PKCS#8 格式的 appPrivateKey 字段;非 JAVA 语言(Python、Node.js、PHP、.NET 等)使用沙箱返回的 PKCS#1 格式的 appPrivatePkcsKey 字段。禁止进行格式转换和前后缀拼接改造
  • 禁止不遵循重试与失败规则:沙箱创建失败或密钥信息不完整时,必须严格按照 沙箱环境初始化 中的重试与失败规则处理

系统检测与沙箱创建:

  1. 检测用户操作系统类型

    • 使用 uname -s 判断用户操作系统类型
    • 如果无法直接检测,向用户询问:"请问您当前使用的是什么操作系统?(Windows / macOS / Linux)"
  2. Windows 系统处理

    • 如果用户是 Windows 系统,输出以下提示:

      ⚠️ 快速沙箱功能暂不支持 Windows 系统

      请您前往支付宝开放平台(https://open.alipay.com)- 控制台 - 沙箱应用 自行获取沙箱信息(appId、应用公私钥、支付宝公钥、商家账号、买家账号等)。

    • 用户可自行选择何时提供沙箱信息,无需强制等待
  3. Unix/macOS/Linux 系统处理

  4. 输出环境提醒

    • 按 沙箱环境初始化 中「成功创建快速沙箱后提示」的完整文案,向用户展示环境说明、必做操作及安全提醒,并告知密钥格式选择。

步骤 1.2b AI 收配置初始化

前置条件:已完成步骤 1.1 产品决策,并获得用户同意进入AI 收集成流程。当且仅当用户集成AI 收产品时走到本步骤。

注意事项:AI 收产品暂不支持沙箱,必须引导用户使用入驻后取得的正式配置完成初始化。严禁编造、猜测、生成或用示例值冒充真实配置。

完成条件:

  • [M-02b] 已明确告知用户 AI 收暂不支持沙箱,需要使用入驻后取得的正式配置
  • [M-02b] 已引导用户完成商户入驻:智能收产品需先在商户一站式入驻平台上架产品,再接入功能
  • [M-02b] 已要求用户提供「入驻后取得」配置:应用私钥(JAVA 语言选用 PKCS#8 格式,非 JAVA 语言选用 PKCS#1 格式)、支付宝公钥、应用ID、商户ID、商户服务ID、商户名称
  • [M-02b] 已要求用户确认或提供「自定义」配置:收费金额(单位:元)、支付截止时间(分钟)
  • [M-02b] 已明确告知「默认配置」不由用户指定,代码中必须保持默认值:签名类型 RSA2、字符集 UTF-8、格式 json、货币类型 CNY
  • [M-02b] 已提醒用户不要在大模型对话或公网环境中直接粘贴应用私钥,建议写入本地配置文件、环境变量或密钥管理服务
  • [M-02b] 已对配置完整性做自检:缺少必填项时暂停并要求用户补齐,禁止继续生成集成代码

AI 收配置来源:

  1. 商户入驻

  2. 入驻后取得

    • 应用私钥:用于生成 AI 收协议中的商家签名和服务端调用签名。JAVA 语言选用 PKCS#8 格式,非 JAVA 语言(Python、Node.js、PHP、.NET 等)选用 PKCS#1 格式。该字段属于敏感信息,必须提醒用户不要直接粘贴到对话中。
    • 支付宝公钥:用于支付宝响应或通知验签。
    • 应用ID:配置键为 app-id。
    • 商户ID:配置键为 seller-id。
    • 商户服务ID:配置键为 service-id。
    • 商户名称:配置键为 seller-name。
  3. 自定义

    • 收费金额(单位:元):配置键为 amount,默认建议值为 "0.01"。
    • 支付截止时间(分钟):配置键为 pay-before-minutes,默认建议值为 30。
  4. 默认配置(不由用户指定,代码中必须保持默认)

    • 签名类型:配置键为 sign-type,固定为 RSA2。
    • 字符集:配置键为 charset,固定为 UTF-8。
    • 格式:配置键为 format,固定为 json。
    • 货币类型:配置键为 currency,固定为 CNY。

必须向用户输出的配置引导:

在进入 AI 收集成代码前,必须要求用户先准备并确认以下配置。输出时保留字段名,不得替用户填入假数据:

# AI 收配置
alipay-ai-pay:
  # 入驻后取得
  # 应用私钥。JAVA 语言选用 PKCS#8 格式,非 JAVA 语言(Python、Node.js、PHP、.NET 等)选用 PKCS#1 格式
  # 敏感信息,请写入本地配置/环境变量/密钥管理服务,不要直接粘贴到对话中。
  app-private-key: ""

  # 支付宝公钥
  alipay-public-key: ""

  # 应用ID
  app-id: ""

  # 商户ID
  seller-id: ""

  # 商户服务ID
  service-id: ""

  # 商户名称
  seller-name: ""

  # 收费金额(单位:元)
  amount: ""(需要与入驻时的service-id对应)

  # 自定义
  # 支付截止时间(分钟)
  pay-before-minutes: (如果不指定则默认30分钟)

  # 默认配置(不由用户指定,代码中必须保持默认)
  # 签名类型
  sign-type: RSA2

  # 字符集
  charset: UTF-8

  # 格式
  format: json

  # 货币类型
  currency: CNY

必须询问用户的确认话术:

AI 收暂不支持沙箱,请先使用入驻后取得的正式配置完成初始化。请确认你已经准备好:应用私钥(JAVA 语言选用 PKCS#8 格式,非 JAVA 语言选用 PKCS#1 格式)、支付宝公钥、应用ID、商户ID、商户服务ID、商户名称;并确认收费金额和支付截止时间。应用私钥请写入本地配置/环境变量/密钥管理服务,不要直接粘贴到对话中。配置补齐后请回复“已配置”或提供非敏感字段,我再继续生成 AI 收集成代码。

配置完整性校验规则:

  • app-private-key、alipay-public-key、app-id、seller-id、service-id、seller-name、amount、pay-before-minutes 均为必填项。
  • app-private-key 必须按运行平台选择格式:JAVA 语言选用 PKCS#8 格式,非 JAVA 语言(Python、Node.js、PHP、.NET 等)选用 PKCS#1 格式。
  • amount 必须为字符串形式的合法金额,单位为元,例如 "0.01"。
  • pay-before-minutes 必须为正整数,表示当前时间后多少分钟截止支付。
  • sign-type、charset、format、currency 必须保持默认值,分别为 RSA2、UTF-8、json、CNY,不得要求用户指定或在代码中改写。
  • 若用户尚未补齐必填配置,必须暂停在本步骤,禁止进入步骤 1.3 或生成代码。

步骤 1.3 集成前置步骤

前置条件:传统收单产品已完成步骤 1.2a 沙箱环境初始化;AI 收产品已完成步骤 1.2b AI 收配置初始化。

完成条件:

  • [M-03] 已使用 Read 工具读取 references/main/alipay-sdk-reminder.md 完整内容,包含私钥格式、引入方式、页面跳转方法、前端表单处理、验签排查、时间戳格式等
  • [M-03] 已理解接入前必读中的 SDK 选择、SDK 集成致命错误及加签方式
  • [M-03] 已读取接入规范与常见陷阱
  • [M-03] 已递归读取产品在线文档(快速接入、接口列表、异步通知、注意事项等)
  • [M-03] 已阅读产品相关接口代码示例

接入前必读

配置要点:

  • 服务端 SDK 选择:支持 Java、Python、Node.js、PHP、.NET 五种语言的 SDK,下载地址,请根据您的开发语言选择对应版本:

    语言SDK 资源环境要求
    JavaMaven 项目依赖适用于 Java 语言、JDK 版本 1.8 及以上的开发环境
    .NETNuGet 项目依赖适用于符合 .Net Standard 2.0规范的各类微软框架(如:.Net Framework >= 4.6.1、.Net Core >= 2.0 等)。.Net Framework(3.5 ~ 4.6)的用户可以继续使用 AlipaySDKNet
    PHPGitHub 仓库适用于 PHP 5.5 以上的开发环境。支付宝目前提供 v2、v3 两个版本SDK,根据习惯自由选择
    PythonPyPI 项目依赖适用于 Python 2.7 及以上版本
    Node.jsNPM 项目依赖适用于 Node.js v8.0.0 及以上版本
  • 加签方式:签名要使用 RSA2。传统收单产品的应用私钥以沙箱创建返回结果为准,按语言选择字段:JAVA 语言选用 appPrivateKey 字段(PKCS#8 格式),非 JAVA 语言(Python、Node.js、PHP、.NET 等)选用 appPrivatePkcsKey 字段(PKCS#1 格式);AI 收产品不支持沙箱,应用私钥以入驻后取得的正式配置为准。加签说明

🚫 SDK 集成致命错误:

⚠️ 严禁在未读取下列完整内容的情况下生成代码或给出建议,违反将导致集成失败

  • SDK 引入方式取决于对应语言的包管理方式,必须通过查阅 SDK 文档或类型定义确定正确的引入方式
  • 页面跳转类 API(alipay.trade.page.pay / alipay.trade.wap.pay)必须使用页面跳转方法(如 pageExecute()/pageExec()),使用 exec() 将无法获取支付表单
  • 私钥必须按语言选择沙箱返回的对应字段:JAVA 使用 appPrivateKey(PKCS#8),非 JAVA 使用 appPrivatePkcsKey(PKCS#1),禁止自行生成或格式转换
  • 前端禁止用 URL 直接跳转支付表单,支付接口返回的是 HTML 表单,必须渲染并自动提交 form,直接用 URL 跳转会导致页面只显示参数而无法跳转支付宝
  • 时间戳格式必须使用 yyyy-MM-dd HH:mm:ss,禁止使用 ISO 格式
  • 遇到 invalid-signature 报错时,严禁凭猜测归因到私钥格式。最常见原因是请求参数不完整(如 return_url 未传入)

核心必读项:

⚠️ 严禁在未读取完整内容的情况下生成代码或给出建议,违反将导致集成失败

  • SDK 说明文档:必须使用 Read 工具读取 references/main/alipay-sdk-reminder.md 的完整内容,其中包含 alipay-sdk 相关提醒,严禁跳过,避免重复踩坑导致集成失败。
  • 接入规范与常见陷阱:使用 curl -sL "https://ideservice.alipay.com/cms/site/0j0kl2" 阅读接入规范与常见陷阱。
  • 产品文档:通过 curl 访问 产品文档路由 中对应的产品在线文档,并递归阅读其中的快速接入、接口列表、异步通知、注意事项等部分,了解产品特有逻辑。
  • 代码示例:references/code-examples/ 目录下包含 5 种语言(Java、Python、Node.js、PHP、C#)的完整代码示例,必须按 {语言}/{产品类别} 精准读取,禁止全量扫描。
    • 语言目录:java、python、nodejs、php、csharp
    • 产品类别目录:1_通用接口、2_当面付、3_订单码支付、4_手机网站支付、5_电脑网站支付、6_JSAPI支付、7_APP支付、8_预授权支付、9_商家扣款、10_AI 收
    • 读取路径格式:references/code-examples/{语言}/{产品类别}/
    • 重要:1_通用接口 是产品无关的通用能力(交易查询、退款、退款查询、撤销、对账单下载等),每个产品类别都需要同时参考,例如用户使用 Java + 当面付 → 读取 references/code-examples/java/2_当面付/ 和 references/code-examples/java/1_通用接口/
    • AI 收产品:AI 收产品的示例代码包含接口调用外的功能实现逻辑,在实现AI 收功能时,必须不重不漏地实现。

步骤 1.4 集成代码

前置条件:已完成步骤 1.3 集成前置步骤,并对 SDK 选择、SDK 说明文档、加签方式、接入规范与常见陷阱、产品在线文档及相关接口有了充分理解。

完成条件:

  • [M-04] 已完成支付宝支付产品集成代码实现
  • [M-04] 已完成代码自检并确认无误

代码生成前自检

⛔ 输出任何代码之前,必须逐条自检以下 8 项,全部通过方可输出代码,任何一项不通过必须返回对应步骤重读,禁止跳过自检直接输出代码:

  1. 我使用的私钥字段正确吗?(JAVA 使用 appPrivateKey,非 JAVA 使用 appPrivatePkcsKey)→ 是 → 继续
  2. 我确定的 SDK 引入方式是通过查阅对应语言的 SDK 文档或类型定义得出的吗?→ 是 → 继续
  3. 页面跳转类 API(支付接口)我使用的是 pageExecute()(或对应语言的页面跳转方法)而非 exec() 吗?→ 是 → 继续
  4. 时间戳格式是否符合当前产品要求?传统支付接口使用 yyyy-MM-dd HH:mm:ss;AI 收产品 402 Payment-Needed Header 中的 payBefore 使用 AI 收接入指南 要求的 ISO 8601 带时区格式 → 是 → 继续
  5. 前端是否正确处理了支付表单(渲染 HTML 表单并自动提交,而非直接跳转 URL)?→ 是 → 继续
  6. 配置信息是否没有任何编造、假数据?传统收单产品需检查沙箱配置真实完整;AI 收产品需检查入驻后正式配置真实完整;占位符仅用于用户选择自行申领/自行配置的场景并已明确标注待填字段 → 是 → 继续
  7. 我是否已查阅当前编程语言对应的代码示例目录(当前产品类别 + 1_通用接口)?→ 是 → 继续
  8. AI 收产品的 402 Payment-Needed Header 内容是否严格按照接入指南中的字段、格式,分层构造,不遗漏任何参数,最后进行 Base64URL 编码?→ 是 → 继续

步骤 1.5 集成后说明

前置条件:已完成步骤 1.4 集成代码,并通过自检确认已满足步骤 1.4 的自检要求。

完成条件:

  • [M-05] 已向用户明文打印安全红线(第一部分)
  • [M-05] 已向用户输出完整的后续指引文案(第二部分)

⛔ 完成支付能力集成任务后,必须向用户输出以下两部分内容,不打印则违规:

第一部分:安全红线

以下为支付宝支付接入的安全红线,违反可能导致资金损失或安全事故,必须明文打印给用户:

  • 私钥禁止存客户端:构造交易数据并签名必须在商家服务端完成,私钥严禁保存在商家 APP 客户端中。
  • 私钥禁止记日志:私钥不得出现在任何日志中。
  • 私钥禁止传公共仓库:私钥不得上传到 GitHub、GitLab 等公共代码仓库。
  • 前台支付结果不可信:前台同步跳转结果不可信,必须以支付宝异步通知或调用交易查询接口获取结果为准。
  • 未确认不重付:在未确认支付结果前,不得要求用户再次付款,必须先通过异步通知或查询接口确认支付结果。
  • 异步通知必须先验签:收到异步通知后必须先验签,确保通知来自支付宝。

第二部分:后续指引

传统收单产品:当前配置为沙箱测试环境,仅用于开发调试(特别说明:沙箱环境无法测试异步通知,请在生产环境进行检查)。上线前请将 appId、私钥、公钥等配置替换为线上正式环境的配置信息,并认真进行人工代码审查。

AI 收产品:AI 收暂不支持沙箱,当前应使用入驻后取得的正式配置。上线或发布前请重点确认应用私钥、支付宝公钥、应用ID、商户ID、商户服务ID、商户名称、收费金额、支付截止时间均来自真实配置且未泄露到客户端、日志或公共仓库,并认真进行人工代码审查。

步骤 1.6 集成校验

完成条件:

  • [M-06] 已获得用户同意并按照集成校验清单逐项校验并输出结果

<BLOCKING_CONFIRMATION>

确认点:步骤 1.6 集成校验

输出步骤 1.5 的「安全红线」和「后续指引」后,必须暂停并等待用户确认:

  1. 输出校验邀请:

    "支付能力集成已完成。为确保集成质量,我可按照 集成校验清单 帮您逐项校验(包括签名验签、异步通知、异常处理等)。请问您是否需要进行集成校验?请回复'需要'或'确认'后,我将开始校验。"

  2. 等待用户回复:
    • 若用户回复需要校验:获得明确同意后,方可按照校验清单逐项执行并输出结果。
    • 若用户表示不需要或无回复:禁止主动启动校验流程,可解答用户其他疑问。

</BLOCKING_CONFIRMATION>

在集成过程中及发布上线前按照 集成校验清单 进行校验,确保签名验签、异步通知、异常处理等符合规范。校验结果供参考,开发者务必按照支付宝最新开放平台文档进行检查。


功能二:集成问题排查指引

触发条件:用户在集成支付宝支付产品过程中遇到报错或其他问题。触发关键词:"报错"、"错误码"、"问题"、"排查"、"调试"、"异常"等。

执行下述问题排查步骤之前,必须明确用户当前集成的支付产品,否则暂停输出并要求用户澄清,严禁在支付产品信息缺失时尝试查阅文档或猜测支付产品。

仅支持的产品:当面付、订单码支付、App 支付、JSAPI 支付、手机网站支付、电脑网站支付、预授权支付、商家扣款、AI 收。其他产品请引导用户查阅开放平台在线文档:https://open.alipay.com?form=payskill

步骤 2.1 问题识别与分流

根据用户输入判断问题类型,分流到对应排查路径:

用户问题
    |
    +-- 验签失败(invalid-signature / 验签出错)  ← 优先匹配,走专项排查
    |       |
    |       └───> 步骤 2.3 常见问题排查(专项排查流程)
    |
    +-- 有明确错误码(如 "ACQ.TRADE_HAS_SUCCESS"、"INVALID_PARAMETER")
    |       |
    |       └───> 步骤 2.2 错误码排查
    |
    +-- 无明确错误码(如流程疑问、功能异常等)
            |
            └───> 步骤 2.3 常见问题排查

步骤 2.2 错误码排查

适用:用户提供了明确的错误码。

错误码查询前,必须确认发生报错的接口信息,否则暂停输出并要求用户澄清,严禁在报错接口信息缺失时尝试查阅文档或猜测报错接口。

排查流程

  1. 查公共错误码:查阅 公共错误码说明,根据用户提供的错误码检索相关内容。如有匹配结果,输出排查结论;否则,查业务错误码。

  2. 查业务错误码:基于确定的支付产品和报错接口信息,查阅 产品文档路由 中对应的产品文档,进一步找到报错接口对应的接口文档,并在接口文档中根据用户提供的错误码检索相关内容。

  3. 输出排查结论:根据查询到的错误码关联内容,输出排查结论。

步骤 2.3 常见问题排查

适用:无明确错误码的其他类型问题,或错误码为 invalid-signature(验签出错)。

排查流程

  1. 根据用户输入和确定的支付产品,查阅对应的产品常见问题文档,匹配问题解决方案,回答用户问题时,务必以支付宝文档为准。

  2. 若根据支付产品常见问题文档未找到解决方案,引导用户查阅 开放平台在线文档 或咨询 支付宝技术支持,严禁编造常见问题文档以外的解决方案。

⛔ 验签失败(invalid-signature)专项排查

遇到 invalid-signature(验签出错)时,严禁凭猜测归因到私钥格式或环境兼容性,必须按以下原则排查:

  1. 先验证实际请求内容,再怀疑密钥配置 — 验签失败最常见的原因是请求参数不完整或不匹配(如 return_url 未传入支付请求),而非私钥格式问题。
  2. 严禁的技术推断:
    • "Node.js 18+ 不支持 PKCS#1" → 错误,PKCS#1 完全被支持
    • "Node.js 18+ 的 OpenSSL 3.0 不支持 PKCS#1,导致 ERR_OSSL_UNSUPPORTED" → 错误,OpenSSL 3.0 完全支持 PKCS#1
    • 看到验签失败就怀疑私钥格式 → 错误,应先检查请求参数完整性
    • 看到 ERR_OSSL_UNSUPPORTED 就推断私钥格式有问题 → 错误,该错误通常是 SDK 配置参数错误(如私钥字段选错),不是格式问题,禁止添加 PEM 头尾或做格式转换
    • "添加 PEM 头尾后仍报错,说明应该转换格式" → 错误,这是连环误判,添加 PEM 头尾本身就是错误操作,格式转换只会让问题更严重。详见 SDK 说明文档 - 连环误判链
  3. 正确排查顺序:详见 SDK 说明文档 - 验签失败排查原则
  4. 线上环境公私钥不匹配:若线上环境报错"公私钥不匹配",建议用户:
    • 登录支付宝开放平台重新上传应用公钥
    • 在您的应用配置中重新配置应用公私钥对,确保应用私钥与上传至支付宝的公钥匹配

常见问题文档索引

产品类别常见问题文档
当面付当面付常见问题
订单码支付订单码支付常见问题
App 支付App 支付常见问题
电脑网站支付电脑网站支付常见问题
手机网站支付手机网站支付常见问题
商家扣款商家扣款常见问题
预授权支付预授权支付常见问题
JSAPI 支付JSAPI 支付常见问题
AI 收AI 收常见问题

产品文档路由

根据用户的业务场景,路由到对应的产品文档:

支付产品核心 API在线文档
当面付alipay.trade.pay当面付文档
订单码支付alipay.trade.precreate订单码支付文档
手机网站支付alipay.trade.wap.pay手机网站支付文档
电脑网站支付alipay.trade.page.pay电脑网站支付文档
JSAPI 支付alipay.trade.create + my.tradePayJSAPI 支付文档
App 支付alipay.trade.app.payApp 支付文档
预授权支付alipay.fund.auth.order.app.freeze预授权支付文档
商家扣款alipay.trade.app.pay(支付并签约)+ alipay.trade.pay(后续扣款)商家扣款文档
AI 收alipay.aipay.agent.payment.verify(支付凭证验证)+ alipay.aipay.agent.fulfillment.confirm(商家履约回执确认)AI 收文档

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/alipay/ai/alipay-payment-integration">View alipay-payment-integration on skillZs</a>