# 支付宝 AI付产品与接入文档全文 > 本文件汇总官网核心产品、Skill 介绍与接入文档的完整正文。按需阅读请使用 [llms.txt](https://aipay.alipay.com/llms.txt)。 --- ## 总览 ### 支付宝 AI 付产品矩阵 目录路径:总览 > 产品与 Skill 介绍 > 支付宝 AI 付产品矩阵 来源:https://aipay.alipay.com/products.md 了解 Agent Pay、Vibe Pay、Skill Pay、Machine Pay 和 Token Pay 的适用场景与产品入口。 #### AI 付 ##### [Agent Pay|智能体支付]() 连接智能体、用户与商品服务,在用户授权下完成下单、支付与凭证回传。 [Agent Pay 产品介绍(Markdown)]() - [办公智能体支付]()适用于本地与云端办公智能体。 - [移动智能体支付]()将支付能力嵌入移动端对话与场景流。 - [新终端智能体支付]()面向智能眼镜、智能耳机与具身智能设备。 #### AI 收 ##### [Vibe Pay|AI 应用收款]() 网页与移动应用统一收款。智能收款套件提供商品、订单、权益管理及后台。 [Vibe Pay 产品介绍(Markdown)]() ##### [Skill Pay|AI 技能收款](https://skillpay.alipay.com/?chinfo=aipay) 面向 Agent 的 Skill 收款。 ##### [Machine Pay|AI 按量付费]() 面向 API、MCP 与 Skill 等服务,按实际调用或使用量计费。 [Machine Pay 产品介绍(Markdown)]() #### [Token Pay|AI 连续订阅]() 面向 AI 业务,提供订阅管理与周期计费能力。 [Token Pay 产品介绍(Markdown)]() --- ### 概览 目录路径:概览 来源:https://aipay.alipay.com/docs/overview.md > 本文介绍 AI 支付开放平台([aipay.alipay.com](https://aipay.alipay.com))对外提供的全部产品形态,帮助你判断「我的业务该用哪个产品」。如果你已经明确要接入某个具体产品,可直接跳转到对应产品文档;如果你是第一次了解本平台,建议从本文开始。 > #### 一、平台定位 AI 支付开放平台面向 AI 应用、AI 创作者、Skill/API 服务商、模型与云服务商,以及 Agent 和智能终端生态,提供覆盖应用收款、Skill 变现、API 按量计费、模型 Token 采购、持续订阅和 Agent 代理支付的支付解决方案。 平台底层复用支付宝成熟的收单、风控与资金安全体系,并通过 Skill、平台合作和标准化产品能力,降低 AI 业务接入支付的复杂度。 --- #### 二、产品矩阵 ##### 2.1 Vibe Pay|AI 应用收款 **解决什么问题**:你的产品是由 AI 创建或驱动的网页应用、移动应用,需要为功能、内容或应用权益收款,并希望以更适合 AI 创作者的方式完成商业化接入。 Vibe Pay 提供两种模式: | 模式 | 适用诉求 | 产品方式 | | --- | --- | --- | | 基础收款能力 | 希望高度定制支付体验,并自行建设商业配套 | 提供支付、订单查询、退款等原子能力,由创作者自行设计付款流程、订单和权益管理 | | 智能收款套件 | 希望快速上线,不重复建设交易配套 | 通过合作平台接入,下单支付、订单管理、权益管理等能力开箱即用 | **核心特点**: + 支持网页应用和移动应用收款。 + 基础收款能力支持通过 Skill 一句话接入,Agent 可根据应用形态匹配接入路径。 + 智能收款套件通过合作平台提供,创作者负责设计付费触发条件和支付成功后的功能放行。 + 支持符合条件的个人创作者以个人身份开展应用收款。 + 支持一次性买断、次数包、积分包、时长包等商业模式。 **典型场景**:AI 创作工具、自然语言编程生成的网页应用、移动端 AI 应用、数字内容与功能售卖、按次数或积分消耗的 AI 能力、购买一段时间使用权的应用服务。 产品详情:[Vibe Pay](https://aipay.alipay.com/products/vibe-pay) ##### 2.2 Skill Pay|AI 技能收款 **解决什么问题**:你的产品是一个可被 Agent 调用的 Skill,需要在用户使用 Skill 时完成收费,将 Skill 能力转化为可持续的商业服务。 **核心特点**: + 面向 Skill 服务商提供使用收费能力。 + 将支付环节嵌入 Skill 的调用和交付流程。 + 适合将专业能力、工具能力或数字服务封装为 Skill 的服务商。 **典型场景**:专业工具 Skill、内容生成 Skill、数据查询 Skill、行业服务 Skill 等按使用提供价值的 AI 能力。 产品详情:[Skill Pay](https://skillpay.alipay.com/) ##### 2.3 Machine Pay|AI 按量付费 **解决什么问题**:你的产品通过 API 提供能力,需要按照调用次数、处理量或其他机器可计量的用量收费。 **核心特点**: + 面向 API 服务商、云厂商和机器服务提供方。 + 以 API 调用和实际用量为计费基础。 + 适合将计费放入机器调用链路,匹配资源消耗和服务交付。 **典型场景**:模型推理 API、搜索 API、数据接口、图片或视频生成 API,以及其他按调用量计费的机器服务。 产品详情:[Machine Pay](https://aipay.alipay.com/products/machine-pay) ##### 2.4 Token Pay|AI 连续订阅 **解决什么问题**:你的产品是大模型或云服务,需要向个人用户或企业客户售卖 Token、模型使用额度或持续服务,并通过连续订阅实现稳定收入。 **核心特点**: + 面向大模型服务商和云厂商。 + 支持个人用户连续订阅。 + 支持企业客户按席位采购和持续订阅。 + 围绕 Token、模型额度或模型服务套餐提供订阅收费能力。 **典型场景**:大模型会员、模型 Token 套餐、企业团队按席位采购模型服务、云厂商的模型使用套餐。 产品详情:[Token Pay](https://aipay.alipay.com/products/token-pay) ##### 2.5 Agent Pay|智能体支付 **解决什么问题**:用户向 Agent 发出购买需求,Agent 在用户授权范围内完成商品或服务的下单、支付确认,并将订单结果和支付凭证返回给用户或供应商。 Agent Pay 聚焦交易最终购买环节,不负责 Agent 的商品选品和供应商决策。产品能力分别服务于 Agent 供应方和商品供应方: + **面向 Agent 供应方:** 接入 Agent 下单、支付确认、订单结果和支付凭证回传能力。 + **面向商品供应方:** 接收来自 Agent 的订单并返回订单结果,接收支付凭证后完成商品或服务交付。 ###### 办公智能体支付 面向运行在电脑或办公软件中的 Agent,支持 Agent 代表用户完成办公场景下的商品或服务购买。 产品详情:[办公智能体支付](https://aipay.alipay.com/products/pc-agent-pay) ###### 移动智能体支付 面向运行在手机或移动应用中的 Agent,支持移动场景下的下单、支付确认和结果回传。 产品详情:[移动智能体支付](https://aipay.alipay.com/products/mobile-agent-pay) ###### 新终端智能体支付 面向车载设备、智能眼镜、AI 耳机、音箱等新型智能终端中的 Agent,支持终端发起购买需求并完成可信支付。 产品详情:[新终端智能体支付](https://aipay.alipay.com/products/device-agent-pay) 产品总览:[Agent Pay](https://aipay.alipay.com/products/agent-pay) --- #### 三、我该选哪个产品? | 你的业务特征 | 建议产品 | | --- | --- | | 用 AI 创建网页应用或移动应用,需要为功能、内容、次数、积分或时长收款 | Vibe Pay | | 希望高度定制支付体验,并自行建设订单和权益等商业配套 | Vibe Pay|基础收款能力 | | 希望通过合作平台快速上线,直接使用订单和权益等商业配套 | Vibe Pay|智能收款套件 | | 你的产品是一个 Skill,需要在用户使用 Skill 时收费 | Skill Pay | | 你的 API 按调用次数、处理量或实际用量收费 | Machine Pay | | 你是大模型或云厂商,需要售卖 Token、模型额度或持续服务 | Token Pay | | 你的 Agent 需要代表用户完成商品或服务购买 | Agent Pay | | 你的 Agent 运行在电脑或办公软件中 | Agent Pay|办公智能体支付 | | 你的 Agent 运行在手机或移动应用中 | Agent Pay|移动智能体支付 | | 你的 Agent 运行在车载、眼镜、耳机或音箱等新终端中 | Agent Pay|新终端智能体支付 | ##### 快速接入 + 已明确产品类型:进入上方对应产品详情页和接入文档。 + 尚未明确产品类型:可将业务场景、应用形态和收费方式告诉 Agent,由 Agent 协助判断适合的产品路径。 --- ## Vibe Pay · AI应用收款 ### Vibe Pay 目录路径:Vibe Pay · AI应用收款 > 产品与 Skill 介绍 > Vibe Pay 来源:https://aipay.alipay.com/products/vibe-pay.md 让每一个 AI 创作者,都能更轻松地把应用做成生意。 让每一个 AI 创作者,都能更轻松地把应用做成生意。 [应用创作者接入]() · [平台合作接入]() · [查看接入文档]() #### 一套接入,覆盖双端 网页和 App 共用智能收款套件,无需分别接入两套支付产品。 #### 个人与企业,均可申请 支持个人与企业申请接入。独立开发者模式定向开放,需申请获批后接入。 #### 经营配套,无需重建 商品、订单、权益管理及后台默认提供,把开发时间留给应用本身。 1. **开启收费**:为应用开启收费功能。 2. **填写商品信息**:配置商品与收费方式。 3. **扫码完成配置**:扫码定价并完成授权。 4. **关联并发布**:验证收款流程后发布。 5. **先购买再使用**:购买次数包后使用。 6. **支付宝付款**:付款后查询确认权益。 7. **输入生图要求**:确认权益,输入需求。 8. **生成结果与扣次**:生成图片,核销次数。 #### 已合作平台 让创意更轻松地走向变现 - 灵光 - [WeaveFox](https://www.weavefox.cn/extensions/services/vibe-pay) - [QMuse](http://qmuse.cn/home/skill/k765c3s6dtz8?chinfo=aipay) - [观猹](https://watchapay.com) - [碳基圈](https://ai6666.com/store/) - [Step Studio](https://studio.stepx.com/) #### 收款之外,应用经营也有配套 智能收款套件覆盖网页与 App 的收款需求,提供商品、订单、权益管理及后台,并支持不同接入路径。 ##### 一套收款能力,覆盖网页与 App 无需分别接入两套支付产品。统一使用智能收款套件,各端按指引衔接购买交互与功能交付。 ##### 商品、订单、权益一起管理 三类管理能力默认提供。按业务配置商品,管理订单与用户权益,减少重复搭建。 ##### 配套后台,无需从零开发 商品、订单和权益都有对应管理后台。直接配置使用,把开发时间留给应用的核心功能与服务。 ##### 通过平台接入,也可独立申请 合作平台可统一对接套件,创作者也可为自己的应用申请直接接入。独立开发者模式定向开放。 #### 把开发时间,留给用户愿意付费的体验。 一个套件覆盖网页与 App,经营配套默认提供。 减少重复搭建,专注应用的核心功能与服务。 ##### 接一个产品,网页、App 都可以用。 无需为网页单独接电脑网站支付,再为 App 接 App 支付。统一接入智能收款套件,覆盖两类应用的收款需求。 智能收款套件 → 网页应用 / App 应用 ##### 三类管理及对应后台,都无需自己开发。 每位创作者都无需从零搭建商品、订单、权益管理及后台。套件统一默认提供,按业务需要配置使用。 套件管理后台:商品管理与后台、订单管理与后台、权益管理与后台,默认提供。 #### 你创造什么价值,就选择怎样收费。 从一次生成,到一段时间的使用权。 按服务价值,配置合适的收费方案。 ##### 次数包 · 按次交付 生成、导出、分析等可计次的服务。 创意绘图 | 档位 | 权益 | 价格 | | --- | --- | --- | | 标准包 | 20 次生成 | ¥9.90 | | 进阶包 | 50 次生成 | ¥19.90 | | 畅享包 | 120 次生成 | ¥39.90 | ##### 积分包 · 按量消耗 多种功能按不同积分规则计费。 创作工作台 | 档位 | 权益 | 价格 | | --- | --- | --- | | 体验积分包 | 100 积分 | ¥19.90 | | 标准积分包 | 300 积分 | ¥49.90 | | 高阶积分包 | 800 积分 | ¥99.90 | ##### 时长包 · 限期使用 主动购买固定周期的使用权。 学习搭子 | 档位 | 权益 | 价格 | | --- | --- | --- | | 周享包 | 1 周 | ¥9.90 | | 月享包 | 1 个月 | ¥29.90 | | 季享包 | 3 个月 | ¥79.90 | | 年享包 | 1 年 | ¥249.90 | ##### 买断制 · 一次购买 一次付费,获得长期使用权益。 简历工坊 | 档位 | 权益 | 价格 | | --- | --- | --- | | 专业版 | 长期使用权 | ¥39.90 | 购买页及价格仅为示意,实际档位与价格由创作者配置。 时长包支持 1 周、1 个月、3 个月、1 年等固定周期,不代表自动续费。同一商品采用一种收费模式,可配置多个档位。价格仅为示意,实际档位与价格由创作者配置。 #### 选择适合你的接入方式 为自己的应用收款,或为平台上的创作者提供收费能力。 ##### 应用创作者 ###### 智能收款套件(即刻收) 需要经营配套 减少经营配套开发,专注业务功能。 一个产品覆盖网页与 App,默认提供商品、订单、权益管理及对应后台。可通过合作平台接入,也可申请为自己的应用直接接入。 选择一种接入方式: **通过合作平台接入 · 优先推荐** 在已合作平台创作应用,使用平台提供的收费配套。 1. 平台开启收费,在即刻收配置价格并开通授权 2. 平台生成付费入口或关联网关,及权益校验、放行与核销代码 系统调用链路:创作者应用 → 平台 → 智能收款套件。 应用向平台发起请求,平台统一调用套件接口并返回结果。 资金流向:用户账户 → 创作者收款账户。 资金直接进入创作者收款账户,不经过平台账户,无需平台代收后结算或分账。 选择平台,开始接入: - [灵光 · 申请接入]() - [WeaveFox · 前往接入](https://www.weavefox.cn/extensions/services/vibe-pay) - [QMuse · 前往接入](http://qmuse.cn/home/skill/k765c3s6dtz8?chinfo=aipay) - [观猹 · 前往接入](https://watchapay.com) - [碳基圈 · 前往接入](https://ai6666.com/store/) - [Step Studio · 前往接入](https://studio.stepx.com/) 具体开放范围及操作方式以各平台为准。 **为自己的应用直接接入** 定向开放 当前尚未全面开放,提交留资后将在1~2个工作日内处理;获批加入白名单后可接入。 [查看接入指南](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/nowpay-direct.html) 1. 在即刻收配置商品与价格,获取商品 ID 2. 接入付费入口、购买链接及权益校验、放行与核销 ###### 基础收款能力 已有经营系统,只缺收款 自主建设经营系统,按需接入支付。 最适用于已有完整经营系统(包括商品管理、订单管理、权益管理及对应后台)、只需接通支付的应用创作者。 选择一种接入方式: **方式一 · 通过 Skill 接入** 一句话,开启收款能力接入。 复制给 Agent: ```text 通过 npx -y @alipay/alipay-aipay@latest install 获取安装支付宝 AI 付接入 Skill,加载该技能为当前项目开发支付宝收款能力代码,并引导我完成对应支付产品的开通 ``` 需要你确认或操作时,Agent 会提供明确的操作入口。 **方式二 · 一站式接入** 从官网流程开始,按页面指引完成开通与接入。 1. 按网页或 App 类型选择支付产品 2. 按指引开通、配置并接入支付 [一站式接入]() 选择网页应用或移动应用后,默认进入 Agent 接入工作区,也可切换为页面引导。 已上架 Skill 的合作平台:QMuse、WeaveFox、秒哒、秒悟、扣子编程。 ##### 平台 平台全托管 · 权益托管模式 ###### 平台接一次,创作者配置使用 为每个创作者配好付费应用工具,把收费能力融入创作和发布流程。 [咨询平台接入]() ###### 请求怎么走? 平台统一承接并分发 创作者应用(通过平台调用套件能力) → 平台(承接请求 · 统一分发) → 智能收款套件(支付 · 订单 · 权益能力) 创作者应用先向平台发起请求,再由平台调用智能收款套件并承接结果。平台统一完成套件接口对接,创作者应用与平台衔接。 ###### 接口由谁接? 平台统一接入和维护套件接口;创作者应用对接平台,在平台配置收费。 ###### 资金怎么走? 两种接入模式相同 用户账户 → 直接支付 → 创作者收款账户 用户支付的资金直接进入创作者收款账户。平台权益托管模式下,平台承接接口请求,资金不经过平台账户,平台无需代收后再向创作者结算或分账。 ###### 接入前准备 - 准备平台支付宝账号,签约平台服务协议 - 准备接口调用权限与服务端凭证,确定应用、创作者和权益使用者标识 ###### 1. 商品信息确认与收费配置 创作者先在平台操作界面确认商品名称、Logo 与收费方式,再通过配置链接或二维码进入支付宝“即刻收”小程序,配置收费价格与档位并完成开通授权。返回平台后确认商品关联结果。 平台提供:商品信息确认卡片、配置链接或二维码、配置状态与商品关联展示 ###### 2. 付费入口与购买链接 回到平台侧,为应用生成付费入口展示代码;用户触发入口时,经平台获取并展示商品购买链接。访问应用时即收费的场景,由平台关联收费网关。 平台建设:付费入口生成、购买链接获取与展示、收费网关关联 ###### 3. 购买后权益校验与访问放行 购买完成后,应用经平台查询确认权益,再按结果开放应用访问或应用内付费功能,完成产品与服务交付;展示权益尚未确认等状态。 平台建设:权益校验、访问与功能放行、应用交付衔接;应用对接平台 ###### 4. 使用后权益核销 次数或积分付费功能使用后,应用经平台按业务规则核销对应权益,更新并展示剩余额度。时长与买断按有效权益开放使用。 平台建设:使用核销衔接、额度更新与展示;应用提供实际使用结果 创作者确认收款主体、商品授权与收费规则,并完成应用内容与服务。套件默认提供商品、订单、权益管理及后台。 [查看平台接入文档]() ###### 完善创作者配套 减少收费功能搭建卡点,帮助付费应用成功上线。 ###### 加强平台管控 具备风险应用处置能力,衔接平台治理。 ###### 在哪里判断付费、开放功能? **访问应用时收费** 平台关联网关,由网关通过服务端确认权益并控制应用访问。 **应用内收费** 平台生成付费入口展示代码,应用在具体功能处判断付费并交付服务。 具体查询、核销按实际收费方式接入。页面返回不等于支付成功,需查询确认权益。 ###### 希望保持纯 Coding 平台定位? 我们也可提供接入 Skill,上架到平台,实现轻量级合作。创作者通过自然语言描述需求,由 Skill 引导代码生成与商品配置。请通过下方留资入口,说明平台定位、创作场景与合作诉求,与团队确认接入方案。 [留资咨询 Skill 合作]() #### 接入之前,先把问题说清。 ##### 智能收款套件与传统支付的核心区别? 传统支付主要解决收款;智能收款套件在收款之外,默认提供商品、订单、权益管理及对应后台。每位创作者无需再从零搭建这套配套,应用仍需完成核心功能与服务交付。 ##### 接入套件后,还要分别接网页支付、App 支付吗? 接入一个智能收款套件,网页和 App 都可以使用,无需分别为网页接电脑网站支付、为 App 接 App 支付。各端仍需按指引衔接对应的购买交互与功能交付。 ##### 套件会自动控制我的应用功能吗? 套件提供商业权益及额度结果,平台网关或应用据此开放功能、按规则核销并交付服务。套件不直接接管应用的业务逻辑。 ##### 独立创作者现在能接吗? 独立开发者模式已定向开放,可直接向官方团队申请,无需依赖合作平台。申请时说明应用、收费场景和联系方式,资格确认后按指引开通并集成。 ##### 费用和结算怎么确认? 产品费用与结算以开通协议及适用产品说明为准,可在接入前与官方团队确认。 #### 把好应用,变成好生意。 从一个应用、一种收费方式,跑通第一条变现路径。 [平台合作接入]() · [独立创作者申请]() --- ### Vibe Pay · AI应用收款 目录路径:Vibe Pay · AI应用收款 来源:https://aipay.alipay.com/docs/vibe-pay.md > 灵感输入,价值输出 #### 一、产品概述 Vibe Pay 是面向 AI 创作者的应用商业化收款方案,帮助创作者将由 AI 创建或驱动的网页应用、移动应用快速变成可持续经营的产品。 Vibe Pay 复用成熟的支付能力,同时提供更适合 AI 创作方式的接入路径。无论是个人创作者,还是有技术团队的应用开发者,都可以根据自身对定制自由度和上线效率的需求,选择合适的产品模式。 #### 二、适用对象 Vibe Pay 适用于以下类型的用户和应用: - 使用 AI 创建网页应用、移动应用的个人创作者; - 通过自然语言编程或 Vibe Coding 开发应用的创作者; - 需要为 AI 功能、数字内容或应用权益收费的开发者; - 希望快速验证商业模式、减少支付配套开发投入的应用团队; - 需要高度定制支付流程和商业化体验的技术团队。 #### 三、两种模式 Vibe Pay 提供两种模式,分别对应“高度定制”和“快速上线”两类诉求。 ##### 3.1 基础收款能力 **定位**:提供支付、订单查询、退款等原子能力,由创作者自行设计和建设应用的商业化配套。 **适合谁**: - 需要高度定制支付体验的创作者或技术团队; - 希望自行设计付款入口、业务流程和应用界面的开发者; - 愿意自行建设订单、权益等应用商业化配套的团队。 **接入方式**: 通过 Skill 一句话接入。创作者将接入命令复制给 Agent,由 Agent 结合应用上下文和应用形态,协助匹配网页或移动应用的接入路径。 **能力特点**: - 支持网页应用与移动应用; - 支持支付、订单查询、退款等核心原子能力; - 支持创作者自行设计付款时机、支付页面和业务流程; - 支持创作者自行建设订单和权益管理等配套能力。 > 基础收款能力的具体产品能力、接口范围、接入要求和技术流程,详见后续产品文档:[AI网页应用收款](https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/ai-web-app-payment-integration-guide.html)、[AI移动应用收款](https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/app-pay-integration-guide-new.html) 复制给Agent,开始接入 ```ts npx -y @alipay/alipay-aipay@latest install ``` ##### 3.2 智能收款套件 **定位**:将支付及相关商业化配套组合提供,帮助创作者更快上线完整的应用商业闭环。 **适合谁**: - 希望快速验证 AI 应用商业模式的创作者; - 不希望重复建设订单和权益管理等交易配套的创作者; - 希望将开发精力集中在应用功能和用户体验上的团队; - 通过合作平台创作或入驻应用的创作者。 **接入方式**: 当前暂以合作平台为入口。创作者通过已合作平台接入智能收款套件,由合作平台提供相应的商业化能力。 创作者独立接入能力正在准备中,敬请期待。 > 智能收款套件的具体产品能力、接口范围、接入要求和技术流程,详见产品文档:[即刻收](https://aipay.alipay.com/docs/vibe-pay/nowpay/nowpay-intro.html) #### 四、两种模式如何选择 | 你的诉求 | 建议模式 | | --- | --- | | 想自己掌控支付页面、业务流程和商业化体验 | 基础收款能力 | | 有技术团队,愿意自行建设订单和权益等配套 | 基础收款能力 | | 希望通过 Skill 快速接入网页或移动应用 | 基础收款能力 | | 希望快速验证应用是否适合收费 | 智能收款套件 | | 不想重复建设订单与权益管理 | 智能收款套件 | | 已在合作平台创作或入驻应用 | 智能收款套件 | --- ### 产品接入指南 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI网页应用收款 > 产品接入指南 来源:https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/ai-web-app-payment-integration-guide.md 网页应用付款产品接入指南 #### 适用场景 适用于在商家网页应用中使用支付宝支付功能,支持个人收款场景。 ::::aipay-tabs{defaultActiveKey="扫码支付"} :::aipay-tab{key="扫码支付" title="扫码支付"} ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/223145/1783352643566-190cb39a-a4a7-4c28-b309-82890873cd41.png) ::: :::aipay-tab{key="登录支付" title="登录支付"} ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/223145/1783352754552-990666e9-d5ce-4e47-9feb-4a17dc4591ac.png) ::: :::: #### Agent快速集成(推荐) ```markdown 通过 npx -y @alipay/alipay-aipay@latest install 安装支付宝 AI 付 Skill,加载 alipay-aipay 技能为我的项目集成网站支付,完成沙箱测试,并完成签约入驻 ``` #### 手动集成 ##### 系统流程 ```mermaid sequenceDiagram participant 用户 participant 商家 participant 支付宝 用户->>商家: 1 下单 商家->>支付宝: 1.1 调用alipay.trade.page.pay发起支付请求 用户->>用户: 2 用户输入用户名、支付密码 用户->>支付宝: 3 登录 用户->>用户: 4 选择支付渠道、输入支付密码 用户->>支付宝: 5 确认支付 支付宝->>商家: 6 get请求returnUrl,返回同步返回参数 Note over 支付宝,商家: 支付是否成功以异步通知为准 支付宝->>商家: 7 post请求notifyUrl,返回异步返回参数 Note over 支付宝,商家: 支付是否成功以查询接口返回为准 商家->>支付宝: 8 调用alipay.trade.query查看交易状态 支付宝-->>商家: 8.1 返回交易信息 ``` 调用流程如下: 1. 商家系统调用 [alipay.trade.page.pay]()(统一收单下单并支付页面接口)向支付宝发起支付请求,支付宝对商家请求参数进行校验,而后重新定向至用户登录页面。 2. 用户确认支付后,支付宝通过 get 请求 returnUrl(商户入参传入),返回同步返回参数。 3. 交易成功后,支付宝通过 post 请求 notifyUrl(商户入参传入),返回异步通知参数。 4. 若由于网络等原因,导致商家系统没有收到异步通知,商家可自行调用 [alipay.trade.query]()(统一收单交易查询接口)查询交易以及支付信息(商家也可以直接调用该查询接口,不需要依赖异步通知)。 **注意**: + 由于同步返回的不可靠性,支付结果必须以异步通知或查询接口返回为准,不能依赖同步跳转。 + 商家系统接收到异步通知以后,必须通过验签(验证通知中的 sign 参数)来确保支付通知是由支付宝发送的。详细验签规则可查看 [异步通知验签]()。 + 接收到异步通知并验签通过后,请务必核对通知中的 app_id、out_trade_no、total_amount 等参数值是否与请求中的一致,并根据 trade_status 进行后续业务处理。 + 在支付宝端,partnerId 与 out_trade_no 唯一对应一笔单据,商家端保证不同次支付 out_trade_no 不可重复;若重复,支付宝会关联到原单据,基本信息一致的情况下会以原单据为准进行支付。 ##### 调用示例 开放平台提供了支持主流开发语言的 SDK 接入的方式。对于页面跳转类 API,SDK 不会也无法像系统调用类 API 一样自动请求支付宝并获得结果,而是在接受 request 请求对象后,为开发者生成前台页面请求需要的完整 form 表单的 html(包含自动提交脚本),商家直接将这个表单的 String 输出到 http response 中即可。 **注意:** + 付款页面生成的付款码每 **2 分钟** 会自动刷新一次。 ###### 示例代码 以 Java 语言为例,调用 [alipay.trade.page.pay]()(统一收单下单并支付页面接口) 的示例代码如下。 ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradePagePayModel; import com.alipay.api.domain.ExtUserInfo; import com.alipay.api.domain.InvoiceKeyInfo; import com.alipay.api.response.AlipayTradePagePayResponse; import com.alipay.api.domain.InvoiceInfo; import com.alipay.api.request.AlipayTradePagePayRequest; import com.alipay.api.domain.ExtendParams; import com.alipay.api.domain.GoodsDetail; import com.alipay.api.domain.SubMerchant; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradePagePay { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePagePayRequest request = new AlipayTradePagePayRequest(); AlipayTradePagePayModel model = new AlipayTradePagePayModel(); // 设置商户订单号 model.setOutTradeNo("20150320010101001"); // 设置订单总金额 model.setTotalAmount("88.88"); // 设置订单标题 model.setSubject("Iphone6 16G"); // 设置产品码 model.setProductCode("FAST_INSTANT_TRADE_PAY"); // 设置PC扫码支付的方式 model.setQrPayMode("1"); // 设置商户自定义二维码宽度 model.setQrcodeWidth(100L); // 设置订单包含的商品列表信息 List goodsDetail = new ArrayList(); GoodsDetail goodsDetail0 = new GoodsDetail(); goodsDetail0.setGoodsName("ipad"); goodsDetail0.setAlipayGoodsId("20010001"); goodsDetail0.setQuantity(1L); goodsDetail0.setPrice("2000"); goodsDetail0.setGoodsId("apple-01"); goodsDetail0.setGoodsCategory("34543238"); goodsDetail0.setCategoriesTree("124868003|126232002|126252004"); goodsDetail0.setShowUrl("http://www.alipay.com/xxx.jpg"); goodsDetail.add(goodsDetail0); model.setGoodsDetail(goodsDetail); // 设置订单绝对超时时间 model.setTimeExpire("2016-12-31 10:05:01"); // 设置二级商户信息 SubMerchant subMerchant = new SubMerchant(); subMerchant.setMerchantId("2088000603999128"); subMerchant.setMerchantType("alipay"); model.setSubMerchant(subMerchant); // 设置业务扩展参数 ExtendParams extendParams = new ExtendParams(); extendParams.setSysServiceProviderId("2088511833207846"); extendParams.setHbFqSellerPercent("100"); extendParams.setHbFqNum("3"); extendParams.setIndustryRefluxInfo("{\"scene_code\":\"metro_tradeorder\",\"channel\":\"xxxx\",\"scene_data\":{\"asset_name\":\"ALIPAY\"}}"); extendParams.setRoyaltyFreeze("true"); extendParams.setCardType("S0JP0000"); model.setExtendParams(extendParams); // 设置商户传入业务信息 model.setBusinessParams("{\"mc_create_trade_ip\":\"127.0.0.1\"}"); // 设置优惠参数 model.setPromoParams("{\"storeIdType\":\"1\"}"); // 设置请求后页面的集成方式 model.setIntegrationType("PCWEB"); // 设置请求来源地址 model.setRequestFromUrl("https://"); // 设置商户门店编号 model.setStoreId("NJ_001"); // 设置商户的原始订单号 model.setMerchantOrderNo("20161008001"); // 设置外部指定买家 ExtUserInfo extUserInfo = new ExtUserInfo(); extUserInfo.setCertType("IDENTITY_CARD"); extUserInfo.setCertNo("362334768769238881"); extUserInfo.setMobile("16587658765"); extUserInfo.setName("李明"); extUserInfo.setMinAge("18"); extUserInfo.setNeedCheckInfo("F"); extUserInfo.setIdentityHash("27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc"); model.setExtUserInfo(extUserInfo); // 设置开票信息 InvoiceInfo invoiceInfo = new InvoiceInfo(); InvoiceKeyInfo keyInfo = new InvoiceKeyInfo(); keyInfo.setTaxNum("1464888883494"); keyInfo.setIsSupportInvoice(true); keyInfo.setInvoiceMerchantName("ABC|003"); invoiceInfo.setKeyInfo(keyInfo); invoiceInfo.setDetails("[{\"code\":\"100294400\",\"name\":\"服饰\",\"num\":\"2\",\"sumPrice\":\"200.00\",\"taxRate\":\"6%\"}]"); model.setInvoiceInfo(invoiceInfo); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePagePayResponse response = alipayClient.pageExecute(request, "POST"); // 如果需要返回GET请求,请使用 // AlipayTradePagePayResponse response = alipayClient.pageExecute(request, "GET"); String pageRedirectionData = response.getBody(); System.out.println(pageRedirectionData); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ###### 重要入参说明 **注意**:请严格按照接口文档中的参数入参,传入非接口文档中的参数是无效的,并且可能会导致请求被拦截或其它异常。 | **参数名称** | **参数说明** | | --- | --- | | subject | **必填**,商品的标题/交易标题/订单标题/订单关键字等。 不可使用特殊字符,如 /,=,& 等。 | | product_code | **必填**,销售产品码,与支付宝签约的产品码名称。目前电脑支付场景下仅支持 `FAST_INSTANT_TRADE_PAY` | | total_amount | **必填**,订单总金额,单位为元,精确到小数点后两位,取值范围为 [0.01,100000000]。金额不能为0。 | 对异步返回结果进行验签的 Java 示例代码如下: ```java Map paramsMap = ... //将异步通知中收到的所有参数都存放到 map 中 boolean signVerified = AlipaySignature.rsaCheckV1(paramsMap, ALIPAY_PUBLIC_KEY, CHARSET, SIGN_TYPE) //调用SDK验证签名 if (signVerified){ // TODO 验签成功后,按照支付结果异步通知中的描述,对支付结果中的业务内容进行二次校验,校验成功后在response中返回success并继续商家自身业务处理,校验失败返回failure } else { // TODO 验签失败则记录异常日志,并在response中返回failure. } ``` 以 Java 语言为例,调用 [alipay.trade.query]()(统一收单交易查询接口)的示例代码如下: ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.response.AlipayTradeQueryResponse; import com.alipay.api.request.AlipayTradeQueryRequest; import com.alipay.api.domain.AlipayTradeQueryModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680 073956707"); // 设置银行间联模式下有用 model.setOrgPid("2088101117952222"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("trade_settle_info"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` #### 退款流程 当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,支付宝将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退回到买家账号上。 ##### 系统流程 商家可调用 [alipay.trade.refund]()(统一收单交易退款接口)进行退款,支付宝同步返回退款参数。调用时序图如下: ```mermaid sequenceDiagram actor 用户 participant 商户系统 participant 支付宝 用户->>商户系统: 用户或商户想退款 商户系统->>支付宝: 1.1: 调用alipay.trade.refund发起退款请求 支付宝-->>商户系统: 1.2: 返回退款结果 商户系统->>支付宝: 2.1: 调用alipay.trade.fastpay.refund.query退款查询 支付宝-->>商户系统: 2.2: 返回退款查询结果 ``` + 若退款接口由于网络等原因返回异常,商家可调用退款查询接口 [alipay.trade.fastpay.refund.query]()(统一收单交易退款查询接口)查询指定交易的退款信息。 + 支付宝退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。 ##### 退款说明 + **退款周期:** 12 个月,即交易发生后 12 个月内可发起退款,超过 12 个月则不可发起退款。 + **退款方式:** 资金原路返回用户账号。 + **退款退费:** 退款时手续费不退回。 + 一笔退款失败后重新提交,要采用原来的退款单号。 + 总退款金额不能超过用户实际支付金额。 + 退款信息以退款接口同步返回或者 [alipay.trade.fastpay.refund.query]()(统一收单交易退款查询接口)为准。 ##### 调用示例 开放平台提供了支持主流开发语言的 SDK 接入的方式,以 Java 语言为例,调用 [alipay.trade.refund]()(统一收单交易退款接口)的示例代码如下: ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeRefundModel; import com.alipay.api.request.AlipayTradeRefundRequest; import com.alipay.api.response.AlipayTradeRefundResponse; import com.alipay.api.domain.RefundGoodsDetail; import com.alipay.api.domain.OpenApiRoyaltyDetailInfoPojo; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeRefund { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); AlipayTradeRefundModel model = new AlipayTradeRefundModel(); // 设置商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680073956707"); // 设置退款金额 model.setRefundAmount("200.12"); // 设置退款原因说明 model.setRefundReason("正常退款"); // 设置退款请求号 model.setOutRequestNo("HZ01RF001"); // 设置退款包含的商品列表信息 List refundGoodsDetail = new ArrayList(); RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail(); refundGoodsDetail0.setOutSkuId("outSku_01"); refundGoodsDetail0.setOutItemId("outItem_01"); refundGoodsDetail0.setGoodsId("apple-01"); refundGoodsDetail0.setRefundAmount("19.50"); List outCertificateNoList = new ArrayList(); outCertificateNoList.add("202407013232143241231243243423"); refundGoodsDetail0.setOutCertificateNoList(outCertificateNoList); refundGoodsDetail.add(refundGoodsDetail0); model.setRefundGoodsDetail(refundGoodsDetail); // 设置退分账明细信息 List refundRoyaltyParameters = new ArrayList(); OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo(); refundRoyaltyParameters0.setAmount("0.1"); refundRoyaltyParameters0.setTransIn("2088101126708402"); refundRoyaltyParameters0.setRoyaltyType("transfer"); refundRoyaltyParameters0.setTransOut("2088101126765726"); refundRoyaltyParameters0.setTransOutType("userId"); refundRoyaltyParameters0.setRoyaltyScene("达人佣金"); refundRoyaltyParameters0.setTransInType("userId"); refundRoyaltyParameters0.setTransInName("张三"); refundRoyaltyParameters0.setDesc("分账给2088101126708402"); refundRoyaltyParameters.add(refundRoyaltyParameters0); model.setRefundRoyaltyParameters(refundRoyaltyParameters); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("refund_detail_item_list"); model.setQueryOptions(queryOptions); // 设置针对账期交易 model.setRelatedSettleConfirmNo("2024041122001495000530302869"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeRefundResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` 调用 [alipay.trade.fastpay.refund.query]()(统一收单交易退款查询接口)Java 示例代码如下: ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeFastpayRefundQueryModel; import com.alipay.api.response.AlipayTradeFastpayRefundQueryResponse; import com.alipay.api.request.AlipayTradeFastpayRefundQueryRequest; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeFastpayRefundQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest(); AlipayTradeFastpayRefundQueryModel model = new AlipayTradeFastpayRefundQueryModel(); // 设置支付宝交易号 model.setTradeNo("2021081722001419121412730660"); // 设置商户订单号 model.setOutTradeNo("2014112611001004680073956707"); // 设置退款请求号 model.setOutRequestNo("HZ01RF001"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("refund_detail_item_list"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeFastpayRefundQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` #### 关闭交易 通常交易关闭是通过 alipay.trade.page.pay 中的超时时间来控制,支付宝也提供给商家 [alipay.trade.close]()(统一收单交易关闭接口)。若用户一直未支付,商家可以调用该接口关闭指定交易;成功关闭交易后该交易不可支付。 ##### 系统流程 交易关闭接口的调用时序图 [alipay.trade.close]()(统一收单交易关闭接口)如下图所示: ```mermaid sequenceDiagram participant 商户系统 participant 支付宝 商户系统->>支付宝: 1. alipay.trade.close 支付宝-->>商户系统: 2. 返回 ``` ##### 调用示例 开放平台提供了支持主流开发语言的 SDK 接入的方式,以 Java 语言为例,调用 [alipay.trade.close]()(统一收单交易关闭接口)的示例代码如下: ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeCloseRequest; import com.alipay.api.domain.AlipayTradeCloseModel; import com.alipay.api.response.AlipayTradeCloseResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeClose { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCloseRequest request = new AlipayTradeCloseRequest(); AlipayTradeCloseModel model = new AlipayTradeCloseModel(); // 设置该交易在支付宝系统中的交易流水号 model.setTradeNo("2013112611001004680073956707"); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("HZ0120131127001"); // 设置商家操作员编号 id model.setOperatorId("YX01"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCloseResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` #### 对账流程 为方便商家快速查账,开放平台支持商家通过 [alipay.data.dataservice.bill.downloadurl.query]()(查询对账单下载地址接口)获取商家离线账单下载地址。 ##### 调用流程 调用该接口的时序图如下: ```mermaid sequenceDiagram participant 商户系统 participant 支付宝 商户系统->>支付宝: 1. alipay.data.dataservice.bill.downloadurl.query 支付宝-->>商户系统: 2. 返回离线账单下载地址 ``` ##### 调用示例 开放平台提供了支持主流开发语言的 SDK 接入的方式,以 Java 语言为例,调用 [alipay.data.dataservice.bill.downloadurl.query]()(查询对账单下载地址接口)的示例代码如下: ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayDataDataserviceBillDownloadurlQueryRequest; import com.alipay.api.response.AlipayDataDataserviceBillDownloadurlQueryResponse; import com.alipay.api.domain.AlipayDataDataserviceBillDownloadurlQueryModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayDataDataserviceBillDownloadurlQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayDataDataserviceBillDownloadurlQueryRequest request = new AlipayDataDataserviceBillDownloadurlQueryRequest(); AlipayDataDataserviceBillDownloadurlQueryModel model = new AlipayDataDataserviceBillDownloadurlQueryModel(); // 设置账单类型 model.setBillType("trade"); // 设置账单时间 model.setBillDate("2025-05-01"); // 设置二级商户smid model.setSmid("2088123412341234"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayDataDataserviceBillDownloadurlQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` 开发者在得到接口返回的账单下载地址(bill_download_url)后还可以下载账单文件,Java 示例代码如下: ```java //将接口返回的对账单下载地址传入urlStr String urlStr = "下载地址" ; //指定希望保存的文件路径 String filePath = "/Users/fund_bill_20210205.csv" ; URL url = null ; HttpURLConnection httpUrlConnection = null ; InputStream fis = null ; FileOutputStream fos = null ; try { url = new URL(urlStr); httpUrlConnection = (HttpURLConnection) url.openConnection(); httpUrlConnection.setConnectTimeout( 5 * 1000 ); httpUrlConnection.setDoInput( true ); httpUrlConnection.setDoOutput( true ); httpUrlConnection.setUseCaches( false ); httpUrlConnection.setRequestMethod( "GET" ); httpUrlConnection.setRequestProperty( "Charsert" , "UTF-8" ); httpUrlConnection.connect(); fis = httpUrlConnection.getInputStream(); byte [] temp = new byte [ 1024 ]; int b; fos = new FileOutputStream( new File(filePath)); while ((b = fis.read(temp)) != - 1 ) { fos.write(temp, 0 , b); fos.flush(); } } catch (MalformedURLException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } finally { try { if (fis!= null ) fis.close(); if (fos!= null ) fos.close(); if (httpUrlConnection!= null ) httpUrlConnection.disconnect(); } catch (IOException e) { e.printStackTrace(); } ``` --- ### 统一收单下单并支付页面接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI网页应用收款 > API列表 > 统一收单下单并支付页面接口 来源:https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-page-pay.md 网页应用收款场景,用于生成用户访问支付宝的跳转链接 #### 接口说明 接口名称:`alipay.trade.page.pay` 该接口是页面跳转接口,用于生成用户访问支付宝的跳转链接。请在服务端执行支付宝SDK中pageExecute方法,读取响应中的body()结果。该结果用于跳转到支付宝页面,返回到用户浏览器渲染或重定向跳转到支付宝页面。 #### 公共请求参数 | **参数** | **类型** | **是否必选** | **最大长度** | **描述** | **示例值** | | --- | --- | --- | --- | --- | --- | | app_id | String | 必选 | 32 | 支付宝分配给开发者的应用ID | 2014072300007148 | | method | String | 必选 | 128 | 接口名称 | alipay.trade.page.pay | | format | String | 可选 | 40 | 仅支持JSON | JSON | | return_url | String | 可选 | 256 | HTTP/HTTPS开头字符串 | [https://m.alipay.com/Gk8NF23](https://m.alipay.com/Gk8NF23) | | charset | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | utf-8 | | sign_type | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | RSA2 | | sign | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | timestamp | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | 2014-07-24 03:07:50 | | version | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | 1.0 | | notify_url | String | 可选 | 256 | 支付宝服务器主动通知商户服务器里指定的页面http/https路径。 | [http://api.test.alipay.net/atinterface/receive_notify.htm](http://api.test.alipay.net/atinterface/receive_notify.htm) | | app_auth_token | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | | | biz_content | String | 必选 | | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `out_trade_no` | String | 必选 | 64 | 商户订单号。由商家自定义,64 个字符以内,仅支持字母、数字、下划线,且需保证在商户端不重复。 | `20150320010101001` | | `total_amount` | Price | 必选 | 11 | 订单总金额。单位为元,精确到小数点后两位,取值范围:`[0.01,100000000]`。 | `88.88` | | `subject` | String | 必选 | 256 | 订单标题。256 个字符以内,不可使用特殊字符,如 `/`、`=`、`&` 等。 | `Iphone6 16G` | | `product_code` | String | 必选 | 64 | 产品码。商家和支付宝签约的产品码。枚举值:[`FAST_INSTANT_TRADE_PAY`](https://opensupport.alipay.com/support/codelab/detail/766/772):新快捷即时到账产品。目前仅支持 `FAST_INSTANT_TRADE_PAY`。 | `FAST_INSTANT_TRADE_PAY` | | `goods_detail` | GoodsDetail[] | 可选 | - | 订单包含的商品列表信息,JSON 格式。 | - | | `time_expire` | String | 可选 | 32 | 订单绝对超时时间。格式为 `yyyy-MM-dd HH:mm:ss`。超时时间范围:`1m~15d`。 | `2016-12-31 10:05:01` | | `extend_params` | ExtendParams | 可选 | - | 业务扩展参数。 | - | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradePagePayModel; import com.alipay.api.domain.ExtUserInfo; import com.alipay.api.domain.InvoiceKeyInfo; import com.alipay.api.response.AlipayTradePagePayResponse; import com.alipay.api.domain.InvoiceInfo; import com.alipay.api.request.AlipayTradePagePayRequest; import com.alipay.api.domain.ExtendParams; import com.alipay.api.domain.GoodsDetail; import com.alipay.api.domain.SubMerchant; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradePagePay { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePagePayRequest request = new AlipayTradePagePayRequest(); AlipayTradePagePayModel model = new AlipayTradePagePayModel(); // 设置商户订单号 model.setOutTradeNo("20150320010101001"); // 设置订单总金额 model.setTotalAmount("88.88"); // 设置订单标题 model.setSubject("Iphone6 16G"); // 设置产品码 model.setProductCode("FAST_INSTANT_TRADE_PAY"); // 设置PC扫码支付的方式 model.setQrPayMode("1"); // 设置商户自定义二维码宽度 model.setQrcodeWidth(100L); // 设置订单包含的商品列表信息 List goodsDetail = new ArrayList(); GoodsDetail goodsDetail0 = new GoodsDetail(); goodsDetail0.setGoodsName("ipad"); goodsDetail0.setAlipayGoodsId("20010001"); goodsDetail0.setQuantity(1L); goodsDetail0.setPrice("2000"); goodsDetail0.setGoodsId("apple-01"); goodsDetail0.setGoodsCategory("34543238"); goodsDetail0.setCategoriesTree("124868003|126232002|126252004"); goodsDetail0.setShowUrl("http://www.alipay.com/xxx.jpg"); goodsDetail.add(goodsDetail0); model.setGoodsDetail(goodsDetail); // 设置订单绝对超时时间 model.setTimeExpire("2016-12-31 10:05:01"); // 设置二级商户信息 SubMerchant subMerchant = new SubMerchant(); subMerchant.setMerchantId("2088000603999128"); subMerchant.setMerchantType("alipay"); model.setSubMerchant(subMerchant); // 设置业务扩展参数 ExtendParams extendParams = new ExtendParams(); extendParams.setSysServiceProviderId("2088511833207846"); extendParams.setHbFqSellerPercent("100"); extendParams.setHbFqNum("3"); extendParams.setIndustryRefluxInfo("{\"scene_code\":\"metro_tradeorder\",\"channel\":\"xxxx\",\"scene_data\":{\"asset_name\":\"ALIPAY\"}}"); extendParams.setRoyaltyFreeze("true"); extendParams.setCardType("S0JP0000"); model.setExtendParams(extendParams); // 设置商户传入业务信息 model.setBusinessParams("{\"mc_create_trade_ip\":\"127.0.0.1\"}"); // 设置优惠参数 model.setPromoParams("{\"storeIdType\":\"1\"}"); // 设置请求后页面的集成方式 model.setIntegrationType("PCWEB"); // 设置请求来源地址 model.setRequestFromUrl("https://"); // 设置商户门店编号 model.setStoreId("NJ_001"); // 设置商户的原始订单号 model.setMerchantOrderNo("20161008001"); // 设置外部指定买家 ExtUserInfo extUserInfo = new ExtUserInfo(); extUserInfo.setCertType("IDENTITY_CARD"); extUserInfo.setCertNo("362334768769238881"); extUserInfo.setMobile("16587658765"); extUserInfo.setName("李明"); extUserInfo.setMinAge("18"); extUserInfo.setNeedCheckInfo("F"); extUserInfo.setIdentityHash("27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc"); model.setExtUserInfo(extUserInfo); // 设置开票信息 InvoiceInfo invoiceInfo = new InvoiceInfo(); InvoiceKeyInfo keyInfo = new InvoiceKeyInfo(); keyInfo.setTaxNum("1464888883494"); keyInfo.setIsSupportInvoice(true); keyInfo.setInvoiceMerchantName("ABC|003"); invoiceInfo.setKeyInfo(keyInfo); invoiceInfo.setDetails("[{\"code\":\"100294400\",\"name\":\"服饰\",\"num\":\"2\",\"sumPrice\":\"200.00\",\"taxRate\":\"6%\"}]"); model.setInvoiceInfo(invoiceInfo); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePagePayResponse response = alipayClient.pageExecute(request, "POST"); // 如果需要返回GET请求,请使用 // AlipayTradePagePayResponse response = alipayClient.pageExecute(request, "GET"); String pageRedirectionData = response.getBody(); System.out.println(pageRedirectionData); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradePagePay { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePagePayRequest request = new AlipayTradePagePayRequest(); AlipayTradePagePayModel model = new AlipayTradePagePayModel(); // 设置商户订单号 model.OutTradeNo = "20150320010101001"; // 设置订单总金额 model.TotalAmount = "88.88"; // 设置订单标题 model.Subject = "Iphone6 16G"; // 设置产品码 model.ProductCode = "FAST_INSTANT_TRADE_PAY"; // 设置PC扫码支付的方式 model.QrPayMode = "1"; // 设置商户自定义二维码宽度 model.QrcodeWidth = 100; // 设置订单包含的商品列表信息 List goodsDetail = new List(); GoodsDetail goodsDetail0 = new GoodsDetail(); goodsDetail0.GoodsName = "ipad"; goodsDetail0.AlipayGoodsId = "20010001"; goodsDetail0.Quantity = 1; goodsDetail0.Price = "2000"; goodsDetail0.GoodsId = "apple-01"; goodsDetail0.GoodsCategory = "34543238"; goodsDetail0.CategoriesTree = "124868003|126232002|126252004"; goodsDetail0.ShowUrl = "http://www.alipay.com/xxx.jpg"; goodsDetail.Add(goodsDetail0); model.GoodsDetail = goodsDetail; // 设置订单绝对超时时间 model.TimeExpire = "2016-12-31 10:05:01"; // 设置二级商户信息 SubMerchant subMerchant = new SubMerchant(); subMerchant.MerchantId = "2088000603999128"; subMerchant.MerchantType = "alipay"; model.SubMerchant = subMerchant; // 设置业务扩展参数 ExtendParams extendParams = new ExtendParams(); extendParams.SysServiceProviderId = "2088511833207846"; extendParams.HbFqSellerPercent = "100"; extendParams.HbFqNum = "3"; extendParams.IndustryRefluxInfo = "{\"scene_code\":\"metro_tradeorder\",\"channel\":\"xxxx\",\"scene_data\":{\"asset_name\":\"ALIPAY\"}}"; extendParams.RoyaltyFreeze = "true"; extendParams.CardType = "S0JP0000"; model.ExtendParams = extendParams; // 设置商户传入业务信息 model.BusinessParams = "{\"mc_create_trade_ip\":\"127.0.0.1\"}"; // 设置优惠参数 model.PromoParams = "{\"storeIdType\":\"1\"}"; // 设置请求后页面的集成方式 model.IntegrationType = "PCWEB"; // 设置请求来源地址 model.RequestFromUrl = "https://"; // 设置商户门店编号 model.StoreId = "NJ_001"; // 设置商户的原始订单号 model.MerchantOrderNo = "20161008001"; // 设置外部指定买家 ExtUserInfo extUserInfo = new ExtUserInfo(); extUserInfo.CertType = "IDENTITY_CARD"; extUserInfo.CertNo = "362334768769238881"; extUserInfo.Mobile = "16587658765"; extUserInfo.Name = "李明"; extUserInfo.MinAge = "18"; extUserInfo.NeedCheckInfo = "F"; extUserInfo.IdentityHash = "27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc"; model.ExtUserInfo = extUserInfo; // 设置开票信息 InvoiceInfo invoiceInfo = new InvoiceInfo(); InvoiceKeyInfo keyInfo = new InvoiceKeyInfo(); keyInfo.TaxNum = "1464888883494"; keyInfo.IsSupportInvoice = true; keyInfo.InvoiceMerchantName = "ABC|003"; invoiceInfo.KeyInfo = keyInfo; invoiceInfo.Details = "[{\"code\":\"100294400\",\"name\":\"服饰\",\"num\":\"2\",\"sumPrice\":\"200.00\",\"taxRate\":\"6%\"}]"; model.InvoiceInfo = invoiceInfo; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePagePayResponse response = alipayClient.pageExecute(request, null, "POST"); // 如果需要返回GET请求,请使用 // AlipayTradePagePayResponse response = alipayClient.pageExecute(request, null, "GET"); string pageRedirectionData = response.Body; Console.WriteLine(pageRedirectionData); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $pageRedirectionData = $alipayClient->pageExecute($request, "POST", "<-- 请填写应用授权令牌 -->"); // 如果需要返回GET请求,请使用 // $pageRedirectionData = $alipayClient->pageExecute($request, "GET"); echo $pageRedirectionData; function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.pageExec("alipay.trade.page.pay", { bizContent: { out_trade_no: "20150320010101001", total_amount: "88.88", subject: "Iphone6+16G", product_code: "FAST_INSTANT_TRADE_PAY", qr_pay_mode: "1", qrcode_width: 100, goods_detail: [ { goods_name: "ipad", alipay_goods_id: "20010001", quantity: 1, price: "2000", goods_id: "apple-01", goods_category: "34543238", categories_tree: "124868003|126232002|126252004", show_url: "http://www.alipay.com/xxx.jpg", }, ], time_expire: "2016-12-31+10:05:01", sub_merchant: { merchant_id: "2088000603999128", merchant_type: "alipay", }, extend_params: { sys_service_provider_id: "2088511833207846", hb_fq_seller_percent: "100", hb_fq_num: "3", industry_reflux_info: '{\\"scene_code\\":\\"metro_tradeorder\\",\\"channel\\":\\"xxxx\\",\\"scene_data\\":{\\"asset_name\\":\\"ALIPAY\\"}}', royalty_freeze: "true", card_type: "S0JP0000", }, business_params: '{"mc_create_trade_ip":"127.0.0.1"}', promo_params: '{"storeIdType":"1"}', integration_type: "PCWEB", request_from_url: "https://", store_id: "NJ_001", merchant_order_no: "20161008001", ext_user_info: { cert_type: "IDENTITY_CARD", cert_no: "362334768769238881", mobile: "16587658765", name: "李明", min_age: "18", need_check_info: "F", identity_hash: "27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc", }, invoice_info: { key_info: { tax_num: "1464888883494", is_support_invoice: true, invoice_merchant_name: "ABC|003", }, details: '[{"code":"100294400","name":"服饰","num":"2","sumPrice":"200.00","taxRate":"6%"}]', }, }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | --- | --- | --- | --- | --- | | `code` | String | 必选 | 网关返回码,详见[文档](https://opendoc.alipay.com/common/02km9f) | `40004` | | `msg` | String | 必选 | 网关返回码描述,详见[文档](https://opendoc.alipay.com/common/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | 业务返回码,参见具体的 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | 签名,详见[文档](https://opendoc.alipay.com/common/02kf5q) | `DZXh8eeTuAHoYE...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `pageRedirectionData` | String | 必选 | 16384 | 用于跳转支付宝页面的信息。POST 和 GET 方法生成内容不同:使用 POST 方法执行时,结果为 HTML form 表单,在浏览器渲染即可;使用 GET 方法执行时,会得到支付宝 URL,需要打开或重定向到该 URL。建议使用 POST 方式。具体使用方法请参考[接入指南](https://opendocs.alipay.com/open/270/105899?pathHash=d57664bf)。 | 请参考响应示例 | #### 响应示例 ##### 正常示例 ```html
``` #### 公共错误码 [前往查看](https://opendoc.alipay.com/common/02km9f) #### 业务错误码 | **错误码** | **错误描述** | **解决方案** | | --- | --- | --- | | ACQ.ACCESS_FORBIDDEN | 无权限使用接口 | 未签约条码支付或者合同已到期 | | ACQ.BUYER_BALANCE_NOT_ENOUGH | 买家余额不足 | 买家绑定新的银行卡或者支付宝余额有钱后再发起支付 | | ACQ.BUYER_BANKCARD_BALANCE_NOT_E | 用户银行卡余额不足 | 建议买家更换支付宝进行支付或者更换其它付款方式 | | ACQ.BUYER_ENABLE_STATUS_FORBID | 买家状态非法 | 用户联系支付宝小二[点这里](https://support.open.alipay.com/alipay/support/index.htm),确认买家状态为什么非法 | | ACQ.BUYER_PAYMENT_AMOUNT_DAY_LIM | 买家付款日限额超限 | 更换买家进行支付 | | ACQ.BUYER_PAYMENT_AMOUNT_MONTH_L | 买家付款月额度超限 | 买家更换账号后,重新付款或者更换其它付款方式 | | ACQ.BUYER_SELLER_EQUAL | 买卖家不能相同 | 更换买家重新付款 | | ACQ.CONTEXT_INCONSISTENT | 交易信息被篡改 | 更换商家订单号后,重新发起请求 | | ACQ.ERROR_BALANCE_PAYMENT_DISABL | 余额支付功能关闭 | 用户打开余额支付开关后,再重新进行支付 | | ACQ.ERROR_BUYER_CERTIFY_LEVEL_LI | 买家未通过人行认证 | 用户联系支付宝小二[点这里](https://support.open.alipay.com/alipay/support/index.htm) | | ACQ.EXIST_FORBIDDEN_WORD | 订单信息中包含违禁词 | 修改订单信息后,重新发起请求 | | ACQ.ILLEGAL_SIGN_VALIDTY_PERIOD | 无效的签约有效期 | 更改接口中传入的签约有效期 | | ACQ.INVALID_PARAMETER | 参数无效 | 检查请求参数,修改后重新发起请求 | | ACQ.MERCHANT_AGREEMENT_NOT_EXIST | 商户协议不存在 | 建议商户与支付宝确认签约代扣合同 | | ACQ.NO_PAYMENT_INSTRUMENTS_AVAIL | 没用可用的支付工具 | 更换其它付款方式 | | ACQ.PARTNER_ERROR | 应用APP_ID填写错误 | 联系支付宝小二[点这里](https://support.open.alipay.com/alipay/support/index.htm),确认APP_ID的状态 | | ACQ.PAYMENT_FAIL | 支付失败 | 用户刷新条码后,重新发起请求,如果重试一次后仍未成功,更换其它方式付款 | | ACQ.PAYMENT_REQUEST_HAS_RISK | 支付有风险 | 更换其它付款方式 | | ACQ.RISK_MERCHANT_IP_NOT_EXIST | 当前交易未传入IP信息,创单失败,请传入IP后再发起支付 | 检查请求参数是否已经传入用户IP信息 | | ACQ.SYSTEM_ERROR | 接口返回错误 | 请立即调用查询订单API,查询当前订单的状态,并根据订单状态决定下一步的操作,如果多次调用依然报此错误码,请联系支付宝客服。 | | ACQ.TOTAL_FEE_EXCEED | 订单总金额不在允许范围内 | 修改订单金额再发起请求 | | ACQ.TRADE_BUYER_NOT_MATCH | 交易买家不匹配 | 更换商家订单号后,重新发起请求 | | ACQ.TRADE_HAS_CLOSE | 交易已经关闭 | 更换商家订单号后,重新发起请求 | | ACQ.TRADE_HAS_SUCCESS | 交易已被支付 | 确认该笔交易信息是否为当前买家的,如果是则认为交易付款成功,如果不是则更换商家订单号后,重新发起请求 | #### 触发通知类型 | **通知类型** | **描述** | **默认开启** | | --- | --- | --- | | tradeStatus.TRADE_CLOSED | 交易关闭 | 0 | | tradeStatus.TRADE_FINISHED | 交易完结 | 0 | | tradeStatus.TRADE_SUCCESS | 支付成功 | 1 | | tradeStatus.WAIT_BUYER_PAY | 交易创建 | 0 | #### 触发通知示例 ```plain https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync¬ify_id=91722adff935e8cfa58b3aabf4dead6ibe¬ify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&gmt_close=null&out_trade_no=null&trade_no=null&out_channel_type=null&passback_params=null&voucher_detail_list=null&point_amount=null&buyer_pay_amount=null&invoice_amount=null&receipt_amount=null&fund_bill_list=null&merchant_app_id=2088102146225135&app_id=null&buyer_id=null&buyer_open_id=074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5&gmt_refund=null&gmt_payment=null&gmt_create=null&body=null&subject=null&refund_fee=null&total_amount=null&trade_status=null&seller_id=null&out_biz_no=null&buyer_logon_id=180****0062&charge_amount=8.88&charge_flags=bluesea_1&settlement_id=2018101610032004620239146945&receipt_currency_type=DC&hyb_amount=10.24&enterprise_pay_info={"invoice_amount":"28.00","is_use_enterprise_pay":"true"}&hb_fq_pay_info={"USER_INSTALL_NUM":"3"} ``` --- ### 统一收单交易查询接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI网页应用收款 > API列表 > 统一收单交易查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-query.md 该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态,并据此完成下一步业务逻辑 #### 接口说明 接口名称:`alipay.trade.query` 该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态,并据此完成下一步业务逻辑。 #### 适用场景 需要调用查询接口的常见情况: - 商户后台、网络、服务器等出现异常,商户系统最终未接收到支付通知。 - 调用支付接口后,返回系统错误或未知交易状态。 - 调用 `alipay.trade.cancel` 前,需要先确认支付状态。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `out_trade_no` 与 `trade_no` 二选一传入,不能同时为空。若 `trade_no` 与 `out_trade_no` 同时存在,优先使用 `trade_no` 查询。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 枚举值/说明 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_trade_no` | string | 二选一 | 64 | 订单支付时传入的商户订单号,和支付宝交易号不能同时为空 | 若与 `trade_no` 同时存在,优先取 `trade_no` | `20150320010101001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号,和商户订单号不能同时为空 | 若与 `out_trade_no` 同时存在,优先取 `trade_no` | `2014112611001004680 073956707` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "out_trade_no":"20150320010101001", "trade_no":"2014112611001004680 073956707", "query_options":[ "trade_settle_info" ] }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.response.AlipayTradeQueryResponse; import com.alipay.api.request.AlipayTradeQueryRequest; import com.alipay.api.domain.AlipayTradeQueryModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680 073956707"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("trade_settle_info"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.OutTradeNo = "20150320010101001"; // 设置支付宝交易号 model.TradeNo = "2014112611001004680 073956707"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("trade_settle_info"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.exec("alipay.trade.query", { bizContent: { out_trade_no: "20150320010101001", trade_no: "2014112611001004680+073956707", query_options: ["trade_settle_info"], }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE3w1J+POiPh...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 必选 | 64 | 支付宝交易号 | 在未生成真实交易时不返回,需要商户多次调用该接口或等待支付通知,获取最终的交易号 | `2013112011001004330000121536` | | `out_trade_no` | string | 必选 | 64 | 商家订单号 | - | `6823789339978248` | | `trade_status` | string | 必选 | 32 | 交易状态 | `WAIT_BUYER_PAY`:交易创建,等待买家付款
`TRADE_CLOSED`:未付款交易超时关闭,或支付完成后全额退款
`TRADE_SUCCESS`:交易支付成功
`TRADE_FINISHED`:交易结束,不可退款 | `TRADE_CLOSED` | | `total_amount` | price | 必选 | 11 | 交易的订单金额,单位为元,两位小数 | 该参数的值为支付时传入的 `total_amount` | `88.88` | | `buyer_user_id` | string | 必选 | 16 | 买家在支付宝的用户 ID | 新商户建议使用 `buyer_open_id` 替代该字段。对于新商户,`buyer_user_id` 字段未来计划逐步回收,存量商户可继续使用。若使用 `buyer_open_id`,请确认“应用 - 开发配置 - openid 配置管理”已启用;无该配置项时,可查看 [openid 配置申请](https://ideservice.alipay.com/cms/site/0ai9ok?pathHash=de631c06) | `2088101117955611` | | `send_pay_date` | date | 特殊可选 | 32 | 本次交易打款给卖家的时间 | - | `2014-11-27 15:45:57` | | `receipt_amount` | string | 特殊可选 | 11 | 实收金额,单位为元,两位小数 | 该金额为本笔交易中商户账户能够实际收到的金额 | `15.25` | | `buyer_open_id` | string | 特殊可选 | 128 | 买家支付宝用户唯一标识 | 详情可查看 [openid 简介](https://ideservice.alipay.com/cms/site/0ai2i6?pathHash=13dd5946) | `01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0` | | `buyer_logon_id` | string | 可选 | 100 | 买家支付宝账号 | 在未生成真实交易时不返回,需要商户多次调用该接口或等待支付通知,获取最终的用户信息 | `159****5620` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_query_response": { "code": "10000", "msg": "Success", "trade_no": "2013112011001004330000121536", "out_trade_no": "6823789339978248", "buyer_logon_id": "159****5620", "trade_status": "TRADE_CLOSED", "total_amount": "88.88", "send_pay_date": "2014-11-27 15:45:57", "buyer_pay_amount": "8.88", "invoice_amount": "12.11", "point_amount": "10", "receipt_amount": "15.25", "store_id": "NJ_S_001", "terminal_id": "NJ_T_001", "fund_bill_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21" } ], "store_name": "证大五道口店", "buyer_open_id": "01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0", "buyer_user_id": "2088101117955611", "discount_amount": "88.88", "ext_infos": "{\"action\":\"cancel\"}", "buyer_user_type": "PRIVATE", "mdiscount_amount": "88.88" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.INVALID_PARAMETER` | 参数无效 | 检查请求参数,修改后重新发起请求 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 查询的交易不存在 | 检查传入的交易号是否正确,修改后重新发起请求 | --- ### 统一收单交易退款接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI网页应用收款 > API列表 > 统一收单交易退款接口 来源:https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-refund.md 卖家可以通过退款接口将支付款退还给买家 #### 接口说明 接口名称:`alipay.trade.refund` 当交易发生之后一段时间内,由于买家或卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家。支付宝在收到退款请求并验证成功后,会按照退款规则将支付款按原路退回买家账号。 交易超过约定时间(签约时设置的可退款时间)的订单无法进行退款。 支付宝退款支持单笔交易分多次退款,多次退款需要提交原支付订单的订单号,并设置不同的退款请求号。一笔退款失败后重新提交时,必须保证退款请求号不变,防止重复退款。同一笔交易累计提交的退款金额不能超过原始交易总金额。 #### 注意事项 1. 同一笔交易的退款至少间隔 3 秒后发起。 2. 请严格按照接口文档中的参数接入。若传入非当前接口文档中的参数,可能造成退款失败或重复退款。 3. 该接口不可与其他退款产品混用。若商户侧同一笔退款请求已使用当前接口退款,再使用其他退款产品退款,可能造成重复退款。 4. 退款成功判断:接口返回 `fund_change=Y` 表示退款成功;`fund_change=N` 或无此字段返回时,需要通过退款查询接口进一步确认退款状态。详见[退款成功判断指导](https://ideservice.alipay.com/cms/site/01rawa)。接口中 `code=10000` 仅代表本次退款请求成功,不代表退款成功。 5. 若退款原订单涉及分账,在发起退款前,需要分账接收方在[支付宝商家平台](https://b.alipay.com/page/portal/home) > 资金管理 > 资金服务 > 分账接收设置中开启分账回退授权后,才可以正常退款。且不支持接收方为个人的分账单发起退款退分账。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.refund` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `out_trade_no` 与 `trade_no` 二选一传入,不能同时为空。两者同时存在时,优先使用 `trade_no`。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `refund_amount` | price | 必选 | 16 | 退款金额,单位为元,支持两位小数,不能大于订单金额 | 如果正向交易使用了营销,该退款金额包含营销金额。支付宝会按业务规则分配营销和买家自有资金分别退多少,默认优先退买家的自有资金 | `200.12` | | `out_trade_no` | string | 二选一 | 64 | 商户订单号,订单支付时传入,商家自定义且保证商家系统中唯一 | 与 `trade_no` 不能同时为空 | `20150320010101001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号 | 与 `out_trade_no` 不能同时为空;两者同时存在时,优先取 `trade_no` | `2014112611001004680073956707` | | `refund_reason` | string | 可选 | 256 | 退款原因说明,商家自定义 | 会在商户和用户的 PC 退款账单详情中展示 | `正常退款` | | `out_request_no` | string | 可选 | 64 | 退款请求号,标识一次退款请求,需要保证在交易号下唯一 | 部分退款时必选。同一次退款请求失败或异常后重试时,必须保证退款请求号不变,防止重复退款。支付宝会保证同样的退款请求号多次请求只退一次 | `HZ01RF001` | #### 请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.refund&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "out_trade_no":"20150320010101001", "trade_no":"2014112611001004680073956707", "refund_amount":"200.12", "refund_reason":"正常退款", "out_request_no":"HZ01RF001", "refund_goods_detail":[ { "out_sku_id":"outSku_01", "out_item_id":"outItem_01", "goods_id":"apple-01", "refund_amount":"19.50", "out_certificate_no_list":[ "202407013232143241231243243423" ] } ], "refund_royalty_parameters":[ { "amount":"0.1", "trans_in":"2088101126708402", "royalty_type":"transfer", "trans_out":"2088101126765726", "trans_out_type":"userId", "royalty_scene":"达人佣金", "trans_in_type":"userId", "trans_in_name":"张三", "desc":"分账给2088101126708402" } ], "query_options":[ "refund_detail_item_list" ], "related_settle_confirm_no":"2024041122001495000530302869" }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeRefundModel; import com.alipay.api.request.AlipayTradeRefundRequest; import com.alipay.api.response.AlipayTradeRefundResponse; import com.alipay.api.domain.RefundGoodsDetail; import com.alipay.api.domain.OpenApiRoyaltyDetailInfoPojo; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeRefund { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); AlipayTradeRefundModel model = new AlipayTradeRefundModel(); // 设置商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680073956707"); // 设置退款金额 model.setRefundAmount("200.12"); // 设置退款原因说明 model.setRefundReason("正常退款"); // 设置退款请求号 model.setOutRequestNo("HZ01RF001"); // 设置退款包含的商品列表信息 List refundGoodsDetail = new ArrayList(); RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail(); refundGoodsDetail0.setOutSkuId("outSku_01"); refundGoodsDetail0.setOutItemId("outItem_01"); refundGoodsDetail0.setGoodsId("apple-01"); refundGoodsDetail0.setRefundAmount("19.50"); List outCertificateNoList = new ArrayList(); outCertificateNoList.add("202407013232143241231243243423"); refundGoodsDetail0.setOutCertificateNoList(outCertificateNoList); refundGoodsDetail.add(refundGoodsDetail0); model.setRefundGoodsDetail(refundGoodsDetail); // 设置退分账明细信息 List refundRoyaltyParameters = new ArrayList(); OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo(); refundRoyaltyParameters0.setAmount("0.1"); refundRoyaltyParameters0.setTransIn("2088101126708402"); refundRoyaltyParameters0.setRoyaltyType("transfer"); refundRoyaltyParameters0.setTransOut("2088101126765726"); refundRoyaltyParameters0.setTransOutType("userId"); refundRoyaltyParameters0.setRoyaltyScene("达人佣金"); refundRoyaltyParameters0.setTransInType("userId"); refundRoyaltyParameters0.setTransInName("张三"); refundRoyaltyParameters0.setDesc("分账给2088101126708402"); refundRoyaltyParameters.add(refundRoyaltyParameters0); model.setRefundRoyaltyParameters(refundRoyaltyParameters); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("refund_detail_item_list"); model.setQueryOptions(queryOptions); // 设置针对账期交易 model.setRelatedSettleConfirmNo("2024041122001495000530302869"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeRefundResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeRefund { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); AlipayTradeRefundModel model = new AlipayTradeRefundModel(); // 设置商户订单号 model.OutTradeNo = "20150320010101001"; // 设置支付宝交易号 model.TradeNo = "2014112611001004680073956707"; // 设置退款金额 model.RefundAmount = "200.12"; // 设置退款原因说明 model.RefundReason = "正常退款"; // 设置退款请求号 model.OutRequestNo = "HZ01RF001"; // 设置退款包含的商品列表信息 List refundGoodsDetail = new List(); RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail(); refundGoodsDetail0.OutSkuId = "outSku_01"; refundGoodsDetail0.OutItemId = "outItem_01"; refundGoodsDetail0.GoodsId = "apple-01"; refundGoodsDetail0.RefundAmount = "19.50"; List outCertificateNoList = new List(); outCertificateNoList.Add("202407013232143241231243243423"); refundGoodsDetail0.OutCertificateNoList = outCertificateNoList; refundGoodsDetail.Add(refundGoodsDetail0); model.RefundGoodsDetail = refundGoodsDetail; // 设置退分账明细信息 List refundRoyaltyParameters = new List(); OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo(); refundRoyaltyParameters0.Amount = "0.1"; refundRoyaltyParameters0.TransIn = "2088101126708402"; refundRoyaltyParameters0.RoyaltyType = "transfer"; refundRoyaltyParameters0.TransOut = "2088101126765726"; refundRoyaltyParameters0.TransOutType = "userId"; refundRoyaltyParameters0.RoyaltyScene = "达人佣金"; refundRoyaltyParameters0.TransInType = "userId"; refundRoyaltyParameters0.TransInName = "张三"; refundRoyaltyParameters0.Desc = "分账给2088101126708402"; refundRoyaltyParameters.Add(refundRoyaltyParameters0); model.RefundRoyaltyParameters = refundRoyaltyParameters; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("refund_detail_item_list"); model.QueryOptions = queryOptions; // 设置针对账期交易 model.RelatedSettleConfirmNo = "2024041122001495000530302869"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeRefundResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const AlipaySdk = require("alipay-sdk").default; const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", }); const result = await alipaySdk.exec("alipay.trade.refund", { bizContent: { out_trade_no: "20150320010101001", trade_no: "2014112611001004680073956707", refund_amount: "200.12", refund_reason: "正常退款", out_request_no: "HZ01RF001", refund_goods_detail: { 0: { out_sku_id: "outSku_01", out_item_id: "outItem_01", goods_id: "apple-01", refund_amount: "19.50", out_certificate_no_list: { 0: "202407013232143241231243243423", }, }, }, refund_royalty_parameters: { 0: { amount: "0.1", trans_in: "2088101126708402", royalty_type: "transfer", trans_out: "2088101126765726", trans_out_type: "userId", royalty_scene: "达人佣金", trans_in_type: "userId", trans_in_name: "张三", desc: "分账给2088101126708402", }, }, query_options: { 0: "refund_detail_item_list", }, related_settle_confirm_no: "2024041122001495000530302869", }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 必选 | 64 | 支付宝交易号 | - | `2013112011001004330000121536` | | `out_trade_no` | string | 必选 | 64 | 商户订单号 | - | `6823789339978248` | | `buyer_logon_id` | string | 必选 | 100 | 用户的登录 ID | - | `159****5620` | | `refund_fee` | price | 必选 | 11 | 退款总金额,单位为元 | 指该笔交易累计已经退款成功的金额 | `88.88` | | `buyer_user_id` | string | 特殊可选 | 28 | 买家在支付宝的用户 ID | 新商户建议使用 `buyer_open_id` 替代该字段。对于新商户,`buyer_user_id` 字段未来计划逐步回收,存量商户可继续使用。若使用 `buyer_open_id`,请确认“应用 - 开发配置 - openid 配置管理”已启用;无该配置项时,可查看 [openid 配置申请](https://ideservice.alipay.com/cms/site/0ai9ok?pathHash=de631c06) | `2088101117955611` | | `buyer_open_id` | string | 特殊可选 | 128 | 买家支付宝用户唯一标识 | 详情可查看 [openid 简介](https://ideservice.alipay.com/cms/site/0ai2i6?pathHash=13dd5946) | `074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5` | | `send_back_fee` | string | 特殊可选 | 11 | 本次商户实际退回金额,单位为元 | 如需获取该值,需在入参 `query_options` 中传入 `refund_detail_item_list` | `1.8` | | `fund_change` | string | 可选 | 1 | 本次退款是否发生了资金变化 | `Y` 通常表示退款成功;`N` 或无此字段时需通过退款查询接口进一步确认退款状态 | `Y` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_refund_response": { "code": "10000", "msg": "Success", "trade_no": "2013112011001004330000121536", "out_trade_no": "6823789339978248", "buyer_logon_id": "159****5620", "fund_change": "Y", "refund_fee": "88.88", "refund_detail_item_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21", "fund_type": "DEBIT_CARD" } ], "store_name": "望湘园联洋店", "buyer_user_id": "2088101117955611", "buyer_open_id": "074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5", "send_back_fee": "1.8", "refund_hyb_amount": "10.24", "refund_charge_info_list": [ { "refund_charge_fee": "0.01", "switch_fee_rate": "0.01", "charge_type": "trade", "refund_sub_fee_detail_list": [ { "refund_charge_fee": "0.10", "switch_fee_rate": "0.01" } ] } ], "refund_voucher_detail_list": [ { "id": "2015102600073002039000002D5O", "name": "XX超市5折优惠", "type": "ALIPAY_FIX_VOUCHER", "amount": "10.00", "merchant_contribute": "9.00", "other_contribute": "1.00", "memo": "学生专用优惠", "template_id": "20171030000730015359000EMZP0", "other_contribute_detail": [ { "contribute_type": "BRAND", "contribute_amount": "8.00" } ], "purchase_buyer_contribute": "2.01", "purchase_merchant_contribute": "1.03", "purchase_ant_contribute": "0.82" } ], "pre_auth_cancel_fee": "12.45" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_refund_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.ALLOC_AMOUNT_VALIDATE_ERROR` | 退分账金额超限 | 请调整退分账金额后重试 | | `ACQ.BUYER_ENABLE_STATUS_FORBID` | 买家状态异常 | 联系支付宝小二确认买家状态异常原因,或者联系买家进行线下退款处理 | | `ACQ.BUYER_ERROR` | 买家状态异常 | 联系支付宝小二确认买家状态异常原因,或者联系买家进行线下退款处理 | | `ACQ.BUYER_NOT_EXIST` | 买家不存在 | 买家已经注销账号,建议联系买家进行线下退款处理 | | `ACQ.CURRENCY_NOT_SUPPORT` | 退款币种不支持 | 请确认传入的退款币种是否正确 | | `ACQ.CUSTOMER_VALIDATE_ERROR` | 账户已注销或者被冻结 | 请查询账户状态:如果账户已注销,请线下处理;如果账户已冻结,请联系支付宝小二确认冻结原因 | | `ACQ.DISCORDANT_REPEAT_REQUEST` | 请求信息不一致 | 退款请求号对应的退款已经执行成功,且本次请求的退款金额与之前请求的金额不一致。请检查退款金额是否正确,或通过退款查询接口获取退款执行结果 | | `ACQ.ENTERPRISE_PAY_BIZ_ERROR` | 因公付业务异常 | 如果提示“当前交易不含企业出资”,请确认交易是否包含企业出资;如果不包含,接口入参不能指定 `enterprise_pay_info`;如果确认包含,请联系支付宝核实。如果提示“无效企业退款金额”,请检查指定的企业退款金额是否超过当前交易企业支付的金额。其他情况请联系支付宝小二 | | `ACQ.INVALID_PARAMETER` | 参数无效 | 请根据接口返回的错误信息检查请求参数,修改后重新发起请求 | | `ACQ.NOT_ALLOW_PARTIAL_REFUND` | 不支持部分退款 | 由于交易使用了特定优惠券等场景,该笔交易不支持部分退款,请进行全额退款或联系买家线下退款 | | `ACQ.ONLINE_TRADE_VOUCHER_NOT_ALLOW_REFUND` | 交易不允许退款 | 此交易中核销了购买的代金券,不允许退款,可联系买家线下退款 | | `ACQ.OVERDRAFT_AGREEMENT_NOT_MATCH` | 垫资退款接口传入模式和签约配置不一致 | 请检查垫资退款合约中的出资方式,修改合约或接口传参后重试 | | `ACQ.OVERDRAFT_ASSIGN_ACCOUNT_INVALID` | 垫资退款出资账号和商户信息不一致 | 垫资退款出资账号必须为商户名下支付宝账号,请更换出资账号后重试 | | `ACQ.REASON_TRADE_BEEN_FREEZEN` | 请求退款的交易被冻结 | 联系支付宝小二确认该笔交易的具体情况 | | `ACQ.REASON_TRADE_REFUND_FEE_ERR` | 退款金额无效 | 同一笔交易累计请求的退款金额不能大于交易总金额,请检查退款请求金额是否正确 | | `ACQ.REASON_TRADE_STATUS_INVALID` | 交易状态异常 | 查询交易,确认交易是否为支付成功状态;如是,可联系支付宝小二确认交易状态 | | `ACQ.REFUNDALLOC_UNAUTH_LIMIT` | 分账接收方未开启分账回退,退分账失败 | 请联系分账接收方在支付宝商家平台 > 资金管理 > 资金服务 > 分账接收设置中开启分账回退授权后再发起调用 | | `ACQ.REFUND_ACCOUNT_NOT_EXIST` | 退款出资账号不存在或账号异常 | 检查退款出资账号状态,账号正常后重试 | | `ACQ.REFUND_AMT_NOT_EQUAL_TOTAL` | 退款金额超限 | 请检查退款金额是否正确,请求退款金额不能大于交易总金额;如果不是全额退款,退款请求号必填,请检查是否传入退款请求号 | | `ACQ.REFUND_CHARGE_ERROR` | 退收费异常 | 请过一段时间后再重试发起退款 | | `ACQ.REFUND_FEE_ERROR` | 交易退款金额有误 | 请检查传入的退款金额是否正确 | | `ACQ.REFUND_ROYALTY_PAYEE_ACCOUNT_NOT_EXIST` | 退分账收入方账户不存在 | 请确认收入方账号是否正确,更换账号后重新发起 | | `ACQ.SELLER_BALANCE_NOT_ENOUGH` | 卖家余额不足 | 商户支付宝账户充值后重新发起退款 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 当前退款请求可能成功也可能失败。请使用相同参数再次重试,保证退款请求号和退款金额不变;如果前一次退款已经成功,接口会幂等返回成功;如果前一次未成功,接口会重试执行退款。也可通过退款查询接口查询退款执行结果,发起退款查询需保证距离退款请求大于 5 秒 | | `ACQ.TRADE_HAS_CLOSE` | 交易已关闭 | 该交易已关闭,不能再退款,请确认请求退款的交易是否未支付或已完成退款 | | `ACQ.TRADE_HAS_FINISHED` | 交易已完结 | 该交易已完结,已超过退款期限,不允许退款;建议联系买家线下退款 | | `ACQ.TRADE_NOT_ALLOW_REFUND` | 当前交易不允许退款 | 检查当前交易状态是否为交易成功状态,以及签约的退款属性是否允许退款,确认后重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 检查请求中的交易号和商户订单号是否正确,确认后重新发起 | | `ACQ.TRADE_SETTLE_ERROR` | 交易结算异常 | 请检查传入的退结算项信息是否正确;如果正确,请联系支付宝小二 | | `ACQ.TRADE_STATUS_ERROR` | 交易状态非法 | 查询交易,确认交易是否已经付款 | | `ACQ.USER_NOT_MATCH_ERR` | 交易用户不匹配 | 请联系支付宝小二处理 | --- ### 统一收单交易退款查询接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI网页应用收款 > API列表 > 统一收单交易退款查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-fastpay-refund-query.md 商户可使用该接口查询提交的退款请求是否执行成功。 #### 接口说明 接口名称:`alipay.trade.fastpay.refund.query` 商户可使用该接口查询自己通过 `alipay.trade.refund` 提交的退款请求是否执行成功。 #### 注意事项 1. 该接口返回码 `10000` 仅代表本次查询操作成功,不代表退款成功。当接口返回的 `refund_status` 值为 `REFUND_SUCCESS` 时,表示退款成功;否则表示退款没有执行成功。 2. 如果退款未成功,商户可以调用退款接口重试。重试时请务必保证退款请求号和退款金额一致,防止重复退款。 3. 发起退款查询接口的时间不能离退款请求时间太短,建议间隔 10 秒以上。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.fastpay.refund.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `trade_no` 与 `out_trade_no` 二选一传入,不能同时为空。两者同时存在时,优先使用 `trade_no`。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | string | 必选 | 64 | 退款请求号 | 请求退款接口时传入的退款请求号;如果退款请求时未传入,则该值为创建交易时的商户订单号 | `HZ01RF001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号 | 与商户订单号不能同时为空 | `2021081722001419121412730660` | | `out_trade_no` | string | 二选一 | 64 | 商户订单号,订单支付时传入 | 与支付宝交易号不能同时为空;`trade_no`、`out_trade_no` 同时存在时,优先取 `trade_no` | `2014112611001004680073956707` | #### 请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.fastpay.refund.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "trade_no":"2021081722001419121412730660", "out_trade_no":"2014112611001004680073956707", "out_request_no":"HZ01RF001", "query_options":[ "refund_detail_item_list" ] }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeFastpayRefundQueryModel; import com.alipay.api.response.AlipayTradeFastpayRefundQueryResponse; import com.alipay.api.request.AlipayTradeFastpayRefundQueryRequest; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeFastpayRefundQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest(); AlipayTradeFastpayRefundQueryModel model = new AlipayTradeFastpayRefundQueryModel(); // 设置支付宝交易号 model.setTradeNo("2021081722001419121412730660"); // 设置商户订单号 model.setOutTradeNo("2014112611001004680073956707"); // 设置退款请求号 model.setOutRequestNo("HZ01RF001"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("refund_detail_item_list"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeFastpayRefundQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeFastpayRefundQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest(); AlipayTradeFastpayRefundQueryModel model = new AlipayTradeFastpayRefundQueryModel(); // 设置支付宝交易号 model.TradeNo = "2021081722001419121412730660"; // 设置商户订单号 model.OutTradeNo = "2014112611001004680073956707"; // 设置退款请求号 model.OutRequestNo = "HZ01RF001"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("refund_detail_item_list"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeFastpayRefundQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoY...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 特殊可选 | 64 | 支付宝交易号 | - | `2014112611001004680073956707` | | `out_trade_no` | string | 特殊可选 | 64 | 创建交易传入的商户订单号 | - | `20150320010101001` | | `out_request_no` | string | 特殊可选 | 64 | 本笔退款对应的退款请求号 | - | `20150320010101001` | | `total_amount` | price | 特殊可选 | 11 | 该笔退款所对应交易的订单金额,单位为元 | - | `100.20` | | `refund_amount` | price | 特殊可选 | 11 | 本次退款请求对应的退款金额,单位为元 | - | `12.33` | | `refund_status` | string | 特殊可选 | 32 | 退款状态 | `REFUND_SUCCESS`:退款处理成功。未返回该字段表示退款请求未收到或退款失败。如果退款查询发起时间早于退款时间,或距离退款发起时间太短,可能出现查询时尚未处理成功、后续又处理成功的情况,建议退款发起后间隔 10 秒以上再查询 | `REFUND_SUCCESS` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_fastpay_refund_query_response": { "code": "10000", "msg": "Success", "trade_no": "2014112611001004680073956707", "out_trade_no": "20150320010101001", "out_request_no": "20150320010101001", "total_amount": "100.20", "refund_amount": "12.33", "refund_status": "REFUND_SUCCESS", "refund_royaltys": [ { "refund_amount": "10", "royalty_type": "transfer", "result_code": "SUCCESS", "trans_out": "2088102210397302", "trans_out_email": "alipay-test03@alipay.com", "trans_in": "2088102210397302", "trans_in_email": "zen_gwen@hotmail.com", "ori_trans_out": "2088111111111111", "ori_trans_in": "2088111111111111" } ], "gmt_refund_pay": "2014-11-27 15:45:57", "refund_detail_item_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21", "fund_type": "DEBIT_CARD" } ], "send_back_fee": "88", "deposit_back_info": { "has_deposit_back": "true", "dback_status": "S", "dback_amount": "1.01", "bank_ack_time": "2020-06-02 14:03:48", "est_bank_receipt_time": "2020-06-02 14:03:48" }, "refund_hyb_amount": "10.24", "refund_charge_info_list": [ { "refund_charge_fee": "0.01", "switch_fee_rate": "0.01", "charge_type": "trade", "refund_sub_fee_detail_list": [ { "refund_charge_fee": "0.10", "switch_fee_rate": "0.01" } ] } ], "deposit_back_info_list": [ { "has_deposit_back": "true", "dback_status": "S", "dback_amount": "1.01", "bank_ack_time": "2020-06-02 14:03:48", "est_bank_receipt_time": "2020-06-02 14:03:48" } ], "refund_voucher_detail_list": [ { "id": "2015102600073002039000002D5O", "name": "XX超市5折优惠", "type": "ALIPAY_FIX_VOUCHER", "amount": "10.00", "merchant_contribute": "9.00", "other_contribute": "1.00", "memo": "学生专用优惠", "template_id": "20171030000730015359000EMZP0", "other_contribute_detail": [ { "contribute_type": "BRAND", "contribute_amount": "8.00" } ], "purchase_buyer_contribute": "2.01", "purchase_merchant_contribute": "1.03", "purchase_ant_contribute": "0.82" } ], "pre_auth_cancel_fee": "12.45" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_fastpay_refund_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.ENTERPRISE_PAY_BIZ_ERROR` | 因公付业务异常 | 重新发起查询请求;如果多次重试后仍返回同样错误,请联系支付宝小二处理 | | `ACQ.INVALID_PARAMETER` | 参数无效 | 请根据接口返回的错误信息检查请求参数,修改后重新发起请求 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 重新发起查询请求;如果多次重试后仍返回系统错误,请联系支付宝小二处理 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 请确认传入的外部订单号或交易号是否正确 | | `TRADE_NOT_EXIST` | 查询退款的交易不存在 | 确认交易号是否为正确的支付宝交易号,修改后重新查询 | --- ### 统一收单交易关闭接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI网页应用收款 > API列表 > 统一收单交易关闭接口 来源:https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-close.md 用于交易创建后,用户在一定时间内未进行支付,可调用该接口直接将未付款的交易进行关闭。 #### 接口说明 接口名称:`alipay.trade.close` 用于交易创建后,用户在一定时间内未进行支付,可调用该接口直接将未付款的交易进行关闭。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.close` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `trade_no` 与 `out_trade_no` 二选一传入,不能同时为空。若两者同时传入,以 `trade_no` 为准。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 二选一 | 64 | 该交易在支付宝系统中的交易流水号,最短 16 位,最长 64 位 | 与 `out_trade_no` 不能同时为空;若同时传入 `out_trade_no` 和 `trade_no`,以 `trade_no` 为准 | `2013112611001004680073956707` | | `out_trade_no` | string | 二选一 | 64 | 订单支付时传入的商户订单号 | 与支付宝交易号不能同时为空;若 `trade_no`、`out_trade_no` 同时存在,优先取 `trade_no` | `HZ0120131127001` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.close&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "trade_no":"2013112611001004680073956707", "out_trade_no":"HZ0120131127001", "operator_id":"YX01" }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeCloseRequest; import com.alipay.api.domain.AlipayTradeCloseModel; import com.alipay.api.response.AlipayTradeCloseResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeClose { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCloseRequest request = new AlipayTradeCloseRequest(); AlipayTradeCloseModel model = new AlipayTradeCloseModel(); // 设置该交易在支付宝系统中的交易流水号 model.setTradeNo("2013112611001004680073956707"); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("HZ0120131127001"); // 设置商家操作员编号 id model.setOperatorId("YX01"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCloseResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeClose { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCloseRequest request = new AlipayTradeCloseRequest(); AlipayTradeCloseModel model = new AlipayTradeCloseModel(); // 设置该交易在支付宝系统中的交易流水号 model.TradeNo = "2013112611001004680073956707"; // 设置订单支付时传入的商户订单号 model.OutTradeNo = "HZ0120131127001"; // 设置商家操作员编号 id model.OperatorId = "YX01"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCloseResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.exec("alipay.trade.close", { bizContent: { trade_no: "2013112611001004680073956707", out_trade_no: "HZ0120131127001", operator_id: "YX01", }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | ACQ.TRADE_HAS_SUCCESS | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | 交易已被支付 | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 特殊可选 | 64 | 支付宝交易号 | - | `2013112111001004500000675971` | | `out_trade_no` | string | 特殊可选 | 64 | 创建交易传入的商户订单号 | - | `YX_001` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_close_response": { "code": "10000", "msg": "Success", "trade_no": "2013112111001004500000675971", "out_trade_no": "YX_001" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_close_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.INVALID_PARAMETER` | 参数无效 | 检查请求参数,修改后重新发起请求 | | `ACQ.REASON_ILLEGAL_STATUS` | 交易状态异常 | 确认交易状态,非待支付状态下不支持关单操作 | | `ACQ.REASON_TRADE_STATUS_INVALID` | 交易状态异常 | 确认交易状态,非待支付状态下不支持关单操作 | | `ACQ.SYSTEM_ERROR` | 系统异常 | 重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 检查传入的交易号和外部订单号是否正确,修改后重新发起 | | `ACQ.TRADE_STATUS_ERROR` | 交易状态不合法 | 检查当前交易的状态是否为等待买家付款。只有等待买家付款状态下才能发起交易关闭 | #### 触发通知类型 | 通知类型 | 描述 | 默认开启 | | --- | --- | --- | | `tradeStatus.TRADE_CLOSED` | 交易关闭 | `1` | | `tradeStatus.TRADE_SUCCESS` | 交易成功 | `0` | #### 触发通知示例 ```text https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync¬ify_id=91722adff935e8cfa58b3aabf4dead6ibe¬ify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&trade_no=null&app_id=null&out_trade_no=null&out_biz_no=null&buyer_logon_id=null&seller_id=null&seller_email=null&trade_status=null&total_amount=null&refund_fee=null&subject=null&body=null&gmt_create=null&gmt_payment=null&gmt_refund=null&gmt_close=null&fund_bill_list=null&receipt_amount=null&invoice_amount=null&buyer_pay_amount=null&point_amount=null&buyer_id=null ``` --- ### 查询对账单下载地址接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI网页应用收款 > API列表 > 查询对账单下载地址接口 来源:https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-data-dataservice-bill-downloadurl-query.md 方便商户快速查账,支持商户通过本接口获取商户离线账单下载地址 #### 接口说明 接口名称:`alipay.data.dataservice.bill.downloadurl.query` 为方便商户快速查账,支付宝支持商户通过本接口获取商户离线账单下载地址。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.data.dataservice.bill.downloadurl.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `bill_type` | string | 必选 | 20 | 账单类型,商户通过接口,或商户经开放平台授权后其所属服务商通过接口,可以获取对应账单类型 | `trade`:商户基于支付宝交易收单的业务账单
`signcustomer`:基于商户支付宝余额收入及支出等资金变动的账务账单
`merchant_act`:营销活动账单,包含营销活动的发放、核销记录
`trade_zft_merchant`:直付通二级商户查询交易的业务账单
`zft_acc`:直付通平台商查询二级商户流水使用,返回所有二级商户流水
`settlementMerge`:每日结算到卡的资金对应明细,下载内容包含批次结算到卡明细文件和批次结算到卡汇总文件;若查询时间范围内有多个批次,会将多个批次的明细和汇总文件打包到一份压缩包中 | `trade` | | `bill_date` | string | 必选 | 15 | 账单时间 | 日账单格式为 `yyyy-MM-dd`,最早可下载近 6 年的日账单;不支持下载当日账单,只能下载前一日 24 点前的账单数据(T+1),当日数据一般于次日 9 点前生成,特殊情况可能延迟
月账单格式为 `yyyy-MM`,最早可下载近 6 年的月账单;不支持下载当月账单,只能下载上一月账单数据,当月账单一般在次月 3 日生成,特殊情况可能延迟
当 `biz_type` 为 `settlementMerge` 时,时间为汇总批次结算资金到账日期,格式为 `yyyy-MM-dd`,最早可下载 2023 年 4 月 17 日及以后的账单
接口调用仅支持下载近 6 年的账单,更多账单请前往 `b.alipay.com` 对账中心-账单下载页下载 | `2025-05-01` | | `smid` | string | 可选 | 20 | 二级商户 `smid` | 仅在 `bill_type` 为 `trade_zft_merchant` 时可使用 | `2088123412341234` | #### 请求示例 ##### cURL ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.data.dataservice.bill.downloadurl.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "bill_type":"trade", "bill_date":"2025-05-01", "smid":"2088123412341234" }' ``` #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `bill_download_url` | string | 可选 | 2048 | 当账单可获取时,返回账单下载地址链接 | 获取链接后 30 秒内未下载,链接地址失效 | `http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&pid=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X` | | `bill_file_code` | string | 可选 | 64 | 账单文件结果说明,描述本次申请的账单文件状态 | `EMPTY_DATA_WITH_BILL_FILE`:当前周期无数据时产生的空账单数据文件。目前仅对默认配置用户生效,主动配置的不会返回当前字段 | `EMPTY_DATA_WITH_BILL_FILE` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_data_dataservice_bill_downloadurl_query_response": { "code": "10000", "msg": "Success", "bill_download_url": "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&pid=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X", "bill_file_code": "EMPTY_DATA_WITH_BILL_FILE" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_data_dataservice_bill_downloadurl_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `BILL_DATE_BEFORE_REGISTRATION` | 请求的账单时间早于注册时间 | 确认参数后重新查询 | | `BILL_NOT_EXIST` | 账单不存在 | 确认参数后重新查询 | | `INVAILID_ARGUMENTS` | 入参不合法 | 确认参数后重新查询 | | `NO_BILL_DATA` | 商户在请求的账单时间内没有发生当前账单类型的业务 | 确认参数后重新查询 | | `SYSTEM_RATE_LIMIT` | 系统当前负载较高,请求被限流,请稍后重试 | 间隔 1 分钟后重试 | | `TYPE_NOT_SUPPORTED` | 此账单类型不支持下载 | 根据不同 `bill_type` 确定解决方案:
`trade`:需签约支付宝支付产品,且有对应产品产生的实际流水,支付产品范围详见[支付宝产品大全](https://b.alipay.com/page/product-mall/all-product?mrchportalwebServer=https%3A%2F%2Fmrchportalweb.alipay.com#J_wysk)
`signcustomer`:非支付宝商家身份,建议先签约收钱码或经营码产品
`merchant_act`:一年内无营销动作,具体请参考[营销账单使用](https://ideservice.alipay.com/cms/site/03ae7i?pathHash=83ffda2d)
`trade_zft_merchant`:请联系直付通平台商提供对应账单数据
`zft_acc`:请先签约[互联网平台直付通](https://b.alipay.com/page/product-mall/solution-detail?solutionCode=SP000001000000007155&sceneCode=PAYMENT)产品
`settlementMerge`:请先签约[收款到银行账户](https://b.alipay.com/page/product-mall/product-detail/I1080300001000041457/ALL?)产品
其他:该账单类型不支持下载操作,请再次确认账单类型及所选日期。如有需求,请联系支付宝小二排查 | | `UNKNOWN_ERROR` | 未知错误 | 稍后重试或联系小二排查问题 | | `USER_RATE_LIMIT` | 调用频率超限 | 间隔 1 分钟后重试,查看[调用频率限制](https://ideservice.alipay.com/cms/site/01inen?pathHash=4fae1c5e)中新增的 2.4 请求频次 | --- ### 异步通知说明 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI网页应用收款 > API列表 > 异步通知说明 来源:https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/async-notify-verify.md 异步通知说明 #### 使用说明 异步通知是指一笔订单支付完成后,支付宝会将该笔订单的变更信息,沿着商家调用支付请求时传入的异步通知地址 `notify_url`,通过 POST 请求将支付结果作为参数通知到商家系统。 异步回调地址状态码(HTTP 状态码)为 `200` 时表示异步通知成功;返回码为 `404` 或 `500` 时表示服务器内部错误,需要商家自行排查。 #### 注意事项 :::info 由于网络异常、系统波动等原因,可能会存在用户支付成功但商户侧未能成功接收到支付结果异步通知的情况。这会导致商户获取不到支付结果、用户订单显示为未支付。 为杜绝以上问题,商户需要同时接入支付结果异步通知与统一收单交易查询接口。当商户侧未收到支付结果异步通知时,必须调用 `alipay.trade.query` 查询订单支付结果。 当商户针对同一笔业务订单更换商户订单号 `out_trade_no` 来请求支付宝前,强烈建议先查询前一个商户订单号的支付结果: - 若为支付成功(`trade_status = TRADE_SUCCESS`),不要再请求支付宝重复支付。 - 若买家仍未支付(`trade_status = WAIT_BUYER_PAY`),调用 `alipay.trade.close` 关闭此订单后再请求支付宝支付。 ::: #### 异步通知参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `notify_time` | Date | 必选 | - | 通知发送时间,格式为 `yyyy-MM-dd HH:mm:ss`。 | - | 2020-12-27 06:20:30 | | `notify_type` | String | 必选 | 64 | 通知类型。 | 枚举值:`trade_status_sync`。 | trade_status_sync | | `notify_id` | String | 必选 | 128 | 通知校验 ID。 | - | ac05099524730693a8b330c5ecf72da9786 | | `sign_type` | String | 必选 | 10 | 签名类型,商家生成签名字符串所使用的签名算法类型。 | 目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2`。如果开发者手动验签且不使用 SDK 验签,可以不传此参数。 | RSA2 | | `sign` | String | 必选 | 344 | 签名。 | 可查看“异步返回结果验签”。如果开发者手动验签且不使用 SDK 验签,可以不传此参数。 | 601510b7970e52cc63db0f44997cf70e | | `trade_no` | String | 必选 | 64 | 支付宝交易号,支付宝交易凭证号。 | - | 20213112011001004330000121536 | | `app_id` | String | 必选 | 32 | 开发者的 app_id,支付宝分配给开发者的应用 APPID。 | - | 2014072300007148 | | `auth_app_id` | String | 必选 | 32 | 开发者的 app_id,在服务商调用场景下为授权方的 app_id。 | - | 2014072300007148 | | `out_trade_no` | String | 必选 | 64 | 商户订单号。 | - | 6823789339978248 | | `out_biz_no` | String | 可选 | 64 | 商家业务号,主要是退款通知中返回退款申请的流水号。 | - | HZRF001 | | `buyer_id` / `buyer_open_id` | String | 可选 | 128 | 买家支付宝用户号或买家支付宝 open_id。 | 新商户建议使用 `buyer_open_id` 替代 `buyer_id`。如使用 open_id,请确认“应用-开发配置-openid 配置管理”已启用。 | - | | `buyer_logon_id` | String | 可选 | 100 | 买家支付宝账号。 | - | 180****0062 | | `seller_id` | String | 可选 | 30 | 卖家支付宝用户号。 | - | 2088101106499364 | | `seller_email` | String | 可选 | 100 | 卖家支付宝账号。 | - | zhuzhanghu@alitest.com | | `trade_status` | String | 必选 | 32 | 交易状态,交易目前所处的状态。 | 取值见“交易状态说明”。 | TRADE_CLOSED | | `total_amount` | Number | 必选 | 11 | 订单金额,本次交易支付的订单金额,单位为元。 | 支持小数点后两位。 | 20 | | `receipt_amount` | Number | 必选 | 11 | 实收金额,商家在交易中实际收到的款项,单位为元。 | 支持小数点后两位。 | 15 | | `invoice_amount` | Number | 可选 | 11 | 开票金额,用户在交易中支付的可开发票金额。 | 支持小数点后两位。 | 10.00 | | `buyer_pay_amount` | Number | 可选 | 11 | 付款金额,用户在交易中支付的金额。 | 支持小数点后两位。 | 13.88 | | `point_amount` | Number | 可选 | 11 | 集分宝金额,使用集分宝支付的金额。 | 支持小数点后两位。 | 12.00 | | `refund_fee` | Number | 可选 | 11 | 总退款金额。退款通知中返回总退款金额,单位为元。 | 支持小数点后两位。 | 2.58 | | `send_back_fee` | Number | 可选 | 11 | 实际退款金额,商家实际退款给用户的金额,单位为元。 | 支持小数点后两位。 | 2.08 | | `subject` | String | 可选 | 256 | 订单标题,商品标题、交易标题、订单标题或订单关键字等。 | 对应请求时的参数,会在通知中原样返回。 | XXX交易 | | `body` | String | 可选 | 400 | 商品描述,订单备注、描述或明细等。 | 对应请求时的 `body` 参数,会在通知中原样返回。 | XXX交易内容 | | `passback_params` | String | 可选 | 512 | 公共回传参数。 | 如果请求时传递该参数,则异步通知会原样返回。本参数必须先进行 UrlEncode 后再发送给支付宝。 | - | | `gmt_create` | Date | 可选 | - | 交易创建时间,格式为 `yyyy-MM-dd HH:mm:ss`。 | - | 2015-04-27 15:45:57 | | `gmt_payment` | Date | 可选 | - | 交易付款时间,格式为 `yyyy-MM-dd HH:mm:ss`。 | - | 2015-04-27 15:45:57 | | `gmt_refund` | Date | 可选 | - | 交易退款时间,格式为 `yyyy-MM-dd HH:mm:ss.SS`。 | - | 2015-04-28 15:45:57.320 | | `gmt_close` | Date | 可选 | - | 交易结束时间,格式为 `yyyy-MM-dd HH:mm:ss`。 | - | 2015-04-29 15:45:57 | | `fund_bill_list` | String | 可选 | 512 | 支付金额信息,支付成功的各个渠道金额信息。 | 字段说明见“资金明细信息说明”。 | `[{"amount":"15.00","fundChannel":"ALIPAYACCOUNT"}]` | | `voucher_detail_list` | String | 可选 | - | 优惠券信息,本交易支付时所使用的所有优惠券信息。 | 字段说明见“优惠券信息说明”。 | `[{"amount":"0.20","merchantContribute":"0.00","name":"一键创建券模板的券名称","otherContribute":"0.20","type":"ALIPAY_BIZ_VOUCHER","memo":"学生8折优惠"}]` | #### 交易状态说明 | 枚举名称 | 枚举说明 | | --- | --- | | `WAIT_BUYER_PAY` | 交易创建,等待买家付款。 | | `TRADE_CLOSED` | 未付款交易超时关闭,或支付完成后全额退款。 | | `TRADE_SUCCESS` | 交易支付成功。 | | `TRADE_FINISHED` | 交易结束,不可退款。 | #### 通知触发条件 | 触发条件名 | 触发条件描述 | 触发条件默认值 | | --- | --- | --- | | `TRADE_FINISHED` | 交易完成 | `true`(触发通知) | | `TRADE_SUCCESS` | 支付成功 | `true`(触发通知) | | `TRADE_CLOSED` | 交易关闭 | `true`(触发通知) | | `WAIT_BUYER_PAY` | 交易创建 | `false`(不触发通知) | #### 资金明细信息说明 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `fundChannel` | String | 可选 | - | 支付渠道。 | 详情可查看[支付渠道说明](https://ideservice.alipay.com/cms/site/009zkj)。 | ALIPAYACCOUNT | | `amount` | String | 可选 | 11 | 支付金额,使用指定支付渠道支付的金额,单位为元。 | - | 15.00 | #### 优惠券信息说明 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `voucherId` | String | 必选 | 32 | 券 ID。 | - | 2015102600073002039000002D5O | | `templateId` | String | 可选 | 64 | 券模板 ID。 | - | 20171030000730015359000EMZP0 | | `name` | String | 必选 | 64 | 券名称。 | - | 5 元代金券 | | `type` | String | 必选 | 32 | 优惠类型。 | `ALIPAY_BIZ_VOUCHER`:商家全场券;`ALIPAY_COMMON_ITEM_VOUCHER`:商家单品券;`ALIPAY_CASH_VOUCHER`:平台优惠券,支付宝或第三方出资;`ALICREDIT_INTFREE_VOUCHER`:花呗分期券,仅做订单外的花呗分期费用减免,不抵扣订单内支付金额。未来可能新增其他类型,商家接入时应注意兼容,避免硬编码。 | ALIPAY_BIZ_VOUCHER | | `amount` | Number | 必选 | 11 | 优惠金额。 | 优惠金额中由商家出资的金额。 | 10.00 | | `merchantContribute` | Number | 可选 | 11 | 商家出资金额。 | 优惠金额中由商家出资的金额。 | 9.00 | | `otherContribute` | Number | 可选 | 11 | 其他出资方出资金额。 | 可能是支付宝、品牌商、其他方,或多方共同出资。 | 1.00 | | `otherContributeDetail` | ContributeDetail[] | 可选 | - | 优惠券的其他出资方明细。 | 子字段见下方 `otherContributeDetail[]`。 | - | | `otherContributeDetail[].contributeType` | String | 可选 | 32 | 出资方类型。 | 如品牌商出资、支付宝平台出资等。 | PLATFORM | | `otherContributeDetail[].contributeAmount` | Number | 可选 | 8 | 出资方金额。 | - | 0.18 | | `memo` | String | 可选 | 256 | 优惠券备注信息。 | - | 学生专用优惠 | #### 异步通知特性 1. 在进行异步通知交互时,如果支付宝收到的应答不是 `success`,支付宝会认为通知失败,并通过一定策略定期重新发起通知。通知间隔频率为:`4m`、`10m`、`10m`、`1h`、`2h`、`6h`、`15h`。 2. 商家设置的异步通知地址 `notify_url` 需保证无任何多余字符,如空格、HTML 标签,且不能重定向。若发生重定向,支付宝会收不到 `success` 字符,可能判定页面程序运行异常并重新发送通知。 3. 支付宝使用 POST 方式发送通知信息,商户可通过 `request.Form("out_trade_no")`、`$_POST['out_trade_no']` 等方式获取参数。 4. 支付宝针对同一条异步通知重试时,异步通知参数中的 `notify_id` 不变。 #### 异步返回结果验签 某商家设置的通知地址为 `https://api.xx.com/receive_notify.htm`,对应接收到通知的示例如下。 注意:以下示例报文仅供参考,实际返回的详细报文请以实际返回为准。 ```text https://api.xx.com/receive_notify.htm?gmt_payment=2015-06-11 22:33:59¬ify_id=42af7baacd1d3746cf7b56752b91edcj34&seller_email=testyufabu07@alipay.com¬ify_type=trade_status_sync&sign=kPbQIjX+xQc8F0/A6/AocELIjhhZnGbcBN6G4MM/HmfWL4ZiHM6fWl5NQhzXJusaklZ1LFuMo+lHQUELAYeugH8LYFvxnNajOvZhuxNFbN2LhF0l/KL8ANtj8oyPM4NN7Qft2kWJTDJUpQOzCzNnV9hDxh5AaT9FPqRS6ZKxnzM=&trade_no=2015061121001004400068549373&out_trade_no=21repl2ac2eOutTradeNo322&gmt_create=2015-06-11 22:33:46&seller_id=2088211521646673¬ify_time=2015-06-11 22:34:03&subject=FACE_TO_FACE_PAYMENT_PRECREATE中文&trade_status=TRADE_SUCCESS&sign_type=RSA2 ``` 验签步骤如下: 1. 在通知返回参数列表中,除去 `sign`、`sign_type` 两个参数外,通知返回的参数均为待验签参数。 2. 将剩余参数进行 `URLDecode`,然后按字典排序组成字符串,得到待签名字符串: ```text gmt_create=2015-06-11 22:33:46&gmt_payment=2015-06-11 22:33:59¬ify_id=42af7baacd1d3746cf7b56752b91edcj34¬ify_time=2015-06-11 22:34:03¬ify_type=trade_status_sync&out_trade_no=21repl2ac2eOutTradeNo322&seller_email=testyufabu07@alipay.com&seller_id=2088211521646673&subject=FACE_TO_FACE_PAYMENT_PRECREATE中文&trade_no=2015061121001004400068549373&trade_status=TRADE_SUCCESS ``` 3. 将签名参数 `sign` 使用 base64 解码为字节码串。 4. 使用 RSA 验签方法,通过签名字符串、签名参数(经过 base64 解码)及支付宝公钥验证签名。 5. 在步骤四验证签名正确后,必须再严格校验通知数据的正确性: | 校验项 | 校验说明 | | --- | --- | | `out_trade_no` | 校验通知数据中的 `out_trade_no` 是否为商家系统中创建的订单号。 | | `total_amount` | 判断 `total_amount` 是否确实为该订单的实际金额,即商家订单创建时的金额。 | | `seller_id` / `seller_email` | 校验通知中的 `seller_id` 或 `seller_email` 是否为 `out_trade_no` 这笔单据的对应操作方。 | | `app_id` | 验证 `app_id` 是否为该商家本身。 | 上述任一校验项不通过,则表明本次通知是异常通知,务必忽略。 上述校验通过后,商家必须根据支付宝不同类型的业务通知进行业务处理,并过滤重复通知结果数据。在支付宝的业务通知中,只有交易通知状态为 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 时,支付宝才会认定为买家付款成功。 SDK 接收以及验签示例代码如下。此处以 Java 语言为例,按照服务端 SDK 中提供的工具类,注意区分公钥和公钥证书验签代码。 ```java // 获取支付宝 POST 过来反馈信息,将异步通知中收到的待验证所有参数都存放到 map 中。 Map params = new HashMap(); Map requestParams = request.getParameterMap(); for (Iterator iter = requestParams.keySet().iterator(); iter.hasNext();) { String name = (String) iter.next(); String[] values = (String[]) requestParams.get(name); String valueStr = ""; for (int i = 0; i < values.length; i++) { valueStr = (i == values.length - 1) ? valueStr + values[i] : valueStr + values[i] + ","; } // 乱码解决,这段代码在出现乱码时使用。 // valueStr = new String(valueStr.getBytes("ISO-8859-1"), "utf-8"); params.put(name, valueStr); } // 调用 SDK 验证签名。 // 公钥验签示例代码: boolean signVerified = AlipaySignature.rsaCheckV1(params, ALIPAY_PUBLIC_KEY, CHARSET, sign_type); // 公钥证书验签示例代码: // boolean flag = AlipaySignature.rsaCertCheckV1(params, alipayPublicCertPath, "UTF-8", "RSA2"); if (signVerified) { // TODO 验签成功后,按照支付结果异步通知中的描述,对支付结果中的业务内容进行 1/2/3/4 二次校验。 // 校验成功后在 response 中返回 success。 } else { // TODO 验签失败则记录异常日志,并在 response 中返回 fail。 } ``` 注意: - 状态 `TRADE_SUCCESS` 的通知触发条件是:商家开通的产品支持退款功能的前提下,买家付款成功。 - 交易状态 `TRADE_FINISHED` 的通知触发条件是:商家开通的产品不支持退款功能的前提下,买家付款成功;或者商家开通的产品支持退款功能的前提下,交易已经成功并且已经超过可退款期限。 #### 响应值 | 响应值 | 描述 | 异步是否重试发送 | | --- | --- | --- | | `fail` | 消息获取失败 | 重试 | | `success` | 消息获取成功 | 不重试 | #### 异步通知触发时机和通知参数说明 注意:如果签约不支持退款,或者定制了异步通知的触发条件和通知字段,则本节说明不适用。 在交易支付成功、交易关单、交易退款、交易分账等场景下都可能触发异步通知。各场景的关键通知参数区分如下: | 场景 | 通知参数特征 | | --- | --- | | 用户支付成功通知 | `trade_status=TRADE_SUCCESS`,且不包含 `out_biz_no` 字段。 | | 退款成功通知 | 通知参数包含 `gmt_refund`、`refund_fee`、`out_biz_no` 字段,其中 `out_biz_no` 为退款请求号。 | | 交易未支付超时关单通知 | 通知参数包含 `gmt_close`、`refund_fee` 字段,其中 `refund_fee=0`、`trade_status=TRADE_CLOSED`。如果用户在收银台没有点击过提交支付,则不会真正创建交易,该场景下不会有未支付超时关单通知。 | | 交易分账成功通知 | 通知参数包含 `out_biz_no` 字段,其中 `out_biz_no` 为分账请求号。 | --- ### 产品接入指南 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > 产品接入指南 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/app-pay-integration-guide-new.md AI移动应用收款产品接入指南 #### 适用场景 适用于在商家移动端 App 内使用支付宝支付功能的场景。 ![](https://cdn.nlark.com/yuque/0/2022/png/179989/1671676185011-25d58e3a-65ba-42a5-bd86-2270db7bb98c.png) #### Agent快速接入(推荐) ```markdown 通过 npx -y @alipay/alipay-aipay@latest install 安装支付宝 AI 付 Skill,加载 alipay-aipay 技能为我的APP 集成支付宝支付,完成沙箱测试,并完成签约入驻 ``` #### 手动接入 ##### 整体流程 ```mermaid sequenceDiagram participant 用户 participant 商户APP participant 商户服务端 participant 支付宝 Note over 用户,支付宝: 支付(必选) 用户->>商户APP: 1.1 下单 商户APP->>商户服务端: 1.2 请求生成订单 商户服务端->>商户服务端: 1.3 [alipay.trade.app.pay]生成 orderStr 商户服务端-->>商户APP: 1.4 返回 orderStr 商户APP->>支付宝: 1.5 发起支付 alt 异常 支付宝-->>用户: 1.6 展示异常 支付宝-->>商户APP: 1.7 返回异常 else 正常 支付宝-->>用户: 1.6 唤起收银台 用户->>支付宝: 1.7 输入密码确认支付 支付宝->>支付宝: 1.8 创建并推进交易 支付宝-->>商户APP: 1.9 返回支付结果 商户APP->>商户APP: 1.10 展示结果 支付宝-->>商户服务端: 1.11 异步通知 商户服务端->>商户服务端: 1.12 处理通知 商户服务端->>支付宝: 1.13 查询订单 支付宝-->>商户服务端: 1.14 返回订单信息 end Note over 用户,支付宝: 退款(可选) 用户->>商户APP: 2.1 申请退款 商户APP->>商户服务端: 2.2 请求退款 商户服务端->>支付宝: 2.3 发起退款 支付宝-->>商户服务端: 2.4 返回退款结果 支付宝-->>商户服务端: 2.5 交易状态变更通知 ``` 以下对重点步骤做简要说明: + 第 1.1 步用户在商户 App 客户端中购买商品下单。 + 第 1.2 步商户订单信息由商户 App 客户端发送到服务端。 + 第 1.3 步商家服务端调用 [alipay.trade.app.pay(App 支付接口 2.0 接口)](),通过支付宝服务端 SDK 获取 `orderStr`(`orderStr` 中包含了订单信息和签名)。 + 第 1.4 步商家将 `orderStr` 发送给商户 App 客户端。 + 第 1.5 步商家在客户端发起请求,将 `orderStr` 发送给支付宝。 + 第 1.6 步支付宝进行支付预下单。正常场景下,会唤起支付宝收银台等待用户核身;异常场景下,会返回异常信息。 + 第 1.9 步返回商家 App:用户在支付宝完成支付后,会跳转回商家页面,并返回最终的支付结果(即同步通知),可查看 [同步通知说明]()。 + 第 1.11 步支付结果异步通知,支付宝会根据步骤 1.3 传入的异步通知地址 `notify_url` 发送异步通知,可查看 [异步通知说明]()。 除了正向支付流程外,支付宝也提供交易查询、关闭、退款、退款查询以及对账等配套 API。 ##### 重要说明 1. 首先确认已完成开通产品、配置密钥等步骤,详情可查看产品一站式接入流程。 2. 构造交易数据并签名必须在商家服务端完成,商家的应用私钥绝对不能保存在商家 APP 客户端中,也不能从服务端下发。 3. 服务端生成的 `orderStr` 只是加签数据,并未请求到支付宝,只有客户端请求后,支付宝才会收到商户的订单信息。 4. 同步返回的数据,只是一个简单的结果通知,商家确定该笔交易付款是否成功需要依赖服务端收到支付宝异步通知的结果进行判断,建议通过异步+查询方式判断避免错失异步漏失交易信息。 5. 商家系统接收到通知以后,必须通过验签(验证通知中的 sign 参数)来确保支付通知是由支付宝发送的。建议使用支付宝提供的 SDK 来完成,详细验签规则可查看 [异步通知说明]() 的 **异步返回结果验签**。 6. **订单创建时间**:支付宝订单将在用户输入正确完整的支付密码后创建,并非唤起收银台时创建(余额不足等情况会导致交易处于订单创建等待支付状态)。 7. **订单支付超时时间**:订单创建后未支付,默认最晚付款时间为 15 天,若超过第 15 天当天 24 点订单超时关闭不可支付(超时参数设置范围 5min~15d)。 8. 异步或查询接口返回的 `trade_status`(交易状态)为 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 时,支付宝才会认定为买家付款成功。 9. 由于网络异常等原因,可能会导致用户支付成功,但是商户侧未能成功接收到支付结果异步通知。因此当商家未收到支付结果通知时,必须要调用 `alipay.trade.query`(统一收单交易查询接口)来获取支付结果。 10. **判断退款成功**:退款接口返回 `fund_change=Y` 或者退款查询接口返回 `refund_status=REFUND_SUCCESS`。 **注意**:`fund_change` 只表示本次接口请求是否资金变动,不是指该笔交易是否资金变动。如果第一次退款成功,返回 `Y`,但是相同参数(如 `out_request_no` 不变)第二次请求则会返回 `N`,因此当 `fund_change=N` 时,建议通过退款查询接口进一步判断。 ##### 交易状态流程 ```mermaid flowchart TB START["下单唤起支付宝支付"] WAIT{"创建交易
WAIT_BUYER_PAY
创建交易,等待买家付款"} SUCCESS["交易成功
TRADE_SUCCESS
交易成功,可退款"] FINISHED["交易完成
TRADE_FINISHED
交易结束,不可退款"] CLOSED["交易关闭
TRADE_CLOSED
未付款交易超时关闭,
或支付完成后全额退款"] START --> WAIT WAIT -- "① 买家付款成功" --> SUCCESS SUCCESS -- "② 退款期结束" --> FINISHED SUCCESS -- "③ 部分退款" --> SUCCESS SUCCESS -- "④ 全额退款" --> CLOSED WAIT -- "⑤ 未付款超时关闭" --> CLOSED WAIT -- "⑥ 支付成功且不可退款" --> FINISHED ``` 随着订单支付成功、退款、关闭等操作,订单交易的每一个环节 `trade_status`(交易状态)也不同。 1. 交易创建成功后,用户支付成功,交易状态转为 **`TRADE_SUCCESS`(交易成功)**。 2. 交易成功后,规定退款时间内没有退款,交易状态转为 **`TRADE_FINISHED`(交易完成)**。 3. 交易支付成功后,交易部分退款,交易状态仍为 **`TRADE_SUCCESS`(交易成功)**。 4. 交易成功后,交易全额退款,交易状态转为 **`TRADE_CLOSED`(交易关闭)**。 5. 交易创建成功后,用户未付款交易超时关闭,交易状态转为 **`TRADE_CLOSED`(交易关闭)**。 6. 交易创建成功后,用户支付成功后,若用户商品不支持退款,交易状态直接转为 **`TRADE_FINISHED`(交易完成)**。 **注意**:交易成功后部分退款,交易状态仍为 `TRADE_SUCCESS`(交易成功)。 如果一直部分退款退完所有交易金额则交易状态转为 `TRADE_CLOSED`(交易关闭)。 如果未退完所有交易金额,超过有效退款时间后交易状态转为 `TRADE_FINISHED`(交易完成)不可退款。 ##### 支付流程 ###### 服务端接入:获取orderStr 示例代码、参数说明及错误码等信息,可查看 [alipay.trade.app.pay(App 支付接口 2.0 接口)]() 接口文档。 `orderStr` 示例代码: ```text alipay_sdk=alipay-sdk-java-dynamicVersionNo&app_id=2014100900010000&biz_content=%7B%22total_amount%22%3A%220.01%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22subject%22%3A%22%E5%93%88%E5%93%88%E5%93%88%E5%93%88%E5%93%88%E5%A4%A7%E4%B9%90%E9%80%8F%22%2C%22out_trade_no%22%3A%2220220530000000011111101%22%7D&charset=utf-8&format=json&method=alipay.trade.app.pay&sign=iuO%2FTso2zr236p%2F%2FgyVoM9B7JGhyQqHHlL82siLLPI90xUruDVRt8hIOAroNid%2FTCbYUENSV4FkIZ5krrXm1qDFLHUnvtsUA3kToEojxyKilR8czZFYm6w91oxJseFZQJe0Os6IJg8oG29tYRf9TiXjB0leSwGQ3Ax8VilW2ATsne9L4A9Xah5fz7PTlKURTMYFqU166J2RH769wtTOjOb5Gs74aSdB3ymlZ486%2FGAcFwyXSvd3i8FEzsx3obLaM3oRQGQ%2Fx2jn8aL5qH3nVkGFIKA4xAUOZAaZSrj4EFw17HPFBYvcPwG55DQlmyLluh5lb4Ibi3j1ZxR4NiB0YFQ%3D%3D&sign_type=RSA2×tamp=2022-05-30+17%3A43%3A28&version=1.0 ``` ###### 客户端接入 ::::aipay-tabs{defaultActiveKey="iOS"} :::aipay-tab{key="iOS" title="iOS"} **安装 SDK:** ```ruby # Podfile pod 'AlipaySDK-iOS' ``` **在支付订单页提前注册 AppID(非强依赖,但能加快唤起速度):** ```objc #import // 建议在进入支付订单页时调用,不是在点击付款按钮时 [[AlipaySDK defaultService] registerApp:@"你的APPID" universalLink:@"你的Universal Link"]; ``` **点击付款按钮时:** ```objc // 第一步:请求你的服务端,拿到 orderStr // (省略网络请求代码,用你项目中已有的网络库实现) NSString *orderStr = [从服务端返回的结果中取出]; // 第二步:把 orderStr 传给支付宝 SDK,唤起收银台 NSString *appScheme = @"你的AppScheme"; // 在 Info.plist > URL Types 中注册 [[AlipaySDK defaultService] payOrder:orderStr fromScheme:appScheme callback:^(NSDictionary *resultDic) { // 第六步:收到同步回调(用户在支付宝完成操作后跳回你的 App) NSString *resultStatus = resultDic[@"resultStatus"]; [self handlePayResult:resultStatus result:resultDic[@"result"]]; }]; ``` **在 AppDelegate 中配置回调处理(必须实现,否则已安装支付宝的场景结果无法回传):** ```objc // iOS 9.0+ - (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options { if ([url.host isEqualToString:@"safepay"]) { [[AlipaySDK defaultService] processOrderWithPaymentResult:url standbyCallback:^(NSDictionary *resultDic) { // 同上,处理支付结果 NSString *resultStatus = resultDic[@"resultStatus"]; [self handlePayResult:resultStatus result:resultDic[@"result"]]; }]; } return YES; } ``` **Info.plist 配置:** 在 URL Types 中添加你的 App Scheme,并在 LSApplicationQueriesSchemes 中添加 `alipay`,用于检测是否安装了支付宝 App。 ::: :::aipay-tab{key="Android" title="Android"} **添加 SDK 依赖(在 app/build.gradle 中):** ```gradle // 将支付宝提供的 aar 文件放入 libs 目录 implementation fileTree(dir: 'libs', include: ['*.aar']) ``` **在 AndroidManifest.xml 中声明必要的 Activity(缺少则 H5 支付无法唤起):** ```xml ``` **点击付款按钮时(需在子线程中执行,避免阻塞 UI):** ```java // 第一步:请求你的服务端,拿到 orderStr String orderStr = 从服务端拿到的结果; // 第二步:在子线程中调用支付宝 SDK new Thread(() -> { PayTask alipay = new PayTask(activity); Map result = alipay.payV2(orderStr, true); // 回到主线程处理结果 runOnUiThread(() -> { String resultStatus = result.get("resultStatus"); handlePayResult(resultStatus, result.get("result")); }); }).start(); ``` ::: :::aipay-tab{key="Harmony" title="Harmony"} ```bash ohpm install @cashier_alipay/cashiersdk ``` 在 `module.json5` 中配置: ```json "module": { "querySchemes": ["https"] // SDK >= 15.8.29 } ``` **点击付款按钮时:** ```typescript import { Pay } from '@cashier_alipay/cashiersdk'; // 第一步:请求你的服务端,拿到 orderStr const orderStr = await fetchOrderStrFromServer(); // 第二步:调用支付宝 SDK new Pay().pay(orderStr, true) .then((result) => { const resultStatus = result.get('resultStatus'); handlePayResult(resultStatus); }) .catch((error: BusinessError) => { console.error(error.message); }); ``` ::: :::: ###### 异步通知 App 支付异步通知发送到 [alipay.trade.app.pay(App 支付接口 2.0 接口)]() 加签时入参的公共参数 `notify_url` 地址中,未设置该参数则不触发异步。通知参数及规则详见 [异步通知说明]()。 **注意**:由于网络异常等原因,可能会导致用户支付成功,但是商户侧未能成功接收到支付结果异步通知。因此当商家未收到支付结果通知时,必须要调用 alipay.trade.query(统一收单交易查询接口)来获取支付结果。 ###### 支付结果查询 商家可调用 [alipay.trade.query(统一收单交易查询接口)](),通过商家网站唯一订单号 out_trade_no 或支付宝交易号 trade_no 查询对应订单支付情况。 ###### 重要入参说明 **注意:** 请严格按照接口文档中的参数入参,传入非接口文档中的参数是无效的,并且可能会导致请求被拦截或其它异常。 | 参数名 | 参数说明 | | --- | --- | | `out_trade_no` | 支付时传入的商户订单号,与 `trade_no` 必填一个。 | | `trade_no` | 支付时返回的支付宝交易号,与 `out_trade_no` 必填一个。 | ##### 退款流程 交易发生后的一段时间内,由于业务原因(如金额错误、用户退款或者对账不平等)需要退款时,商家可以调用 [alipay.trade.refund(统一收单交易退款接口)](),通过 `out_trade_no`(商家网站唯一订单号)或 `trade_no`(支付宝交易号),将对应订单支付款退还给买家。支付宝将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家账号上。 **说明:** 支持全额或部分退款。 ###### 接口流程 ```mermaid sequenceDiagram participant 商户服务端 participant 支付宝服务端 商户服务端->>支付宝服务端: 1. 调用 alipay.trade.refund 接口发起退款请求 支付宝服务端-->>商户服务端: 2. 返回退款结果 ``` ###### 退款结果 + **退款成功**:退款是否成功可以根据同步响应的 `fund_change` 参数来判断,返回值为 `Y` 则表示退款成功。 + **退款失败**:根据 [alipay.trade.refund(统一收单交易退款接口)]()中的错误码确认是否要重试,重试时注意 `out_request_no` 需保持一致。 + **系统异常**:无法确认退款结果。 - 方案一:重试,重试时注意 `out_request_no` 需保持一致。 - 方案二:先调用 [alipay.trade.fastpay.refund.query(统一收单交易退款查询接口)]()确认退款结果,如失败,再发起重试。 ###### 退款说明 + **退款周期:** 默认12 个月,即交易发生后 12 个月内可发起退款,超过 12 个月则不可发起退款。 + **退款方式:** 资金原路返回用户账号。 + **退款退费:** 默认退款时手续费不退回。 + 支付渠道为花呗、余额等退款即时到账。 + 银行卡的退款时间以银行退款时间为准,一般情况下 2 小时内可到账(若退款到卡失败,退款金额会退回用户支付宝账户余额)。 + 商家可以在 [商家平台 > 对账中心 > 交易订单](https://b.alipay.com/page/mbillexprod/trade/order/sold) 中退款。 + 退款接口会根据外部请求号 `out_request_no` 幂等返回,因此同一笔交易需要多次部分退款时,必须使用不同的 `out_request_no`。 **子章节:** 重要入参说明 章节路径:手动接入 > 退款流程 > 退款说明 > 重要入参说明 **注意:** 请严格按照接口文档中的参数入参,传入非接口文档中的参数是无效的,并且可能会导致请求被拦截或其它异常。 | 参数名 | 参数说明 | | --- | --- | | `out_trade_no` | 支付时传入的商户订单号,与 `trade_no` 必填一个。 | | `trade_no` | 支付时返回的支付宝交易号,与 `out_trade_no` 必填一个。 | | `out_request_no` | 本次退款请求流水号,部分退款时必传。 | | `refund_amount` | 本次退款金额。 | **子章节:** 重要出参说明 章节路径:手动接入 > 退款流程 > 退款说明 > 重要出参说明 | 参数名 | 参数说明 | | --- | --- | | `refund_fee` | 该笔交易已退款的总金额。 | ###### 查询退款结果 商家/服务商可调用 [alipay.trade.fastpay.refund.query(统一收单交易退款查询接口)]() 查询对应 `out_request_no`(退款请求号)的退款情况。 **重要说明** 1. 退款查询接口的 `trade_no`、`out_trade_no`、`out_request_no` 必须和退款接口保持一致,否则交易号一致、`out_request_no` 不同,只会返回 `10000`、`success`,但是没有具体的退款信息。 2. 该接口的返回 `10000` 仅代表本次查询操作成功,不代表退款成功;当接口返回的 `refund_status` 值为 `REFUND_SUCCESS` 时表示退款成功,否则表示退款没有执行成功。 **子章节:** 重要入参说明 章节路径:手动接入 > 退款流程 > 查询退款结果 > 重要入参说明 **注意:** 请严格按照接口文档中的参数入参,传入非接口文档中的参数是无效的,并且可能会导致请求被拦截或其它异常。 | 参数名 | 参数说明 | | --- | --- | | `out_trade_no` | 支付时传入的商户订单号,与 `trade_no` 必填一个。 | | `trade_no` | 支付时返回的支付宝交易号,与 `out_trade_no` 必填一个。 | ##### 对账流程(可选) 目前支付宝对外的常用对账方式有两种: + 一种是通过在 [商家平台 > 对账中心](https://mbillexprod.alipay.com/enterprise/mainIndex.htm#/) 下载账单的方式来对账。 + 一种是通过调用接口的方式来实现对账,下文介绍如何通过接口获取对账单下载链接。更多后台下载及账单示例图详情可查看 [对账说明](https://opendocs.alipay.com/open/00dn7a?referPath=01dcc0_cf89b2be)。 商家可通过接口下载指定日期(当天除外)的业务明细账单文件,并结合自身业务系统实现自动对账。 ###### 接口流程 ```mermaid sequenceDiagram participant 商户服务端 participant 支付宝服务端 商户服务端->>支付宝服务端: 1. 调用 alipay.data.dataservice.bill.downloadurl.query 接口 支付宝服务端-->>商户服务端: 2. 返回对账单下载地址 商户服务端->>支付宝服务端: 3. 通过 HTTP 请求对账单下载地址 支付宝服务端-->>商户服务端: 4.获得对账单文件流 商户服务端->>商户服务端: 5. 读取文件流处理 CSV 文件自动对账,或保存至本地 ``` 1. 商家系统调用 [alipay.data.dataservice.bill.downloadurl.query(查询对账单下载地址接口)](),传入指定日期,获得该日期账单文件的下载地址。 2. 商家系统通过 HTTP 方式后台访问账单下载链接,将账单 CSV 文件下载到本地后自行处理。注意该下载链接仅 30 秒,在得到链接后系统需要立刻下载账单文件。 ###### 重要入参说明 **注意:**请严格按照接口文档中的参数入参,传入非接口文档中的参数是无效的,并且可能会导致请求被拦截或其它异常。 | 参数名 | 参数说明 | | --- | --- | | `bill_type` | 固定传入 `trade`。 | | `bill_date` | 需要下载的账单日期,最晚是当期日期的前一天。 | ###### 下载账单文件示例代码 ```java //将接口返回的对账单下载地址传入urlStr String urlStr = "下载地址"; //指定希望保存的文件路径 String filePath = "/Users/fund_bill_20160405.csv.zip"; URL url = null; HttpURLConnection httpUrlConnection = null; InputStream fis = null; FileOutputStream fos = null; try { url = new URL(urlStr); httpUrlConnection = (HttpURLConnection) url.openConnection(); httpUrlConnection.setConnectTimeout(5 * 1000); httpUrlConnection.setDoInput(true); httpUrlConnection.setDoOutput(true); httpUrlConnection.setUseCaches(false); httpUrlConnection.setRequestMethod("GET"); httpUrlConnection.setRequestProperty("CHARSET", "UTF-8"); httpUrlConnection.connect(); fis = httpUrlConnection.getInputStream(); byte[] temp = new byte[1024]; int b; fos = new FileOutputStream(new File(filePath)); while ((b = fis.read(temp)) != -1) { fos.write(temp, 0, b); fos.flush(); } } catch (MalformedURLException e) { e.printStackTrace(); } catch (IOException e) { e.printStackTrace(); } finally { try { if(fis!=null) fis.close(); if(fos!=null) fos.close(); if(httpUrlConnection!=null) httpUrlConnection.disconnect(); } catch (IOException e) { e.printStackTrace(); } } ``` ##### 附录:自定义参数说明 1. 商家在请求参数中自己附加的一些额外参数,**请勿和支付宝系统中约定的 key**(如 `alipay.trade.app.pay`(App 支付接口 2.0)等接口 **公共请求参数**/**请求参数**)**重名**,否则将可能导致未知的异常。 1. 例如以下示例中 `app_id=2014072300007148&version=1.0&biz_content` 的 key 是公共请求参数,商家/服务商自己的扩展参数需要放在 `biz_content` 内部,例如示例中 `tips` 属性。下面 `total_amount` 属性是商家按照自己的业务属性赋值的,但是由于 `total_amount` 同时也是支付宝关键 key,支付宝将会认为这个 `total_amount` 是支付宝业务的参数应该是金额,这个最终将导致误解析。 2. **注意:**下列请求串为了展示清晰,未进行 encode 并且做了格式化处理。 ```text app_id=2014072300007148&charset=UTF-8&version=1.0×tamp=2016-07-01 08:08:08&method=alipay.trade.app.pay¬ify_url=https://api.**.com/pay_receive_notify.html&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&biz_content= { "body":"对一笔交易的具体描述信息。如果是多种商品,请将商品描述字符串累加传给body。", "subject":"大乐透", "out_trade_no":"70501111111S001111119", "timeout_express":"90m", "total_amount":"一共花费了10元", "product_code":"QUICK_MSECURITY_PAY", "tips":"测试一笔支付" } ``` 2. 商家的请求参数中,所有的 key(支付宝关键 key 或者商家自己的 key),其对应的 value 中都不应该出现支付宝关键 key,否则该类交易将可能被支付宝拦截禁止支付。 1. 例如以下的请求中 `"subject":"大乐透 这个辣条不错 out_trade_no=123 total_fee=123.5"`,其 value 值中有支付宝关键 key 值 `out_trade_no`、`total_fee`,这样的业务请求参数支付宝将会拦截。 2. **注意:** 下列请求串为了展示清晰,未进行 encode 并且做了格式化处理。 ```text app_id=2014072300007148&charset=UTF-8&version=1.0×tamp=2016-07-01 08:08:08&method=alipay.trade.app.pay¬ify_url=https://api.**.com/pay_receive_notify.htm&sign_type=RSA2&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&version=1.0&biz_content= { "body":"对一笔交易的具体描述信息。如果是多种商品,请将商品描述字符串累加传给body。", "subject":"大乐透 这个辣条不错 out_trade_no=123 total_fee=123.5", "out_trade_no":"70501111111S001111119", "timeout_express":"90m", "total_amount":10.0, "product_code":"QUICK_MSECURITY_PAY" } ``` 3. 商家支付请求参数的安全注意点 1. 请求参数的 `sign` 字段请务必在服务端完成签名生成(不要在客户端本地签名)。 2. 支付请求中的 `total_amount`(订单金额) ,请务必依赖服务端,不要轻信客户端上行的数据(客户端本地上行数据在用户手机环境中无法确保一定安全)。 --- ### 统一收单APP支付接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > API列表 > 统一收单APP支付接口 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-app-pay.md 外部商户 App 可通过该接口唤起快捷 SDK 创建订单并支付 #### 接口说明 接口名称:`alipay.trade.app.pay` 该接口用于生成可信签名字符串 `orderStr`。可信签名串中包含业务参数及商户身份信息,可防止数据被篡改,一般用于打开支付宝客户端。 外部商户 App 可通过该接口唤起快捷 SDK 创建订单并支付。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.app.pay` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `notify_url` | String | 可选 | 256 | 支付宝服务器主动通知商户服务器里指定页面的 HTTP/HTTPS 路径 | `http://api.test.alipay.net/atinterface/receive_notify.htm` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_trade_no` | string | 必选 | 64 | 商户网站唯一订单号 | 由商家自定义,仅支持字母、数字、下划线,需保证在商户端不重复 | `70501111111S001111119` | | `total_amount` | string | 必选 | 9 | 订单总金额,单位为元,精确到小数点后两位 | 取值范围 `[0.01,100000000]`,金额不能为 0 | `9.00` | | `subject` | string | 必选 | 256 | 订单标题 | 不可使用特殊字符,如 `/`、`=`、`&` 等 | `大乐透` | | `product_code` | string | 可选 | 64 | 销售产品码,商家和支付宝签约的产品码 | App 支付常用值为 `QUICK_MSECURITY_PAY` | `QUICK_MSECURITY_PAY` | | `goods_detail` | GoodsDetail[] | 可选 | - | 订单包含的商品列表信息,JSON 格式 | 其他说明详见商品明细说明 | - | | `goods_detail[].goods_id` | string | 必选 | 32 | 商品编号 | - | `apple-01` | | `goods_detail[].goods_name` | string | 必选 | 256 | 商品名称 | - | `ipad` | | `goods_detail[].quantity` | number | 必选 | 32 | 商品数量 | - | `1` | | `goods_detail[].price` | price | 必选 | 9 | 商品单价,单位为元 | - | `2000` | | `goods_detail[].alipay_goods_id` | string | 可选 | 32 | 支付宝定义的统一商品编号 | - | `20010001` | | `goods_detail[].goods_category` | string | 可选 | 24 | 商品类目 | - | `34543238` | | `goods_detail[].categories_tree` | string | 可选 | 128 | 商品类目树 | 从商品类目根节点到叶子节点的类目 ID 组成,类目 ID 值使用 `|` 分割 | `124868003\|126232002\|126252004` | | `goods_detail[].show_url` | string | 可选 | 400 | 商品的展示地址 | - | `http://www.alipay.com/xxx.jpg` | | `time_expire` | string | 可选 | 32 | 绝对超时时间 | 格式为 `yyyy-MM-dd HH:mm:ss` | `2016-12-31 10:05:00` | | `extend_params` | ExtendParams | 可选 | - | 业务扩展参数 | - | - | #### 请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeAppPayRequest; import com.alipay.api.domain.ExtUserInfo; import com.alipay.api.domain.AlipayTradeAppPayModel; import com.alipay.api.response.AlipayTradeAppPayResponse; import com.alipay.api.domain.ExtendParams; import com.alipay.api.domain.GoodsDetail; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeAppPay { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeAppPayRequest request = new AlipayTradeAppPayRequest(); AlipayTradeAppPayModel model = new AlipayTradeAppPayModel(); // 设置商户订单号 model.setOutTradeNo("70501111111S001111119"); // 设置订单总金额 model.setTotalAmount("9.00"); // 设置订单标题 model.setSubject("大乐透"); // 设置产品码 model.setProductCode("QUICK_MSECURITY_PAY"); // 设置订单包含的商品列表信息 List goodsDetail = new ArrayList(); GoodsDetail goodsDetail0 = new GoodsDetail(); goodsDetail0.setGoodsName("ipad"); goodsDetail0.setAlipayGoodsId("20010001"); goodsDetail0.setQuantity(1L); goodsDetail0.setPrice("2000"); goodsDetail0.setGoodsId("apple-01"); goodsDetail0.setGoodsCategory("34543238"); goodsDetail0.setCategoriesTree("124868003|126232002|126252004"); goodsDetail0.setShowUrl("http://www.alipay.com/xxx.jpg"); goodsDetail.add(goodsDetail0); model.setGoodsDetail(goodsDetail); // 设置订单绝对超时时间 model.setTimeExpire("2016-12-31 10:05:00"); // 设置业务扩展参数 ExtendParams extendParams = new ExtendParams(); extendParams.setSysServiceProviderId("2088511833207846"); extendParams.setHbFqSellerPercent("100"); extendParams.setHbFqNum("3"); extendParams.setIndustryRefluxInfo("{\"scene_code\":\"metro_tradeorder\",\"channel\":\"xxxx\",\"scene_data\":{\"asset_name\":\"ALIPAY\"}}"); extendParams.setRoyaltyFreeze("true"); extendParams.setCardType("S0JP0000"); model.setExtendParams(extendParams); // 设置公用回传参数 model.setPassbackParams("merchantBizType%3d3C%26merchantBizNo%3d2016010101111"); // 设置商户的原始订单号 model.setMerchantOrderNo("20161008001"); // 设置外部指定买家 ExtUserInfo extUserInfo = new ExtUserInfo(); extUserInfo.setCertType("IDENTITY_CARD"); extUserInfo.setCertNo("362334768769238881"); extUserInfo.setMobile("16587658765"); extUserInfo.setName("李明"); extUserInfo.setMinAge("18"); extUserInfo.setNeedCheckInfo("F"); extUserInfo.setIdentityHash("27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc"); model.setExtUserInfo(extUserInfo); // 设置通知参数选项 List queryOptions = new ArrayList(); queryOptions.add("hyb_amount"); queryOptions.add("enterprise_pay_info"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeAppPayResponse response = alipayClient.sdkExecute(request); String orderStr = response.getBody(); System.out.println(orderStr); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeAppPay { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeAppPayRequest request = new AlipayTradeAppPayRequest(); AlipayTradeAppPayModel model = new AlipayTradeAppPayModel(); // 设置商户订单号 model.OutTradeNo = "70501111111S001111119"; // 设置订单总金额 model.TotalAmount = "9.00"; // 设置订单标题 model.Subject = "大乐透"; // 设置产品码 model.ProductCode = "QUICK_MSECURITY_PAY"; // 设置订单包含的商品列表信息 List goodsDetail = new List(); GoodsDetail goodsDetail0 = new GoodsDetail(); goodsDetail0.GoodsName = "ipad"; goodsDetail0.AlipayGoodsId = "20010001"; goodsDetail0.Quantity = 1; goodsDetail0.Price = "2000"; goodsDetail0.GoodsId = "apple-01"; goodsDetail0.GoodsCategory = "34543238"; goodsDetail0.CategoriesTree = "124868003|126232002|126252004"; goodsDetail0.ShowUrl = "http://www.alipay.com/xxx.jpg"; goodsDetail.Add(goodsDetail0); model.GoodsDetail = goodsDetail; // 设置订单绝对超时时间 model.TimeExpire = "2016-12-31 10:05:00"; // 设置业务扩展参数 ExtendParams extendParams = new ExtendParams(); extendParams.SysServiceProviderId = "2088511833207846"; extendParams.HbFqSellerPercent = "100"; extendParams.HbFqNum = "3"; extendParams.IndustryRefluxInfo = "{\"scene_code\":\"metro_tradeorder\",\"channel\":\"xxxx\",\"scene_data\":{\"asset_name\":\"ALIPAY\"}}"; extendParams.RoyaltyFreeze = "true"; extendParams.CardType = "S0JP0000"; model.ExtendParams = extendParams; // 设置公用回传参数 model.PassbackParams = "merchantBizType%3d3C%26merchantBizNo%3d2016010101111"; // 设置商户的原始订单号 model.MerchantOrderNo = "20161008001"; // 设置外部指定买家 ExtUserInfo extUserInfo = new ExtUserInfo(); extUserInfo.CertType = "IDENTITY_CARD"; extUserInfo.CertNo = "362334768769238881"; extUserInfo.Mobile = "16587658765"; extUserInfo.Name = "李明"; extUserInfo.MinAge = "18"; extUserInfo.NeedCheckInfo = "F"; extUserInfo.IdentityHash = "27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc"; model.ExtUserInfo = extUserInfo; // 设置通知参数选项 List queryOptions = new List(); queryOptions.Add("hyb_amount"); queryOptions.Add("enterprise_pay_info"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeAppPayResponse response = alipayClient.SdkExecute(request); string orderStr = response.Body; Console.WriteLine(orderStr); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $orderStr = $alipayClient->sdkExecute($request, "<-- 请填写应用授权令牌 -->"); echo $orderStr; function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.sdkExec("alipay.trade.app.pay", { bizContent: { out_trade_no: "70501111111S001111119", total_amount: "9.00", subject: "大乐透", product_code: "QUICK_MSECURITY_PAY", goods_detail: [ { goods_name: "ipad", alipay_goods_id: "20010001", quantity: 1, price: "2000", goods_id: "apple-01", goods_category: "34543238", categories_tree: "124868003|126232002|126252004", show_url: "http://www.alipay.com/xxx.jpg", }, ], time_expire: "2016-12-31+10:05:00", extend_params: { sys_service_provider_id: "2088511833207846", hb_fq_seller_percent: "100", hb_fq_num: "3", industry_reflux_info: '{\\"scene_code\\":\\"metro_tradeorder\\",\\"channel\\":\\"xxxx\\",\\"scene_data\\":{\\"asset_name\\":\\"ALIPAY\\"}}', royalty_freeze: "true", card_type: "S0JP0000", }, passback_params: "merchantBizType%3d3C%26merchantBizNo%3d2016010101111", merchant_order_no: "20161008001", ext_user_info: { cert_type: "IDENTITY_CARD", cert_no: "362334768769238881", mobile: "16587658765", name: "李明", min_age: "18", need_check_info: "F", identity_hash: "27bfcd1dee4f22c8fe8a2374af9b660419d1361b1c207e9b41a754a113f38fcc", }, query_options: ["hyb_amount", "enterprise_pay_info"], }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | ACQ.TRADE_HAS_SUCCESS | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | 交易已被支付 | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `orderStr` | string | 必选 | 16384 | 签名字符串。获取签名后的业务数据,具体使用方法请参考[接入指南](https://ideservice.alipay.com/cms/site/01dcc0?pathHash=cf89b2be) | 请参考响应示例 | #### 响应示例 ##### 正常示例 ```text app_id=2017060101317939&biz_content=%7B%22time_expire%22%3A%222016-12-31+10%3A05%3A00%22%2C%22extend_params%22%3A%22%22%2C%22query_options%22%3A%22%5B%5C%22hyb_amount%5C%22%2C%5C%22enterprise_pay_info%5C%22%5D%22%2C%22subject%22%3A%22%E5%A4%A7%E4%B9%90%E9%80%8F%22%2C%22product_code%22%3A%22QUICK_MSECURITY_PAY%22%2C%22body%22%3A%22Iphone6+16G%22%2C%22passback_params%22%3A%22merchantBizType%253d3C%2526merchantBizNo%253d2016010101111%22%2C%22specified_channel%22%3A%22pcredit%22%2C%22goods_detail%22%3A%22%22%2C%22merchant_order_no%22%3A%2220161008001%22%2C%22enable_pay_channels%22%3A%22pcredit%2CmoneyFund%2CdebitCardExpress%22%2C%22out_trade_no%22%3A%2270501111111S001111119%22%2C%22ext_user_info%22%3A%22%22%2C%22total_amount%22%3A%229.00%22%2C%22timeout_express%22%3A%2290m%22%2C%22disable_pay_channels%22%3A%22pcredit%2CmoneyFund%2CdebitCardExpress%22%2C%22agreement_sign_params%22%3A%22%22%7D&charset=UTF-8&format=json&method=alipay.trade.app.pay&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&sign_type=RSA2×tamp=2014-07-24+03%3A07%3A50&version=1.0 ``` #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.ACCESS_FORBIDDEN` | 无权限使用接口 | 联系支付宝小二签约 | | `ACQ.BUYER_ENABLE_STATUS_FORBID` | 买家状态非法 | 用户联系支付宝小二,确认买家状态非法原因 | | `ACQ.BUYER_SELLER_EQUAL` | 买卖家不能相同 | 更换买家重新付款 | | `ACQ.CONTEXT_INCONSISTENT` | 交易信息被篡改 | 确认该笔交易信息是否为当前买家的已存订单。如果是,则认为本次请求参数与已存交易不一致;如果不是,请更换商家订单号后重新发起请求 | | `ACQ.EXIST_FORBIDDEN_WORD` | 订单信息中包含违禁词 | 修改订单信息后重新发起请求 | | `ACQ.INVALID_PARAMETER` | 参数无效 | 若存在参数无效具体错误信息描述,请参考描述检查请求参数后重新发起 | | `ACQ.PARTNER_ERROR` | 应用 `APP_ID` 填写错误 | 联系支付宝小二,确认 `APP_ID` 的状态 | | `ACQ.RISK_MERCHANT_IP_NOT_EXIST` | 当前交易未传入 IP 信息,创单失败 | 检查请求参数是否已经传入用户 IP 信息 | | `ACQ.SELLER_BEEN_BLOCKED` | 商家账号被冻结 | 联系支付宝小二解冻账号 | | `ACQ.SYSTEM_ERROR` | 接口返回错误 | 请立即调用查询订单 API,查询当前订单状态,并根据订单状态决定下一步操作 | | `ACQ.TOTAL_FEE_EXCEED` | 订单总金额不在允许范围内 | 修改订单金额后再发起请求 | | `ACQ.TRADE_BUYER_NOT_MATCH` | 交易买家不匹配 | 该笔交易已经在支付宝端创建,但请求买家与已存交易中的买家不一致。请确认本次请求是否与已存交易有关;若为同一笔交易,只能用原始买家付款;若无关,请更换商家订单号后重新发起请求 | | `ACQ.TRADE_HAS_CLOSE` | 交易已经关闭 | 确认该笔交易信息是否为当前买家的已存订单。如果是,则认为交易已经关闭;如果不是,请更换商家订单号后重新发起请求 | | `ACQ.TRADE_HAS_SUCCESS` | 交易已被支付 | 确认该笔交易信息是否为当前买家的订单。如果是,则认为交易付款成功;如果不是,请更换商家订单号后重新发起请求 | #### 触发通知类型 | 通知类型 | 描述 | 默认开启 | | --- | --- | --- | | `tradeStatus.TRADE_CLOSED` | 交易关闭 | `1` | | `tradeStatus.TRADE_FINISHED` | 交易完结 | `1` | | `tradeStatus.TRADE_SUCCESS` | 支付成功 | `1` | | `tradeStatus.WAIT_BUYER_PAY` | 交易创建 | `0` | #### 触发通知示例 ```text https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync¬ify_id=91722adff935e8cfa58b3aabf4dead6ibe¬ify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&passback_params=null&body=null&subject=null&refund_fee=null&total_amount=null&trade_status=null&seller_id=null&out_trade_no=null&app_id=null&trade_no=null&buyer_open_id=074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5&out_channel_type=null&gmt_payment=null&gmt_create=null&gmt_close=null&gmt_refund=null&merchant_app_id=2088102146225135&out_biz_no=null&seller_email=null&buyer_logon_id=null&voucher_detail_list=null&point_amount=null&buyer_pay_amount=null&invoice_amount=null&receipt_amount=null&fund_bill_list=[{"amount":"50.00","fundChannel":"ALIPAYACCOUNT"}]&buyer_id=null¬ify_action_type=payByAccountAction/closeTradeAction/reverseAction/finishFPAction/confirmDisburseAction/financingReceiptAction¤t_seller_received_amount=88.88&seller_received_total_amount=88.88&total_from_seller_fee=88.88&ff_current_period=1&discount_amount=88.88&charge_amount=8.88&charge_flags=bluesea_1&settlement_id=2018101610032004620239146945&industry_sepc_detail={"registration_order_pay":{"brlx":"1","cblx":"1"}}&industry_sepc_detail_acc={"registration_order_pay":{"brlx":"1","cblx":"1"}}&industry_sepc_detail_gov={"registration_order_pay":{"brlx":"1","cblx":"1"}}&discount_goods_detail="[{\"goodsId\":\"STANDARD1026181538\",\"goodsName\":\"雪碧\",\"discountAmount\":\"10.00\"}]"&mdiscount_amount=88.88&hb_fq_pay_info={"USER_INSTALL_NUM":"3"}&receipt_currency_type=DC&enterprise_pay_info={"invoice_amount":"28.00","is_use_enterprise_pay":"true"}&hyb_amount=10.24&charge_info_list=[{"charge_fee":"0.01","original_charge_fee":"0.02","switch_fee_rate":"0.03","is_rating_on_trade_receiver":"Y","is_rating_on_switch":"Y"}]&medical_insurance_info={"medicareCardType":"1","medicareCardHolderHiddenName":"**专"}&credit_pay_mode=creditAdvanceV2&buyer_charge_amt=1.00&fulfillment_amount=10.24&cashier_type=APP&refund_voucher_detail_list=[{"amount":"0.10","merchantContribute":"0.00","name":"工具立减_固定金额","otherContribute":"0.10","type":"DISCOUNT","voucherId":"20241207000730027708000CRGZP"}] ``` --- ### 统一收单交易查询接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > API列表 > 统一收单交易查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-query.md 该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态,并据此完成下一步业务逻辑 #### 接口说明 接口名称:`alipay.trade.query` 该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态,并据此完成下一步业务逻辑。 #### 适用场景 需要调用查询接口的常见情况: - 商户后台、网络、服务器等出现异常,商户系统最终未接收到支付通知。 - 调用支付接口后,返回系统错误或未知交易状态。 - 调用 `alipay.trade.cancel` 前,需要先确认支付状态。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `out_trade_no` 与 `trade_no` 二选一传入,不能同时为空。若 `trade_no` 与 `out_trade_no` 同时存在,优先使用 `trade_no` 查询。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 枚举值/说明 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_trade_no` | string | 二选一 | 64 | 订单支付时传入的商户订单号,和支付宝交易号不能同时为空 | 若与 `trade_no` 同时存在,优先取 `trade_no` | `20150320010101001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号,和商户订单号不能同时为空 | 若与 `out_trade_no` 同时存在,优先取 `trade_no` | `2014112611001004680 073956707` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "out_trade_no":"20150320010101001", "trade_no":"2014112611001004680 073956707", "query_options":[ "trade_settle_info" ] }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.response.AlipayTradeQueryResponse; import com.alipay.api.request.AlipayTradeQueryRequest; import com.alipay.api.domain.AlipayTradeQueryModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680 073956707"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("trade_settle_info"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.OutTradeNo = "20150320010101001"; // 设置支付宝交易号 model.TradeNo = "2014112611001004680 073956707"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("trade_settle_info"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.exec("alipay.trade.query", { bizContent: { out_trade_no: "20150320010101001", trade_no: "2014112611001004680+073956707", query_options: ["trade_settle_info"], }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE3w1J+POiPh...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 必选 | 64 | 支付宝交易号 | 在未生成真实交易时不返回,需要商户多次调用该接口或等待支付通知,获取最终的交易号 | `2013112011001004330000121536` | | `out_trade_no` | string | 必选 | 64 | 商家订单号 | - | `6823789339978248` | | `trade_status` | string | 必选 | 32 | 交易状态 | `WAIT_BUYER_PAY`:交易创建,等待买家付款
`TRADE_CLOSED`:未付款交易超时关闭,或支付完成后全额退款
`TRADE_SUCCESS`:交易支付成功
`TRADE_FINISHED`:交易结束,不可退款 | `TRADE_CLOSED` | | `total_amount` | price | 必选 | 11 | 交易的订单金额,单位为元,两位小数 | 该参数的值为支付时传入的 `total_amount` | `88.88` | | `buyer_user_id` | string | 必选 | 16 | 买家在支付宝的用户 ID | 新商户建议使用 `buyer_open_id` 替代该字段。对于新商户,`buyer_user_id` 字段未来计划逐步回收,存量商户可继续使用。若使用 `buyer_open_id`,请确认“应用 - 开发配置 - openid 配置管理”已启用;无该配置项时,可查看 [openid 配置申请](https://ideservice.alipay.com/cms/site/0ai9ok?pathHash=de631c06) | `2088101117955611` | | `send_pay_date` | date | 特殊可选 | 32 | 本次交易打款给卖家的时间 | - | `2014-11-27 15:45:57` | | `receipt_amount` | string | 特殊可选 | 11 | 实收金额,单位为元,两位小数 | 该金额为本笔交易中商户账户能够实际收到的金额 | `15.25` | | `buyer_open_id` | string | 特殊可选 | 128 | 买家支付宝用户唯一标识 | 详情可查看 [openid 简介](https://ideservice.alipay.com/cms/site/0ai2i6?pathHash=13dd5946) | `01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0` | | `buyer_logon_id` | string | 可选 | 100 | 买家支付宝账号 | 在未生成真实交易时不返回,需要商户多次调用该接口或等待支付通知,获取最终的用户信息 | `159****5620` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_query_response": { "code": "10000", "msg": "Success", "trade_no": "2013112011001004330000121536", "out_trade_no": "6823789339978248", "buyer_logon_id": "159****5620", "trade_status": "TRADE_CLOSED", "total_amount": "88.88", "send_pay_date": "2014-11-27 15:45:57", "buyer_pay_amount": "8.88", "invoice_amount": "12.11", "point_amount": "10", "receipt_amount": "15.25", "store_id": "NJ_S_001", "terminal_id": "NJ_T_001", "fund_bill_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21" } ], "store_name": "证大五道口店", "buyer_open_id": "01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0", "buyer_user_id": "2088101117955611", "discount_amount": "88.88", "ext_infos": "{\"action\":\"cancel\"}", "buyer_user_type": "PRIVATE", "mdiscount_amount": "88.88" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.INVALID_PARAMETER` | 参数无效 | 检查请求参数,修改后重新发起请求 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 查询的交易不存在 | 检查传入的交易号是否正确,修改后重新发起请求 | --- ### 统一收单交易退款接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > API列表 > 统一收单交易退款接口 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-refund.md 卖家可以通过退款接口将支付款退还给买家 #### 接口说明 接口名称:`alipay.trade.refund` 当交易发生之后一段时间内,由于买家或卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家。支付宝在收到退款请求并验证成功后,会按照退款规则将支付款按原路退回买家账号。 交易超过约定时间(签约时设置的可退款时间)的订单无法进行退款。 支付宝退款支持单笔交易分多次退款,多次退款需要提交原支付订单的订单号,并设置不同的退款请求号。一笔退款失败后重新提交时,必须保证退款请求号不变,防止重复退款。同一笔交易累计提交的退款金额不能超过原始交易总金额。 #### 注意事项 1. 同一笔交易的退款至少间隔 3 秒后发起。 2. 请严格按照接口文档中的参数接入。若传入非当前接口文档中的参数,可能造成退款失败或重复退款。 3. 该接口不可与其他退款产品混用。若商户侧同一笔退款请求已使用当前接口退款,再使用其他退款产品退款,可能造成重复退款。 4. 退款成功判断:接口返回 `fund_change=Y` 表示退款成功;`fund_change=N` 或无此字段返回时,需要通过退款查询接口进一步确认退款状态。详见[退款成功判断指导](https://ideservice.alipay.com/cms/site/01rawa)。接口中 `code=10000` 仅代表本次退款请求成功,不代表退款成功。 5. 若退款原订单涉及分账,在发起退款前,需要分账接收方在[支付宝商家平台](https://b.alipay.com/page/portal/home) > 资金管理 > 资金服务 > 分账接收设置中开启分账回退授权后,才可以正常退款。且不支持接收方为个人的分账单发起退款退分账。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.refund` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `out_trade_no` 与 `trade_no` 二选一传入,不能同时为空。两者同时存在时,优先使用 `trade_no`。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `refund_amount` | price | 必选 | 16 | 退款金额,单位为元,支持两位小数,不能大于订单金额 | 如果正向交易使用了营销,该退款金额包含营销金额。支付宝会按业务规则分配营销和买家自有资金分别退多少,默认优先退买家的自有资金 | `200.12` | | `out_trade_no` | string | 二选一 | 64 | 商户订单号,订单支付时传入,商家自定义且保证商家系统中唯一 | 与 `trade_no` 不能同时为空 | `20150320010101001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号 | 与 `out_trade_no` 不能同时为空;两者同时存在时,优先取 `trade_no` | `2014112611001004680073956707` | | `refund_reason` | string | 可选 | 256 | 退款原因说明,商家自定义 | 会在商户和用户的 PC 退款账单详情中展示 | `正常退款` | | `out_request_no` | string | 可选 | 64 | 退款请求号,标识一次退款请求,需要保证在交易号下唯一 | 部分退款时必选。同一次退款请求失败或异常后重试时,必须保证退款请求号不变,防止重复退款。支付宝会保证同样的退款请求号多次请求只退一次 | `HZ01RF001` | #### 请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.refund&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "out_trade_no":"20150320010101001", "trade_no":"2014112611001004680073956707", "refund_amount":"200.12", "refund_reason":"正常退款", "out_request_no":"HZ01RF001", "refund_goods_detail":[ { "out_sku_id":"outSku_01", "out_item_id":"outItem_01", "goods_id":"apple-01", "refund_amount":"19.50", "out_certificate_no_list":[ "202407013232143241231243243423" ] } ], "refund_royalty_parameters":[ { "amount":"0.1", "trans_in":"2088101126708402", "royalty_type":"transfer", "trans_out":"2088101126765726", "trans_out_type":"userId", "royalty_scene":"达人佣金", "trans_in_type":"userId", "trans_in_name":"张三", "desc":"分账给2088101126708402" } ], "query_options":[ "refund_detail_item_list" ], "related_settle_confirm_no":"2024041122001495000530302869" }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeRefundModel; import com.alipay.api.request.AlipayTradeRefundRequest; import com.alipay.api.response.AlipayTradeRefundResponse; import com.alipay.api.domain.RefundGoodsDetail; import com.alipay.api.domain.OpenApiRoyaltyDetailInfoPojo; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeRefund { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); AlipayTradeRefundModel model = new AlipayTradeRefundModel(); // 设置商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680073956707"); // 设置退款金额 model.setRefundAmount("200.12"); // 设置退款原因说明 model.setRefundReason("正常退款"); // 设置退款请求号 model.setOutRequestNo("HZ01RF001"); // 设置退款包含的商品列表信息 List refundGoodsDetail = new ArrayList(); RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail(); refundGoodsDetail0.setOutSkuId("outSku_01"); refundGoodsDetail0.setOutItemId("outItem_01"); refundGoodsDetail0.setGoodsId("apple-01"); refundGoodsDetail0.setRefundAmount("19.50"); List outCertificateNoList = new ArrayList(); outCertificateNoList.add("202407013232143241231243243423"); refundGoodsDetail0.setOutCertificateNoList(outCertificateNoList); refundGoodsDetail.add(refundGoodsDetail0); model.setRefundGoodsDetail(refundGoodsDetail); // 设置退分账明细信息 List refundRoyaltyParameters = new ArrayList(); OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo(); refundRoyaltyParameters0.setAmount("0.1"); refundRoyaltyParameters0.setTransIn("2088101126708402"); refundRoyaltyParameters0.setRoyaltyType("transfer"); refundRoyaltyParameters0.setTransOut("2088101126765726"); refundRoyaltyParameters0.setTransOutType("userId"); refundRoyaltyParameters0.setRoyaltyScene("达人佣金"); refundRoyaltyParameters0.setTransInType("userId"); refundRoyaltyParameters0.setTransInName("张三"); refundRoyaltyParameters0.setDesc("分账给2088101126708402"); refundRoyaltyParameters.add(refundRoyaltyParameters0); model.setRefundRoyaltyParameters(refundRoyaltyParameters); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("refund_detail_item_list"); model.setQueryOptions(queryOptions); // 设置针对账期交易 model.setRelatedSettleConfirmNo("2024041122001495000530302869"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeRefundResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeRefund { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); AlipayTradeRefundModel model = new AlipayTradeRefundModel(); // 设置商户订单号 model.OutTradeNo = "20150320010101001"; // 设置支付宝交易号 model.TradeNo = "2014112611001004680073956707"; // 设置退款金额 model.RefundAmount = "200.12"; // 设置退款原因说明 model.RefundReason = "正常退款"; // 设置退款请求号 model.OutRequestNo = "HZ01RF001"; // 设置退款包含的商品列表信息 List refundGoodsDetail = new List(); RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail(); refundGoodsDetail0.OutSkuId = "outSku_01"; refundGoodsDetail0.OutItemId = "outItem_01"; refundGoodsDetail0.GoodsId = "apple-01"; refundGoodsDetail0.RefundAmount = "19.50"; List outCertificateNoList = new List(); outCertificateNoList.Add("202407013232143241231243243423"); refundGoodsDetail0.OutCertificateNoList = outCertificateNoList; refundGoodsDetail.Add(refundGoodsDetail0); model.RefundGoodsDetail = refundGoodsDetail; // 设置退分账明细信息 List refundRoyaltyParameters = new List(); OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo(); refundRoyaltyParameters0.Amount = "0.1"; refundRoyaltyParameters0.TransIn = "2088101126708402"; refundRoyaltyParameters0.RoyaltyType = "transfer"; refundRoyaltyParameters0.TransOut = "2088101126765726"; refundRoyaltyParameters0.TransOutType = "userId"; refundRoyaltyParameters0.RoyaltyScene = "达人佣金"; refundRoyaltyParameters0.TransInType = "userId"; refundRoyaltyParameters0.TransInName = "张三"; refundRoyaltyParameters0.Desc = "分账给2088101126708402"; refundRoyaltyParameters.Add(refundRoyaltyParameters0); model.RefundRoyaltyParameters = refundRoyaltyParameters; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("refund_detail_item_list"); model.QueryOptions = queryOptions; // 设置针对账期交易 model.RelatedSettleConfirmNo = "2024041122001495000530302869"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeRefundResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const AlipaySdk = require("alipay-sdk").default; const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", }); const result = await alipaySdk.exec("alipay.trade.refund", { bizContent: { out_trade_no: "20150320010101001", trade_no: "2014112611001004680073956707", refund_amount: "200.12", refund_reason: "正常退款", out_request_no: "HZ01RF001", refund_goods_detail: { 0: { out_sku_id: "outSku_01", out_item_id: "outItem_01", goods_id: "apple-01", refund_amount: "19.50", out_certificate_no_list: { 0: "202407013232143241231243243423", }, }, }, refund_royalty_parameters: { 0: { amount: "0.1", trans_in: "2088101126708402", royalty_type: "transfer", trans_out: "2088101126765726", trans_out_type: "userId", royalty_scene: "达人佣金", trans_in_type: "userId", trans_in_name: "张三", desc: "分账给2088101126708402", }, }, query_options: { 0: "refund_detail_item_list", }, related_settle_confirm_no: "2024041122001495000530302869", }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 必选 | 64 | 支付宝交易号 | - | `2013112011001004330000121536` | | `out_trade_no` | string | 必选 | 64 | 商户订单号 | - | `6823789339978248` | | `buyer_logon_id` | string | 必选 | 100 | 用户的登录 ID | - | `159****5620` | | `refund_fee` | price | 必选 | 11 | 退款总金额,单位为元 | 指该笔交易累计已经退款成功的金额 | `88.88` | | `buyer_user_id` | string | 特殊可选 | 28 | 买家在支付宝的用户 ID | 新商户建议使用 `buyer_open_id` 替代该字段。对于新商户,`buyer_user_id` 字段未来计划逐步回收,存量商户可继续使用。若使用 `buyer_open_id`,请确认“应用 - 开发配置 - openid 配置管理”已启用;无该配置项时,可查看 [openid 配置申请](https://ideservice.alipay.com/cms/site/0ai9ok?pathHash=de631c06) | `2088101117955611` | | `buyer_open_id` | string | 特殊可选 | 128 | 买家支付宝用户唯一标识 | 详情可查看 [openid 简介](https://ideservice.alipay.com/cms/site/0ai2i6?pathHash=13dd5946) | `074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5` | | `send_back_fee` | string | 特殊可选 | 11 | 本次商户实际退回金额,单位为元 | 如需获取该值,需在入参 `query_options` 中传入 `refund_detail_item_list` | `1.8` | | `fund_change` | string | 可选 | 1 | 本次退款是否发生了资金变化 | `Y` 通常表示退款成功;`N` 或无此字段时需通过退款查询接口进一步确认退款状态 | `Y` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_refund_response": { "code": "10000", "msg": "Success", "trade_no": "2013112011001004330000121536", "out_trade_no": "6823789339978248", "buyer_logon_id": "159****5620", "fund_change": "Y", "refund_fee": "88.88", "refund_detail_item_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21", "fund_type": "DEBIT_CARD" } ], "store_name": "望湘园联洋店", "buyer_user_id": "2088101117955611", "buyer_open_id": "074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5", "send_back_fee": "1.8", "refund_hyb_amount": "10.24", "refund_charge_info_list": [ { "refund_charge_fee": "0.01", "switch_fee_rate": "0.01", "charge_type": "trade", "refund_sub_fee_detail_list": [ { "refund_charge_fee": "0.10", "switch_fee_rate": "0.01" } ] } ], "refund_voucher_detail_list": [ { "id": "2015102600073002039000002D5O", "name": "XX超市5折优惠", "type": "ALIPAY_FIX_VOUCHER", "amount": "10.00", "merchant_contribute": "9.00", "other_contribute": "1.00", "memo": "学生专用优惠", "template_id": "20171030000730015359000EMZP0", "other_contribute_detail": [ { "contribute_type": "BRAND", "contribute_amount": "8.00" } ], "purchase_buyer_contribute": "2.01", "purchase_merchant_contribute": "1.03", "purchase_ant_contribute": "0.82" } ], "pre_auth_cancel_fee": "12.45" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_refund_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.ALLOC_AMOUNT_VALIDATE_ERROR` | 退分账金额超限 | 请调整退分账金额后重试 | | `ACQ.BUYER_ENABLE_STATUS_FORBID` | 买家状态异常 | 联系支付宝小二确认买家状态异常原因,或者联系买家进行线下退款处理 | | `ACQ.BUYER_ERROR` | 买家状态异常 | 联系支付宝小二确认买家状态异常原因,或者联系买家进行线下退款处理 | | `ACQ.BUYER_NOT_EXIST` | 买家不存在 | 买家已经注销账号,建议联系买家进行线下退款处理 | | `ACQ.CURRENCY_NOT_SUPPORT` | 退款币种不支持 | 请确认传入的退款币种是否正确 | | `ACQ.CUSTOMER_VALIDATE_ERROR` | 账户已注销或者被冻结 | 请查询账户状态:如果账户已注销,请线下处理;如果账户已冻结,请联系支付宝小二确认冻结原因 | | `ACQ.DISCORDANT_REPEAT_REQUEST` | 请求信息不一致 | 退款请求号对应的退款已经执行成功,且本次请求的退款金额与之前请求的金额不一致。请检查退款金额是否正确,或通过退款查询接口获取退款执行结果 | | `ACQ.ENTERPRISE_PAY_BIZ_ERROR` | 因公付业务异常 | 如果提示“当前交易不含企业出资”,请确认交易是否包含企业出资;如果不包含,接口入参不能指定 `enterprise_pay_info`;如果确认包含,请联系支付宝核实。如果提示“无效企业退款金额”,请检查指定的企业退款金额是否超过当前交易企业支付的金额。其他情况请联系支付宝小二 | | `ACQ.INVALID_PARAMETER` | 参数无效 | 请根据接口返回的错误信息检查请求参数,修改后重新发起请求 | | `ACQ.NOT_ALLOW_PARTIAL_REFUND` | 不支持部分退款 | 由于交易使用了特定优惠券等场景,该笔交易不支持部分退款,请进行全额退款或联系买家线下退款 | | `ACQ.ONLINE_TRADE_VOUCHER_NOT_ALLOW_REFUND` | 交易不允许退款 | 此交易中核销了购买的代金券,不允许退款,可联系买家线下退款 | | `ACQ.OVERDRAFT_AGREEMENT_NOT_MATCH` | 垫资退款接口传入模式和签约配置不一致 | 请检查垫资退款合约中的出资方式,修改合约或接口传参后重试 | | `ACQ.OVERDRAFT_ASSIGN_ACCOUNT_INVALID` | 垫资退款出资账号和商户信息不一致 | 垫资退款出资账号必须为商户名下支付宝账号,请更换出资账号后重试 | | `ACQ.REASON_TRADE_BEEN_FREEZEN` | 请求退款的交易被冻结 | 联系支付宝小二确认该笔交易的具体情况 | | `ACQ.REASON_TRADE_REFUND_FEE_ERR` | 退款金额无效 | 同一笔交易累计请求的退款金额不能大于交易总金额,请检查退款请求金额是否正确 | | `ACQ.REASON_TRADE_STATUS_INVALID` | 交易状态异常 | 查询交易,确认交易是否为支付成功状态;如是,可联系支付宝小二确认交易状态 | | `ACQ.REFUNDALLOC_UNAUTH_LIMIT` | 分账接收方未开启分账回退,退分账失败 | 请联系分账接收方在支付宝商家平台 > 资金管理 > 资金服务 > 分账接收设置中开启分账回退授权后再发起调用 | | `ACQ.REFUND_ACCOUNT_NOT_EXIST` | 退款出资账号不存在或账号异常 | 检查退款出资账号状态,账号正常后重试 | | `ACQ.REFUND_AMT_NOT_EQUAL_TOTAL` | 退款金额超限 | 请检查退款金额是否正确,请求退款金额不能大于交易总金额;如果不是全额退款,退款请求号必填,请检查是否传入退款请求号 | | `ACQ.REFUND_CHARGE_ERROR` | 退收费异常 | 请过一段时间后再重试发起退款 | | `ACQ.REFUND_FEE_ERROR` | 交易退款金额有误 | 请检查传入的退款金额是否正确 | | `ACQ.REFUND_ROYALTY_PAYEE_ACCOUNT_NOT_EXIST` | 退分账收入方账户不存在 | 请确认收入方账号是否正确,更换账号后重新发起 | | `ACQ.SELLER_BALANCE_NOT_ENOUGH` | 卖家余额不足 | 商户支付宝账户充值后重新发起退款 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 当前退款请求可能成功也可能失败。请使用相同参数再次重试,保证退款请求号和退款金额不变;如果前一次退款已经成功,接口会幂等返回成功;如果前一次未成功,接口会重试执行退款。也可通过退款查询接口查询退款执行结果,发起退款查询需保证距离退款请求大于 5 秒 | | `ACQ.TRADE_HAS_CLOSE` | 交易已关闭 | 该交易已关闭,不能再退款,请确认请求退款的交易是否未支付或已完成退款 | | `ACQ.TRADE_HAS_FINISHED` | 交易已完结 | 该交易已完结,已超过退款期限,不允许退款;建议联系买家线下退款 | | `ACQ.TRADE_NOT_ALLOW_REFUND` | 当前交易不允许退款 | 检查当前交易状态是否为交易成功状态,以及签约的退款属性是否允许退款,确认后重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 检查请求中的交易号和商户订单号是否正确,确认后重新发起 | | `ACQ.TRADE_SETTLE_ERROR` | 交易结算异常 | 请检查传入的退结算项信息是否正确;如果正确,请联系支付宝小二 | | `ACQ.TRADE_STATUS_ERROR` | 交易状态非法 | 查询交易,确认交易是否已经付款 | | `ACQ.USER_NOT_MATCH_ERR` | 交易用户不匹配 | 请联系支付宝小二处理 | --- ### 统一收单交易退款查询接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > API列表 > 统一收单交易退款查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-fastpay-refund-query.md 商户可使用该接口查询提交的退款请求是否执行成功。 #### 接口说明 接口名称:`alipay.trade.fastpay.refund.query` 商户可使用该接口查询自己通过 `alipay.trade.refund` 提交的退款请求是否执行成功。 #### 注意事项 1. 该接口返回码 `10000` 仅代表本次查询操作成功,不代表退款成功。当接口返回的 `refund_status` 值为 `REFUND_SUCCESS` 时,表示退款成功;否则表示退款没有执行成功。 2. 如果退款未成功,商户可以调用退款接口重试。重试时请务必保证退款请求号和退款金额一致,防止重复退款。 3. 发起退款查询接口的时间不能离退款请求时间太短,建议间隔 10 秒以上。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.fastpay.refund.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `trade_no` 与 `out_trade_no` 二选一传入,不能同时为空。两者同时存在时,优先使用 `trade_no`。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | string | 必选 | 64 | 退款请求号 | 请求退款接口时传入的退款请求号;如果退款请求时未传入,则该值为创建交易时的商户订单号 | `HZ01RF001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号 | 与商户订单号不能同时为空 | `2021081722001419121412730660` | | `out_trade_no` | string | 二选一 | 64 | 商户订单号,订单支付时传入 | 与支付宝交易号不能同时为空;`trade_no`、`out_trade_no` 同时存在时,优先取 `trade_no` | `2014112611001004680073956707` | #### 请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.fastpay.refund.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "trade_no":"2021081722001419121412730660", "out_trade_no":"2014112611001004680073956707", "out_request_no":"HZ01RF001", "query_options":[ "refund_detail_item_list" ] }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeFastpayRefundQueryModel; import com.alipay.api.response.AlipayTradeFastpayRefundQueryResponse; import com.alipay.api.request.AlipayTradeFastpayRefundQueryRequest; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeFastpayRefundQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest(); AlipayTradeFastpayRefundQueryModel model = new AlipayTradeFastpayRefundQueryModel(); // 设置支付宝交易号 model.setTradeNo("2021081722001419121412730660"); // 设置商户订单号 model.setOutTradeNo("2014112611001004680073956707"); // 设置退款请求号 model.setOutRequestNo("HZ01RF001"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("refund_detail_item_list"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeFastpayRefundQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeFastpayRefundQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest(); AlipayTradeFastpayRefundQueryModel model = new AlipayTradeFastpayRefundQueryModel(); // 设置支付宝交易号 model.TradeNo = "2021081722001419121412730660"; // 设置商户订单号 model.OutTradeNo = "2014112611001004680073956707"; // 设置退款请求号 model.OutRequestNo = "HZ01RF001"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("refund_detail_item_list"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeFastpayRefundQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoY...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 特殊可选 | 64 | 支付宝交易号 | - | `2014112611001004680073956707` | | `out_trade_no` | string | 特殊可选 | 64 | 创建交易传入的商户订单号 | - | `20150320010101001` | | `out_request_no` | string | 特殊可选 | 64 | 本笔退款对应的退款请求号 | - | `20150320010101001` | | `total_amount` | price | 特殊可选 | 11 | 该笔退款所对应交易的订单金额,单位为元 | - | `100.20` | | `refund_amount` | price | 特殊可选 | 11 | 本次退款请求对应的退款金额,单位为元 | - | `12.33` | | `refund_status` | string | 特殊可选 | 32 | 退款状态 | `REFUND_SUCCESS`:退款处理成功。未返回该字段表示退款请求未收到或退款失败。如果退款查询发起时间早于退款时间,或距离退款发起时间太短,可能出现查询时尚未处理成功、后续又处理成功的情况,建议退款发起后间隔 10 秒以上再查询 | `REFUND_SUCCESS` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_fastpay_refund_query_response": { "code": "10000", "msg": "Success", "trade_no": "2014112611001004680073956707", "out_trade_no": "20150320010101001", "out_request_no": "20150320010101001", "total_amount": "100.20", "refund_amount": "12.33", "refund_status": "REFUND_SUCCESS", "refund_royaltys": [ { "refund_amount": "10", "royalty_type": "transfer", "result_code": "SUCCESS", "trans_out": "2088102210397302", "trans_out_email": "alipay-test03@alipay.com", "trans_in": "2088102210397302", "trans_in_email": "zen_gwen@hotmail.com", "ori_trans_out": "2088111111111111", "ori_trans_in": "2088111111111111" } ], "gmt_refund_pay": "2014-11-27 15:45:57", "refund_detail_item_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21", "fund_type": "DEBIT_CARD" } ], "send_back_fee": "88", "deposit_back_info": { "has_deposit_back": "true", "dback_status": "S", "dback_amount": "1.01", "bank_ack_time": "2020-06-02 14:03:48", "est_bank_receipt_time": "2020-06-02 14:03:48" }, "refund_hyb_amount": "10.24", "refund_charge_info_list": [ { "refund_charge_fee": "0.01", "switch_fee_rate": "0.01", "charge_type": "trade", "refund_sub_fee_detail_list": [ { "refund_charge_fee": "0.10", "switch_fee_rate": "0.01" } ] } ], "deposit_back_info_list": [ { "has_deposit_back": "true", "dback_status": "S", "dback_amount": "1.01", "bank_ack_time": "2020-06-02 14:03:48", "est_bank_receipt_time": "2020-06-02 14:03:48" } ], "refund_voucher_detail_list": [ { "id": "2015102600073002039000002D5O", "name": "XX超市5折优惠", "type": "ALIPAY_FIX_VOUCHER", "amount": "10.00", "merchant_contribute": "9.00", "other_contribute": "1.00", "memo": "学生专用优惠", "template_id": "20171030000730015359000EMZP0", "other_contribute_detail": [ { "contribute_type": "BRAND", "contribute_amount": "8.00" } ], "purchase_buyer_contribute": "2.01", "purchase_merchant_contribute": "1.03", "purchase_ant_contribute": "0.82" } ], "pre_auth_cancel_fee": "12.45" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_fastpay_refund_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.ENTERPRISE_PAY_BIZ_ERROR` | 因公付业务异常 | 重新发起查询请求;如果多次重试后仍返回同样错误,请联系支付宝小二处理 | | `ACQ.INVALID_PARAMETER` | 参数无效 | 请根据接口返回的错误信息检查请求参数,修改后重新发起请求 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 重新发起查询请求;如果多次重试后仍返回系统错误,请联系支付宝小二处理 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 请确认传入的外部订单号或交易号是否正确 | | `TRADE_NOT_EXIST` | 查询退款的交易不存在 | 确认交易号是否为正确的支付宝交易号,修改后重新查询 | --- ### 统一收单交易关闭接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > API列表 > 统一收单交易关闭接口 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-trade-close.md 用于交易创建后,用户在一定时间内未进行支付,可调用该接口直接将未付款的交易进行关闭。 #### 接口说明 接口名称:`alipay.trade.close` 用于交易创建后,用户在一定时间内未进行支付,可调用该接口直接将未付款的交易进行关闭。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.close` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `trade_no` 与 `out_trade_no` 二选一传入,不能同时为空。若两者同时传入,以 `trade_no` 为准。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 二选一 | 64 | 该交易在支付宝系统中的交易流水号,最短 16 位,最长 64 位 | 与 `out_trade_no` 不能同时为空;若同时传入 `out_trade_no` 和 `trade_no`,以 `trade_no` 为准 | `2013112611001004680073956707` | | `out_trade_no` | string | 二选一 | 64 | 订单支付时传入的商户订单号 | 与支付宝交易号不能同时为空;若 `trade_no`、`out_trade_no` 同时存在,优先取 `trade_no` | `HZ0120131127001` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.close&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "trade_no":"2013112611001004680073956707", "out_trade_no":"HZ0120131127001", "operator_id":"YX01" }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeCloseRequest; import com.alipay.api.domain.AlipayTradeCloseModel; import com.alipay.api.response.AlipayTradeCloseResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeClose { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCloseRequest request = new AlipayTradeCloseRequest(); AlipayTradeCloseModel model = new AlipayTradeCloseModel(); // 设置该交易在支付宝系统中的交易流水号 model.setTradeNo("2013112611001004680073956707"); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("HZ0120131127001"); // 设置商家操作员编号 id model.setOperatorId("YX01"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCloseResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeClose { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCloseRequest request = new AlipayTradeCloseRequest(); AlipayTradeCloseModel model = new AlipayTradeCloseModel(); // 设置该交易在支付宝系统中的交易流水号 model.TradeNo = "2013112611001004680073956707"; // 设置订单支付时传入的商户订单号 model.OutTradeNo = "HZ0120131127001"; // 设置商家操作员编号 id model.OperatorId = "YX01"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCloseResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.exec("alipay.trade.close", { bizContent: { trade_no: "2013112611001004680073956707", out_trade_no: "HZ0120131127001", operator_id: "YX01", }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | ACQ.TRADE_HAS_SUCCESS | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | 交易已被支付 | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 特殊可选 | 64 | 支付宝交易号 | - | `2013112111001004500000675971` | | `out_trade_no` | string | 特殊可选 | 64 | 创建交易传入的商户订单号 | - | `YX_001` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_close_response": { "code": "10000", "msg": "Success", "trade_no": "2013112111001004500000675971", "out_trade_no": "YX_001" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_close_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.INVALID_PARAMETER` | 参数无效 | 检查请求参数,修改后重新发起请求 | | `ACQ.REASON_ILLEGAL_STATUS` | 交易状态异常 | 确认交易状态,非待支付状态下不支持关单操作 | | `ACQ.REASON_TRADE_STATUS_INVALID` | 交易状态异常 | 确认交易状态,非待支付状态下不支持关单操作 | | `ACQ.SYSTEM_ERROR` | 系统异常 | 重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 检查传入的交易号和外部订单号是否正确,修改后重新发起 | | `ACQ.TRADE_STATUS_ERROR` | 交易状态不合法 | 检查当前交易的状态是否为等待买家付款。只有等待买家付款状态下才能发起交易关闭 | #### 触发通知类型 | 通知类型 | 描述 | 默认开启 | | --- | --- | --- | | `tradeStatus.TRADE_CLOSED` | 交易关闭 | `1` | | `tradeStatus.TRADE_SUCCESS` | 交易成功 | `0` | #### 触发通知示例 ```text https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync¬ify_id=91722adff935e8cfa58b3aabf4dead6ibe¬ify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&trade_no=null&app_id=null&out_trade_no=null&out_biz_no=null&buyer_logon_id=null&seller_id=null&seller_email=null&trade_status=null&total_amount=null&refund_fee=null&subject=null&body=null&gmt_create=null&gmt_payment=null&gmt_refund=null&gmt_close=null&fund_bill_list=null&receipt_amount=null&invoice_amount=null&buyer_pay_amount=null&point_amount=null&buyer_id=null ``` --- ### 查询对账单下载地址接口 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > API列表 > 查询对账单下载地址接口 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/alipay-data-dataservice-bill-downloadurl-query.md 方便商户快速查账,支持商户通过本接口获取商户离线账单下载地址 #### 接口说明 接口名称:`alipay.data.dataservice.bill.downloadurl.query` 为方便商户快速查账,支付宝支持商户通过本接口获取商户离线账单下载地址。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.data.dataservice.bill.downloadurl.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `bill_type` | string | 必选 | 20 | 账单类型,商户通过接口,或商户经开放平台授权后其所属服务商通过接口,可以获取对应账单类型 | `trade`:商户基于支付宝交易收单的业务账单
`signcustomer`:基于商户支付宝余额收入及支出等资金变动的账务账单
`merchant_act`:营销活动账单,包含营销活动的发放、核销记录
`trade_zft_merchant`:直付通二级商户查询交易的业务账单
`zft_acc`:直付通平台商查询二级商户流水使用,返回所有二级商户流水
`settlementMerge`:每日结算到卡的资金对应明细,下载内容包含批次结算到卡明细文件和批次结算到卡汇总文件;若查询时间范围内有多个批次,会将多个批次的明细和汇总文件打包到一份压缩包中 | `trade` | | `bill_date` | string | 必选 | 15 | 账单时间 | 日账单格式为 `yyyy-MM-dd`,最早可下载近 6 年的日账单;不支持下载当日账单,只能下载前一日 24 点前的账单数据(T+1),当日数据一般于次日 9 点前生成,特殊情况可能延迟
月账单格式为 `yyyy-MM`,最早可下载近 6 年的月账单;不支持下载当月账单,只能下载上一月账单数据,当月账单一般在次月 3 日生成,特殊情况可能延迟
当 `biz_type` 为 `settlementMerge` 时,时间为汇总批次结算资金到账日期,格式为 `yyyy-MM-dd`,最早可下载 2023 年 4 月 17 日及以后的账单
接口调用仅支持下载近 6 年的账单,更多账单请前往 `b.alipay.com` 对账中心-账单下载页下载 | `2025-05-01` | | `smid` | string | 可选 | 20 | 二级商户 `smid` | 仅在 `bill_type` 为 `trade_zft_merchant` 时可使用 | `2088123412341234` | #### 请求示例 ##### cURL ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.data.dataservice.bill.downloadurl.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "bill_type":"trade", "bill_date":"2025-05-01", "smid":"2088123412341234" }' ``` #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE3w1J+POiPhfDxOYBfUNn1lkeT/V7P4zJdyojWEa6IZs6Hz0yDW5Cp/viufUb5I0/V5WENS3OYR8zRedqo6D+fUTdLHdc+EFyCkiQhBxIzgngPdPdfp1PIS7BdhhzrsZHbRqb7o4k3Dxc+AAnFauu4V6Zdwczo=` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `bill_download_url` | string | 可选 | 2048 | 当账单可获取时,返回账单下载地址链接 | 获取链接后 30 秒内未下载,链接地址失效 | `http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&pid=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X` | | `bill_file_code` | string | 可选 | 64 | 账单文件结果说明,描述本次申请的账单文件状态 | `EMPTY_DATA_WITH_BILL_FILE`:当前周期无数据时产生的空账单数据文件。目前仅对默认配置用户生效,主动配置的不会返回当前字段 | `EMPTY_DATA_WITH_BILL_FILE` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_data_dataservice_bill_downloadurl_query_response": { "code": "10000", "msg": "Success", "bill_download_url": "http://dwbillcenter.alipay.com/downloadBillFile.resource?bizType=X&pid=X&fileType=X&bizDates=X&downloadFileName=X&fileId=X", "bill_file_code": "EMPTY_DATA_WITH_BILL_FILE" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_data_dataservice_bill_downloadurl_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `BILL_DATE_BEFORE_REGISTRATION` | 请求的账单时间早于注册时间 | 确认参数后重新查询 | | `BILL_NOT_EXIST` | 账单不存在 | 确认参数后重新查询 | | `INVAILID_ARGUMENTS` | 入参不合法 | 确认参数后重新查询 | | `NO_BILL_DATA` | 商户在请求的账单时间内没有发生当前账单类型的业务 | 确认参数后重新查询 | | `SYSTEM_RATE_LIMIT` | 系统当前负载较高,请求被限流,请稍后重试 | 间隔 1 分钟后重试 | | `TYPE_NOT_SUPPORTED` | 此账单类型不支持下载 | 根据不同 `bill_type` 确定解决方案:
`trade`:需签约支付宝支付产品,且有对应产品产生的实际流水,支付产品范围详见[支付宝产品大全](https://b.alipay.com/page/product-mall/all-product?mrchportalwebServer=https%3A%2F%2Fmrchportalweb.alipay.com#J_wysk)
`signcustomer`:非支付宝商家身份,建议先签约收钱码或经营码产品
`merchant_act`:一年内无营销动作,具体请参考[营销账单使用](https://ideservice.alipay.com/cms/site/03ae7i?pathHash=83ffda2d)
`trade_zft_merchant`:请联系直付通平台商提供对应账单数据
`zft_acc`:请先签约[互联网平台直付通](https://b.alipay.com/page/product-mall/solution-detail?solutionCode=SP000001000000007155&sceneCode=PAYMENT)产品
`settlementMerge`:请先签约[收款到银行账户](https://b.alipay.com/page/product-mall/product-detail/I1080300001000041457/ALL?)产品
其他:该账单类型不支持下载操作,请再次确认账单类型及所选日期。如有需求,请联系支付宝小二排查 | | `UNKNOWN_ERROR` | 未知错误 | 稍后重试或联系小二排查问题 | | `USER_RATE_LIMIT` | 调用频率超限 | 间隔 1 分钟后重试,查看[调用频率限制](https://ideservice.alipay.com/cms/site/01inen?pathHash=4fae1c5e)中新增的 2.4 请求频次 | --- ### 异步通知说明 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > API列表 > 异步通知说明 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/async-notify-verify.md 异步通知说明 #### 使用说明 异步通知是指一笔订单支付完成后,支付宝会将该笔订单的变更信息,沿着商家调用支付请求时传入的异步通知地址 `notify_url`,通过 POST 请求将支付结果作为参数通知到商家系统。 异步回调地址状态码(HTTP 状态码)为 `200` 时表示异步通知成功;返回码为 `404` 或 `500` 时表示服务器内部错误,需要商家自行排查。 #### 注意事项 :::info 由于网络异常、系统波动等原因,可能会存在用户支付成功但商户侧未能成功接收到支付结果异步通知的情况。这会导致商户获取不到支付结果、用户订单显示为未支付。 为杜绝以上问题,商户需要同时接入支付结果异步通知与统一收单交易查询接口。当商户侧未收到支付结果异步通知时,必须调用 `alipay.trade.query` 查询订单支付结果。 当商户针对同一笔业务订单更换商户订单号 `out_trade_no` 来请求支付宝前,强烈建议先查询前一个商户订单号的支付结果: - 若为支付成功(`trade_status = TRADE_SUCCESS`),不要再请求支付宝重复支付。 - 若买家仍未支付(`trade_status = WAIT_BUYER_PAY`),调用 `alipay.trade.close` 关闭此订单后再请求支付宝支付。 ::: #### 异步通知参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `notify_time` | Date | 必选 | - | 通知发送时间,格式为 `yyyy-MM-dd HH:mm:ss`。 | - | 2020-12-27 06:20:30 | | `notify_type` | String | 必选 | 64 | 通知类型。 | 枚举值:`trade_status_sync`。 | trade_status_sync | | `notify_id` | String | 必选 | 128 | 通知校验 ID。 | - | ac05099524730693a8b330c5ecf72da9786 | | `sign_type` | String | 必选 | 10 | 签名类型,商家生成签名字符串所使用的签名算法类型。 | 目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2`。如果开发者手动验签且不使用 SDK 验签,可以不传此参数。 | RSA2 | | `sign` | String | 必选 | 344 | 签名。 | 可查看“异步返回结果验签”。如果开发者手动验签且不使用 SDK 验签,可以不传此参数。 | 601510b7970e52cc63db0f44997cf70e | | `trade_no` | String | 必选 | 64 | 支付宝交易号,支付宝交易凭证号。 | - | 20213112011001004330000121536 | | `app_id` | String | 必选 | 32 | 开发者的 app_id,支付宝分配给开发者的应用 APPID。 | - | 2014072300007148 | | `auth_app_id` | String | 必选 | 32 | 开发者的 app_id,在服务商调用场景下为授权方的 app_id。 | - | 2014072300007148 | | `out_trade_no` | String | 必选 | 64 | 商户订单号。 | - | 6823789339978248 | | `out_biz_no` | String | 可选 | 64 | 商家业务号,主要是退款通知中返回退款申请的流水号。 | - | HZRF001 | | `buyer_id` / `buyer_open_id` | String | 可选 | 128 | 买家支付宝用户号或买家支付宝 open_id。 | 新商户建议使用 `buyer_open_id` 替代 `buyer_id`。如使用 open_id,请确认“应用-开发配置-openid 配置管理”已启用。 | - | | `buyer_logon_id` | String | 可选 | 100 | 买家支付宝账号。 | - | 180****0062 | | `seller_id` | String | 可选 | 30 | 卖家支付宝用户号。 | - | 2088101106499364 | | `seller_email` | String | 可选 | 100 | 卖家支付宝账号。 | - | zhuzhanghu@alitest.com | | `trade_status` | String | 必选 | 32 | 交易状态,交易目前所处的状态。 | 取值见“交易状态说明”。 | TRADE_CLOSED | | `total_amount` | Number | 必选 | 11 | 订单金额,本次交易支付的订单金额,单位为元。 | 支持小数点后两位。 | 20 | | `receipt_amount` | Number | 必选 | 11 | 实收金额,商家在交易中实际收到的款项,单位为元。 | 支持小数点后两位。 | 15 | | `invoice_amount` | Number | 可选 | 11 | 开票金额,用户在交易中支付的可开发票金额。 | 支持小数点后两位。 | 10.00 | | `buyer_pay_amount` | Number | 可选 | 11 | 付款金额,用户在交易中支付的金额。 | 支持小数点后两位。 | 13.88 | | `point_amount` | Number | 可选 | 11 | 集分宝金额,使用集分宝支付的金额。 | 支持小数点后两位。 | 12.00 | | `refund_fee` | Number | 可选 | 11 | 总退款金额。退款通知中返回总退款金额,单位为元。 | 支持小数点后两位。 | 2.58 | | `send_back_fee` | Number | 可选 | 11 | 实际退款金额,商家实际退款给用户的金额,单位为元。 | 支持小数点后两位。 | 2.08 | | `subject` | String | 可选 | 256 | 订单标题,商品标题、交易标题、订单标题或订单关键字等。 | 对应请求时的参数,会在通知中原样返回。 | XXX交易 | | `body` | String | 可选 | 400 | 商品描述,订单备注、描述或明细等。 | 对应请求时的 `body` 参数,会在通知中原样返回。 | XXX交易内容 | | `passback_params` | String | 可选 | 512 | 公共回传参数。 | 如果请求时传递该参数,则异步通知会原样返回。本参数必须先进行 UrlEncode 后再发送给支付宝。 | - | | `gmt_create` | Date | 可选 | - | 交易创建时间,格式为 `yyyy-MM-dd HH:mm:ss`。 | - | 2015-04-27 15:45:57 | | `gmt_payment` | Date | 可选 | - | 交易付款时间,格式为 `yyyy-MM-dd HH:mm:ss`。 | - | 2015-04-27 15:45:57 | | `gmt_refund` | Date | 可选 | - | 交易退款时间,格式为 `yyyy-MM-dd HH:mm:ss.SS`。 | - | 2015-04-28 15:45:57.320 | | `gmt_close` | Date | 可选 | - | 交易结束时间,格式为 `yyyy-MM-dd HH:mm:ss`。 | - | 2015-04-29 15:45:57 | | `fund_bill_list` | String | 可选 | 512 | 支付金额信息,支付成功的各个渠道金额信息。 | 字段说明见“资金明细信息说明”。 | `[{"amount":"15.00","fundChannel":"ALIPAYACCOUNT"}]` | | `voucher_detail_list` | String | 可选 | - | 优惠券信息,本交易支付时所使用的所有优惠券信息。 | 字段说明见“优惠券信息说明”。 | `[{"amount":"0.20","merchantContribute":"0.00","name":"一键创建券模板的券名称","otherContribute":"0.20","type":"ALIPAY_BIZ_VOUCHER","memo":"学生8折优惠"}]` | #### 交易状态说明 | 枚举名称 | 枚举说明 | | --- | --- | | `WAIT_BUYER_PAY` | 交易创建,等待买家付款。 | | `TRADE_CLOSED` | 未付款交易超时关闭,或支付完成后全额退款。 | | `TRADE_SUCCESS` | 交易支付成功。 | | `TRADE_FINISHED` | 交易结束,不可退款。 | #### 通知触发条件 | 触发条件名 | 触发条件描述 | 触发条件默认值 | | --- | --- | --- | | `TRADE_FINISHED` | 交易完成 | `true`(触发通知) | | `TRADE_SUCCESS` | 支付成功 | `true`(触发通知) | | `TRADE_CLOSED` | 交易关闭 | `true`(触发通知) | | `WAIT_BUYER_PAY` | 交易创建 | `false`(不触发通知) | #### 资金明细信息说明 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `fundChannel` | String | 可选 | - | 支付渠道。 | 详情可查看[支付渠道说明](https://ideservice.alipay.com/cms/site/009zkj)。 | ALIPAYACCOUNT | | `amount` | String | 可选 | 11 | 支付金额,使用指定支付渠道支付的金额,单位为元。 | - | 15.00 | #### 优惠券信息说明 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `voucherId` | String | 必选 | 32 | 券 ID。 | - | 2015102600073002039000002D5O | | `templateId` | String | 可选 | 64 | 券模板 ID。 | - | 20171030000730015359000EMZP0 | | `name` | String | 必选 | 64 | 券名称。 | - | 5 元代金券 | | `type` | String | 必选 | 32 | 优惠类型。 | `ALIPAY_BIZ_VOUCHER`:商家全场券;`ALIPAY_COMMON_ITEM_VOUCHER`:商家单品券;`ALIPAY_CASH_VOUCHER`:平台优惠券,支付宝或第三方出资;`ALICREDIT_INTFREE_VOUCHER`:花呗分期券,仅做订单外的花呗分期费用减免,不抵扣订单内支付金额。未来可能新增其他类型,商家接入时应注意兼容,避免硬编码。 | ALIPAY_BIZ_VOUCHER | | `amount` | Number | 必选 | 11 | 优惠金额。 | 优惠金额中由商家出资的金额。 | 10.00 | | `merchantContribute` | Number | 可选 | 11 | 商家出资金额。 | 优惠金额中由商家出资的金额。 | 9.00 | | `otherContribute` | Number | 可选 | 11 | 其他出资方出资金额。 | 可能是支付宝、品牌商、其他方,或多方共同出资。 | 1.00 | | `otherContributeDetail` | ContributeDetail[] | 可选 | - | 优惠券的其他出资方明细。 | 子字段见下方 `otherContributeDetail[]`。 | - | | `otherContributeDetail[].contributeType` | String | 可选 | 32 | 出资方类型。 | 如品牌商出资、支付宝平台出资等。 | PLATFORM | | `otherContributeDetail[].contributeAmount` | Number | 可选 | 8 | 出资方金额。 | - | 0.18 | | `memo` | String | 可选 | 256 | 优惠券备注信息。 | - | 学生专用优惠 | #### 异步通知特性 1. 在进行异步通知交互时,如果支付宝收到的应答不是 `success`,支付宝会认为通知失败,并通过一定策略定期重新发起通知。通知间隔频率为:`4m`、`10m`、`10m`、`1h`、`2h`、`6h`、`15h`。 2. 商家设置的异步通知地址 `notify_url` 需保证无任何多余字符,如空格、HTML 标签,且不能重定向。若发生重定向,支付宝会收不到 `success` 字符,可能判定页面程序运行异常并重新发送通知。 3. 支付宝使用 POST 方式发送通知信息,商户可通过 `request.Form("out_trade_no")`、`$_POST['out_trade_no']` 等方式获取参数。 4. 支付宝针对同一条异步通知重试时,异步通知参数中的 `notify_id` 不变。 #### 异步返回结果验签 某商家设置的通知地址为 `https://api.xx.com/receive_notify.htm`,对应接收到通知的示例如下。 注意:以下示例报文仅供参考,实际返回的详细报文请以实际返回为准。 ```text https://api.xx.com/receive_notify.htm?gmt_payment=2015-06-11 22:33:59¬ify_id=42af7baacd1d3746cf7b56752b91edcj34&seller_email=testyufabu07@alipay.com¬ify_type=trade_status_sync&sign=kPbQIjX+xQc8F0/A6/AocELIjhhZnGbcBN6G4MM/HmfWL4ZiHM6fWl5NQhzXJusaklZ1LFuMo+lHQUELAYeugH8LYFvxnNajOvZhuxNFbN2LhF0l/KL8ANtj8oyPM4NN7Qft2kWJTDJUpQOzCzNnV9hDxh5AaT9FPqRS6ZKxnzM=&trade_no=2015061121001004400068549373&out_trade_no=21repl2ac2eOutTradeNo322&gmt_create=2015-06-11 22:33:46&seller_id=2088211521646673¬ify_time=2015-06-11 22:34:03&subject=FACE_TO_FACE_PAYMENT_PRECREATE中文&trade_status=TRADE_SUCCESS&sign_type=RSA2 ``` 验签步骤如下: 1. 在通知返回参数列表中,除去 `sign`、`sign_type` 两个参数外,通知返回的参数均为待验签参数。 2. 将剩余参数进行 `URLDecode`,然后按字典排序组成字符串,得到待签名字符串: ```text gmt_create=2015-06-11 22:33:46&gmt_payment=2015-06-11 22:33:59¬ify_id=42af7baacd1d3746cf7b56752b91edcj34¬ify_time=2015-06-11 22:34:03¬ify_type=trade_status_sync&out_trade_no=21repl2ac2eOutTradeNo322&seller_email=testyufabu07@alipay.com&seller_id=2088211521646673&subject=FACE_TO_FACE_PAYMENT_PRECREATE中文&trade_no=2015061121001004400068549373&trade_status=TRADE_SUCCESS ``` 3. 将签名参数 `sign` 使用 base64 解码为字节码串。 4. 使用 RSA 验签方法,通过签名字符串、签名参数(经过 base64 解码)及支付宝公钥验证签名。 5. 在步骤四验证签名正确后,必须再严格校验通知数据的正确性: | 校验项 | 校验说明 | | --- | --- | | `out_trade_no` | 校验通知数据中的 `out_trade_no` 是否为商家系统中创建的订单号。 | | `total_amount` | 判断 `total_amount` 是否确实为该订单的实际金额,即商家订单创建时的金额。 | | `seller_id` / `seller_email` | 校验通知中的 `seller_id` 或 `seller_email` 是否为 `out_trade_no` 这笔单据的对应操作方。 | | `app_id` | 验证 `app_id` 是否为该商家本身。 | 上述任一校验项不通过,则表明本次通知是异常通知,务必忽略。 上述校验通过后,商家必须根据支付宝不同类型的业务通知进行业务处理,并过滤重复通知结果数据。在支付宝的业务通知中,只有交易通知状态为 `TRADE_SUCCESS` 或 `TRADE_FINISHED` 时,支付宝才会认定为买家付款成功。 SDK 接收以及验签示例代码如下。此处以 Java 语言为例,按照服务端 SDK 中提供的工具类,注意区分公钥和公钥证书验签代码。 ```java // 获取支付宝 POST 过来反馈信息,将异步通知中收到的待验证所有参数都存放到 map 中。 Map params = new HashMap(); Map requestParams = request.getParameterMap(); for (Iterator iter = requestParams.keySet().iterator(); iter.hasNext();) { String name = (String) iter.next(); String[] values = (String[]) requestParams.get(name); String valueStr = ""; for (int i = 0; i < values.length; i++) { valueStr = (i == values.length - 1) ? valueStr + values[i] : valueStr + values[i] + ","; } // 乱码解决,这段代码在出现乱码时使用。 // valueStr = new String(valueStr.getBytes("ISO-8859-1"), "utf-8"); params.put(name, valueStr); } // 调用 SDK 验证签名。 // 公钥验签示例代码: boolean signVerified = AlipaySignature.rsaCheckV1(params, ALIPAY_PUBLIC_KEY, CHARSET, sign_type); // 公钥证书验签示例代码: // boolean flag = AlipaySignature.rsaCertCheckV1(params, alipayPublicCertPath, "UTF-8", "RSA2"); if (signVerified) { // TODO 验签成功后,按照支付结果异步通知中的描述,对支付结果中的业务内容进行 1/2/3/4 二次校验。 // 校验成功后在 response 中返回 success。 } else { // TODO 验签失败则记录异常日志,并在 response 中返回 fail。 } ``` 注意: - 状态 `TRADE_SUCCESS` 的通知触发条件是:商家开通的产品支持退款功能的前提下,买家付款成功。 - 交易状态 `TRADE_FINISHED` 的通知触发条件是:商家开通的产品不支持退款功能的前提下,买家付款成功;或者商家开通的产品支持退款功能的前提下,交易已经成功并且已经超过可退款期限。 #### 响应值 | 响应值 | 描述 | 异步是否重试发送 | | --- | --- | --- | | `fail` | 消息获取失败 | 重试 | | `success` | 消息获取成功 | 不重试 | #### 异步通知触发时机和通知参数说明 注意:如果签约不支持退款,或者定制了异步通知的触发条件和通知字段,则本节说明不适用。 在交易支付成功、交易关单、交易退款、交易分账等场景下都可能触发异步通知。各场景的关键通知参数区分如下: | 场景 | 通知参数特征 | | --- | --- | | 用户支付成功通知 | `trade_status=TRADE_SUCCESS`,且不包含 `out_biz_no` 字段。 | | 退款成功通知 | 通知参数包含 `gmt_refund`、`refund_fee`、`out_biz_no` 字段,其中 `out_biz_no` 为退款请求号。 | | 交易未支付超时关单通知 | 通知参数包含 `gmt_close`、`refund_fee` 字段,其中 `refund_fee=0`、`trade_status=TRADE_CLOSED`。如果用户在收银台没有点击过提交支付,则不会真正创建交易,该场景下不会有未支付超时关单通知。 | | 交易分账成功通知 | 通知参数包含 `out_biz_no` 字段,其中 `out_biz_no` 为分账请求号。 | --- ### 同步返回说明 目录路径:Vibe Pay · AI应用收款 > 基础收款能力-AI移动应用收款 > API列表 > 同步返回说明 来源:https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/ai-app-pay/sync-result.md 同步通知说明 #### 使用说明 支付宝 SDK 对商家的请求支付数据处理完成后,会将结果同步反馈给商家 App 端。 注意:同步返回的数据,商家可以按照下文描述的方式在服务端验证。验证通过后,可以认为本次用户付款成功。有些时候会出现商家 App 在支付宝付款阶段被关闭、导致无法正确收到同步结果的情况,此时支付结果可以通过服务端异步通知获取。为了简化集成流程,商家可以将同步结果仅作为一个支付结束通知,实际支付是否成功以服务端异步通知为准。 #### 回调返回方法 - iOS:参考 [iOS 集成流程](https://ideservice.alipay.com/cms/site/0izcsf) 的配置返回 URL 处理方法打印输出回调信息。对于 iOS 平台而言,返回参数是一个 `NSDictionary` 对象。 - Android:参考 [Android 集成流程](https://ideservice.alipay.com/cms/site/0izcsg) 中“支付结果获取和处理”的同步返回打印输出回调信息。对于 Android 平台而言,返回参数是一个 map 结构体。 #### 返回结果示例 同步返回的回调信息包含 3 个 key: - `memo`:描述信息,类型为字符串。 - `result`:处理结果,类型为 JSON 结构字符串。 - `resultStatus`:结果码,类型为字符串。 ```json { "memo": "xxxxx", "result": "{ \"alipay_trade_app_pay_response\": { \"code\": \"10000\", \"msg\": \"Success\", \"app_id\": \"2014072300007148\", \"out_trade_no\": \"081622560194853\", \"trade_no\": \"2016081621001004400236957647\", \"total_amount\": \"9.00\", \"seller_id\": \"2088702849871851\", \"charset\": \"utf-8\", \"timestamp\": \"2016-10-11 17:43:36\" }, \"sign\": \"NGfStJf3i3ooWBuCDIQSumOpaGBcQz+aoAqyGh3W6EqA/gmyPYwLJ2REFijY9XPTApI9YglZyMw+ZMhd3kb0mh4RAXMrb6mekX4Zu8Nf6geOwIa9kLOnw0IMCjxi4abDIfXhxrXyj********\", \"sign_type\": \"RSA2\" }", "resultStatus": "9000" } ``` #### result 返回参数说明 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `out_trade_no` | String | 必选 | 64 | 商家网站唯一订单号。 | 70501111111S001111119 | | `trade_no` | String | 必选 | 64 | 该交易在支付宝系统中的交易流水号。 | 2014112400001000340011111118 | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 APPID。 | 2014072300007148 | | `total_amount` | Price | 必选 | 11 | 该笔订单的资金总额,单位为 RMB-Yuan。取值范围 `[0.01, 100000000.00]`,精确到小数点后两位。 | 9.00 | | `seller_id` | String | 必选 | 16 | 收款支付宝账号对应的支付宝唯一用户号,以 2088 开头的纯 16 位数字。 | 20886894 | | `msg` | String | 必选 | 16 | 处理结果的描述,信息来自于 `code` 返回结果的描述。 | success | | `charset` | String | 必选 | 16 | 编码格式。 | utf-8 | | `timestamp` | String | 必选 | 32 | 时间。 | 2016-10-11 17:43:36 | | `code` | String | 必选 | 16 | 结果码,详情可查看[公共错误码](https://ideservice.alipay.com/cms/site/02km9f)。 | 10000 | #### resultStatus 结果码含义 | 返回码 | 含义 | | --- | --- | | `9000` | 订单支付成功。 | | `8000` | 正在处理中,支付结果未知,有可能已经支付成功。请查询商家订单列表中订单的支付状态。 | | `4000` | 订单支付失败。 | | `5000` | 重复请求。 | | `6001` | 用户中途取消。 | | `6002` | 网络连接出错。 | | `6004` | 支付结果未知,有可能已经支付成功。请查询商家订单列表中订单的支付状态。 | | 其它 | 其它支付错误。 | #### 同步通知验证 为了帮助开发者调用开放接口,支付宝提供了[开放平台服务端 DEMO&SDK](https://ideservice.alipay.com/cms/site/02no46),包含 Java、PHP、Python、NodeJS 和 .NET 五种语言版本,封装了签名、验签、HTTP 接口请求等基础功能。强烈建议先下载对应语言版本的 SDK 并引入开发工程进行快速接入。 若未使用支付宝 SDK,可按以下步骤完成同步通知验签: 1. 在返回数据 `resultStatus` 为 `9000` 的情况下,解析 `result` 结果进行[同步返回验签](https://ideservice.alipay.com/cms/site/02mse7)。 2. 提取 `alipay_trade_app_pay_response` 字段值,其代表签名原始字符串,示例如下: ```json { "code": "10000", "msg": "Success", "app_id": "2014072300007148", "out_trade_no": "081622560194853", "trade_no": "2016081621001004400236957647", "total_amount": "9.00", "seller_id": "2088702849871851", "charset": "utf-8", "timestamp": "2016-10-11 17:43:36" } ``` 3. 提取 `sign_type` 字段值,其代表签名类型,示例如下: ```text RSA2 ``` 4. 提取 `sign` 字段值,其代表签名结果,示例如下: ```text NGfStJf3i3ooWBuCDIQSumOpaGBcQz+aoAqyGh3W6EqA/gmyPYwLJ2REFijY9XPTApI9YglZyMw+ZMhd3kb0mh4RAXMrb6mekX4Zu8Nf6geOwIa9kLOnw0IMCjxi4abDIfXhxrXyj******** ``` 5. 验证签名是否合法。使用各自语言对应的 SHA256WithRSA 签名验证函数,传入签名原始字符串、支付宝公钥、签名类型 RSA、签名字符进行合法性验证。 6. 在签名验证通过后,必须严格按照如下描述校验通知参数的合法性: | 校验项 | 校验说明 | | --- | --- | | `out_trade_no` | 校验该通知数据中的 `out_trade_no` 是否为商家系统中创建的订单号。 | | `total_amount` | 判断 `total_amount` 是否确实为该订单的实际金额,即商家订单创建时的金额。 | | `seller_id` / `seller_email` | 校验通知中的 `seller_id` 或 `seller_email` 是否为 `out_trade_no` 这笔单据对应的操作方。 | | `app_id` | 验证 `app_id` 是否为该商家本身。 | 上述任一校验项不通过,则表明同步校验结果无效。只有全部验证通过后,才可以认定买家付款成功。 #### 客户端报错处理方案 商家客户端唤起支付宝客户端后,支付宝客户端中可能弹窗提示“支付失败”等报错信息。 ##### 系统交互流程 ```mermaid sequenceDiagram actor 用户 participant 商户客户端 participant 支付宝AppSDK as 支付宝 app SDK participant 支付宝服务端 participant 商户服务端 用户->>商户客户端: 1. 使用支付宝付款 商户客户端->>商户服务端: 2. 请求商户服务端,获取签名后的订单信息 商户服务端-->>商户客户端: 3. 返回签名后的订单信息 商户客户端->>支付宝AppSDK: 4. 调用 alipay.trade.app.pay 接口唤起支付宝 app 支付宝AppSDK->>支付宝服务端: 5. 支付请求 支付宝服务端->>支付宝服务端: 6. 验签以及其他处理 rect rgb(255, 240, 240) Note left of 用户: ATL 验签或参数校验失败 支付宝服务端->>支付宝AppSDK: 7. 返回错误信息 支付宝AppSDK->>用户: 8. 弹窗提示错误信息 用户->>支付宝AppSDK: 9. 点击确认按钮,关闭支付宝 app end 支付宝AppSDK->>商户客户端: 10. 返回详细错误信息 ``` ##### 错误信息格式样例 ![错误信息格式样例](https://gw.alipayobjects.com/zos/skylark-tools/public/files/ea95904c8c74165bcd9d051493a6fde2.png) ##### result 错误处理方案 当 `resultStatus` 返回非 `9000` 状态,且 `result` 返回的 `sub_code` 和 `sub_msg` 含有具体错误原因时,可查看 [alipay.trade.app.pay(App 支付接口 2.0 接口)](https://ideservice.alipay.com/cms/site/02e7gq)错误码进行排查和解决。如在开发过程中碰到其他问题,可以在[文档中心](https://opendocs.alipay.com/home)搜索查找相关问题。 注意:部分报错没有显示具体报错信息,例如 `{resultStatus=6001, result=, memo=用户取消}`,无法判断是用户取消支付导致还是报错导致,建议按照客户端页面显示的报错信息进行查询定位。 常见报错信息及解决方案如下: | 客户端报错 | 解决方案 | | --- | --- | | 商家订单参数异常,请尝试返回后重新付款或联系商家确认 | 可能原因包括:请求 APPID 应用未上线;应用类型为第三方应用;未开通 App 支付或未添加 App 支付功能包;`sign_type` 填写错误,必须为 `RSA2`;签名方式使用错误,若应用接口加签方式为公钥证书,则代码必须为证书模式加签(含 `app_cert_sn` 和 `alipay_root_cert_sn`),若接口加签方式为公钥,则代码必须为普通公钥加签;请求参数问题,建议只传必传参数测试核实(沙箱调试客户端请开启沙箱联调代码);代码中设置的私钥和应用中上传的应用公钥不匹配。 | | 卖家账户状态异常,请联系卖家解决。(T1) | 商家收款账号存在异常,建议商家拨打联系电话 `4007585858` 处理。 | | 系统繁忙,请稍后再试 | 请按照[常见问题](https://ideservice.alipay.com/cms/site/0izct7)中客户端返回具体报错定位。 | | 订单已付款成功,请勿重复提交。(ALIN42279) | 该笔订单已支付完成,不可使用相同的商家订单号再次发起请求。 | | 花呗分期暂不可用,请更换付款方式 | 可能原因包括:用户尚未开通花呗或花呗可用额度不足;花呗分期额度过小或超支,建议设置 200 元测试;收款账号未开通花呗分期协议或接口不支持花呗分期收款;账号存在风险;接口设置了支付渠道,禁用花呗分期。 | | 订单已超时,请重新下单后再发起付款(ALIN47094) | 接口传入了超时参数,未在交易超时前支付,建议更换新的订单号 `out_trade_no` 重新请求。 | --- ### 产品介绍 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 产品介绍 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/nowpay-intro.md #### 智能收款套件产品介绍 ##### 产品特色 智能收款套件是 Vibe Pay 面向 AI 创作者提供的一种快速商业化模式。套件将下单支付、订单管理、权益管理等支付及关联能力组合提供,创作者只需设计应用在什么情况下引导用户付费,并在支付成功后开放相应功能,无需重复建设完整的交易配套。 - **开箱即用的商业闭环:** 下单支付、支付结果处理、订单管理与权益管理等能力内置提供,减少从创意到上线过程中需要自行开发的商业化基础功能。 - **聚焦应用体验:** 创作者主要负责设计付费触发时机及支付成功后的应用功能放行,可以将更多精力投入产品创意和使用体验。 - **保留关键定制空间:** 创作者可自主决定在应用内何时引导支付、售卖什么内容或权益,以及支付成功后开放哪些功能。 - **对 AI 创作者更友好:** 适合希望快速验证创意、降低开发投入,或不熟悉支付系统建设的 AI 创作者。 - **支持网页与移动应用:** 可承接网页应用和移动应用的商业化需求。 - **依托成熟支付能力:** 为应用提供成熟、可靠的收款能力,并通过套件降低支付及其配套能力的接入复杂度。 ##### 产品交互 ###### 收款方配置商品 ::aipay-image{src="https://mdn.alipayobjects.com/aipay_assets/afts/file/9MIHSan80poAAAAAYnAAAAgAeoh5AQJr" width="100%"} 支持多种收费模式: 一次性买断、次数、额度、时长 ::aipay-image{src="https://mass.alipay.com/aipay_assets/afts/file/P-itT4GUBB8AAAAAgDAAAAgAeoh5AQJr" width="100%"} ###### 消费方购买商品 ::aipay-image{src="https://mdn.alipayobjects.com/aipay_assets/afts/file/UoAgT4mGeVsAAAAAgBAAAAgAeoh5AQJr" width="100%"} 无需研发,用户跳转支付宝支付时,自动根据商品的收费模式渲染适配的支付页面 ::aipay-image{src="https://mass.alipay.com/aipay_assets/afts/file/a123S4rfRSIAAAAAgDAAAAgAeoh5AQJr" width="100%"} ##### 典型场景 智能收款套件适用于希望快速为 AI 应用增加付费能力,同时不希望自行开发订单和权益管理等商业化基础设施的创作者。 ###### 快速验证 AI 应用商业模式 适合通过 AI 创作平台或自然语言编程平台完成应用开发,希望快速加入付费环节、验证市场需求的创作者。创作者可直接使用合作平台提供的智能收款套件,将开发重心放在应用功能和用户体验上。 ###### 网页与移动应用商业化 支持创作者为网页应用或移动应用接入收款能力。创作者负责定义应用内的付费触发点,智能收款套件承接下单支付、支付结果处理及相关交易管理。 ###### 多种收费模式 智能收款套件可用于多种应用商业场景,包括: - **一次性买断:** 用户一次付费后,获得工具、内容或功能的长期使用权。 - **次数包:** 用户购买固定次数,用于生成、导出、分析等按次消耗的应用功能。 - **积分包:** 用户购买积分,并使用积分兑换或消耗不同的应用功能。 - **时长包:** 用户购买一定时间范围内的应用使用权,例如购买 1 个月使用权。 ##### 商业化基础设施 智能收款套件将应用商业化所需的核心能力组合提供: - **下单支付:** 承接应用内的下单、支付及支付结果处理。 - **订单管理:** 内置订单查询、订单状态及订单信息管理能力。 - **权益管理:** 根据支付结果及配置规则发放、暂停或回收应用权益,并支持支付成功后开放相应功能。 ##### 准入条件 1、支持的账号类型: [支付宝个人账号](https://opendocs.alipay.com/common/02kg61) 、 [支付宝企业账号](https://opendocs.alipay.com/common/02kkum) 2、接入方式:智能收款套件支持创作者通过合作平台接入 或者 独立接入 **通过合作平台接入** 已合作平台包括 - 灵光 - 观猹([前往了解](https://pay.watcha.cn/)) - WeaveFox([前往了解](https://www.weavefox.cn/extensions/services/vibe-pay)) - QMuse([前往了解](https://www.qmuse.cn/home/skill/yoz8oenxlkes)) 创作者可前往上述合作平台了解具体接入方式。 有意向提供智能收款套件的平台,可提交合作申请,[申请成为合作平台](https://render.alipay.com/p/yuyan/180022670000179729/index.html?type=platform)。 **创作者独立接入** 创作者独立接入已定向开放,申请获批加入白名单后方可接入。 可前往 [接入指南](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/nowpay-direct.html) ##### 结算 **收款账户**:默认收款到签约账号的支付宝余额账户,实时到账 :aipay-text[**注意**:]{color="#ff4d4f"}根据相关规定,如果是首次签约收单产品且未满 90 日或连续交易未满 30 日的商家,收款的资金都将于次日结算到收款账户 ##### 费率 智能收款套件的费率由收单产品( [JSAPI支付](https://opendocs.alipay.com/mini/053llc?pathHash=d81d3a2a) )和 即刻收商品经营 组成。 | 产品 | 费率 | | --- | --- | | JSAPI支付 | 0.6%~1%。[费率说明](https://opendocs.alipay.com/mini/053llc?pathHash=d81d3a2a#5%20%E8%AE%A1%E8%B4%B9%E6%A8%A1%E5%BC%8F)| | 即刻收商品经营 | 0.4% | ##### 开通和接入流程 ###### 创作者接入 1. 选择已接入智能收款套件的合作平台。 2. 在合作平台创建或入驻应用。 3. 按合作平台提供的流程配置应用的付费触发条件、售卖内容或权益。 4. 使用平台提供的下单支付、订单管理和权益管理能力完成应用商业化。 创作者独立接入已定向开放,申请获批加入白名单后方可接入,详见[接入指南](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/nowpay-direct.html)。 ###### 平台接入 --- ### 接入指南 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > 接入指南 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/platfrom-guide.md vibe pay智能收款套件(即刻收)平台接入指南 #### 适用场景 即刻收面向承载创作者、应用或数字服务的平台,提供收费配置、托管购买、权益查询和额度核销能力。平台通过支付宝 OpenAPI 为创作者接入收费:创作者在支付宝托管页完成收费配置,用户在托管购买页支付,平台服务端根据权益或核销结果开放服务。 ##### 支持的收费模式 | 收费模式 | billing_mode | 权益或额度 | 平台使用方式 | 重复购买 | | --- | --- | --- | --- | --- | | 永久买断 | `ONE_TIME` | 永久使用权益 | 使用前查询访问决策 | 已有有效权益时不再购买 | | 时长包 | `ONE_TIME_DURATION` | 固定有效期权益 | 使用前查询访问决策,可展示有效期 | 有效期内不续购;到期后按查询结果购买 | | 次数包 | `QUANTITY`,`quota_unit=COUNT` | 可消耗次数 | 查询余额,每次服务按约定数量核销 | 可加购,新增额度累加 | | 积分包 | `QUANTITY`,`quota_unit=POINT` | 可消耗积分 | 查询余额,按服务规则核销积分 | 可加购,新增额度累加 | 同一商品最终采用一种收费模式,该模式下可配置多个档位。例如,次数包可提供“20 次包”和“100 次包”,用户购买后增加相应次数。 时长包支持以下周期,按日历计算,不能将“一个月”固定换算成 30 天: | duration_period | 对客名称 | 计算口径 | | --- | --- | --- | | `WEEK` | 一周 | 按日历增加 1 周 | | `MONTH` | 一个月 | 按日历增加 1 个月 | | `QUARTER` | 三个月 | 按日历增加 3 个月 | | `YEAR` | 一年 | 按日历增加 1 年 | 本接入范围支持买断、固定周期时长包和次数/积分额度包,不包含自动续费、任意天数、有效期内时长续购、商品改价、核销撤销。 #### 接入准备 ##### 平台与支付宝的职责 | 参与方 | 负责内容 | | --- | --- | | 平台服务端 | 维护商品、创作者及用户标识;签名调用接口;保存幂等请求;根据权益与核销结果控制服务 | | 平台客户端 | 展示收费状态、档位和余额;打开接口返回的托管页面或展示二维码;页面返回后触发服务端查询 | | 创作者 | 在支付宝托管页完成所需账号绑定、收费模式与档位配置,管理商品收费状态 | | 即刻收 | 提供配置和购买入口、支付与权益处理、权益查询及额度扣减结果 | ##### 开始前完成以下准备 1. 准备平台的支付宝应用 `app_id`、应用私钥和对应支付宝公钥,并完成所需接口权限及平台接入配置。 2. 在平台服务端接入支付宝服务端 SDK,配置签名与验签。请求网关为 `https://openapi.alipay.com/gateway.do`,API 版本为 `1.0`,推荐使用 `RSA2`、`UTF-8` 和 JSON。 3. 确定商品、创作者和权益受益人的稳定标识,建立商品归属与平台登录用户的对应关系。 OpenAPI 凭证保存在平台服务端。平台服务端根据已登录用户及商品归属确定身份参数,不能直接信任客户端任意传入的创作者或受益人标识。 #### 手动集成 ##### 第一步:为创作者配置收费 ###### 系统流程 ```mermaid sequenceDiagram autonumber participant C as 创作者 participant P as 平台 participant N as 即刻收 OpenAPI participant H as 支付宝托管配置页 C->>P: 进入商品收费设置 P->>N: alipay.aipay.nowpay.charge.query N-->>P: capability_status / management_url alt NOT_CONFIGURED 或 CONFIGURING P->>N: alipay.aipay.nowpay.charge.initialize N-->>P: configuration_url / configuration_qr_code P-->>C: 展示配置入口 C->>H: 打开配置页并完成收费设置 H-->>P: 返回 callback_url else 已配置状态 P-->>C: 展示 management_url C->>H: 进入商品管理 end P->>N: alipay.aipay.nowpay.charge.query N-->>P: 最新状态、收费模式与档位 ``` 1. 调用 [alipay.aipay.nowpay.charge.query(查询收费能力和档位)](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/charge_query.md),传入平台商品和创作者标识。 2. 当 `capability_status` 为 `NOT_CONFIGURED` 或 `CONFIGURING` 时,调用 [alipay.aipay.nowpay.charge.initialize(初始化收费配置)](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/charge_init.md),使用返回的配置链接或二维码引导创作者完成设置。 3. 当状态为 `PENDING`、`ACTION_REQUIRED`、`ENABLED`、`DISABLED` 或 `TERMINATED` 时,使用查询返回的 `management_url` 进入管理页,查看进度或处理商品。 4. 页面返回或创作者主动刷新时,再次查询收费能力。只有 `ENABLED` 表示商品允许新增购买。 初始化请求的 `biz_content` 示例: ```json { "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "product_name": "智能写作助手", "product_icon_url": "https://platform.example.com/assets/writing.png", "product_url": "https://platform.example.com/apps/app_writing_001", "callback_url": "https://platform.example.com/nowpay/config-return", "pricing_mode_list": [ { "billing_mode": "QUANTITY", "quota_unit": "COUNT" } ] } ``` 本例提示配置次数包。初始化不传价格;创作者在托管页选择收费方式并配置档位。商品配置成功后,平台从 `alipay.aipay.nowpay.charge.query` 读取实际 `billing_mode`、`quota_unit`、`charging_options`。 若重复初始化返回 `NOW_PAY_ALREADY_CONFIGURED`,调用 `alipay.aipay.nowpay.charge.query` 获取管理入口。不要依赖失败响应返回链接,也不要将初始化成功当作商品已经上架。 ###### 收费状态与页面处理 | capability_status | 商品含义 | 平台页面处理 | | --- | --- | --- | | `NOT_CONFIGURED` | 尚未初始化 | 展示“设置收费”,点击后调用初始化接口 | | `CONFIGURING` | 配置尚未完成 | 展示“继续配置”,复用原申请进入配置页 | | `PENDING` | 等待审核或发布 | 使用管理入口查看进度 | | `ACTION_REQUIRED` | 需要创作者处理 | 使用管理入口完成处理 | | `ENABLED` | 允许新增购买 | 展示用户购买入口与商品管理入口 | | `DISABLED` | 已停止新增购买 | 隐藏新购买入口;已有权益继续按权益接口判断 | | `TERMINATED` | 商品已归档 | 使用管理入口查看状态,不新增购买 | 商品收费状态与某个用户的权益状态分别查询。商品已停用不能直接推断用户已有权益失效;商品已启用也不能直接推断用户已有访问权限。 ##### 第二步:按收费模式选择流程 | billing_mode | 使用前查询 | 需要购买时 | 支付页面返回后 | 实际消费时 | | --- | --- | --- | --- | --- | | `ONE_TIME` | alipay.aipay.nowpay.purchase.consult | 使用 alipay.aipay.nowpay.purchase.consult 返回的购买入口,或通过 alipay.aipay.nowpay.purchase.create 选择指定档位 | 再查 alipay.aipay.nowpay.purchase.consult | 按访问决策放行 | | `ONE_TIME_DURATION` | alipay.aipay.nowpay.purchase.consult | 同上 | 再查 alipay.aipay.nowpay.purchase.consult,读取当前有效期 | 按访问决策放行 | | `QUANTITY` | alipay.aipay.nowpay.quota.query | alipay.aipay.nowpay.purchase.create | 再查 alipay.aipay.nowpay.quota.query | alipay.aipay.nowpay.quota.verify;结果未知用 alipay.aipay.nowpay.quota.refresh | ###### 买断和时长包 ```mermaid sequenceDiagram autonumber participant U as 用户 participant P as 平台 participant N as 即刻收 OpenAPI participant H as 支付宝托管购买页 U->>P: 使用付费功能 P->>N: alipay.aipay.nowpay.purchase.consult N-->>P: decision alt ALLOW P-->>U: 开放服务 else PURCHASE_REQUIRED P-->>U: 展示购买入口 U->>H: 选择档位并支付 H-->>P: 返回 callback_url P->>N: alipay.aipay.nowpay.purchase.consult N-->>P: 最新 decision P-->>U: 按查询结果开放服务或提示刷新 else DENY P-->>U: 不开放服务,按原因展示说明 end ``` 调用 [alipay.aipay.nowpay.purchase.consult(查询买断或时长访问决策)](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/purchase_consult.md),业务入参示例: ```json { "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001", "callback_url": "https://platform.example.com/nowpay/purchase-return" } ``` | decision | 平台操作 | | --- | --- | | `ALLOW` | 放行。时长包按返回的 `valid_from`、`valid_until` 展示有效期 | | `PURCHASE_REQUIRED` | 使用返回的 `purchase_url` 或 `purchase_qr_code` 引导购买 | | `DENY` | 不放行、不新建购买入口;根据 `reason_code` 展示说明或刷新 | 时长包权益区间为 `[valid_from, valid_until)`,在结束时间点失效。有效权益存在时,不引导用户重复购买。购买返回后仍需重新查询,只有新的 `decision=ALLOW` 才开放服务。 若支付页面返回后权益暂未可用,可进行有限次查询并提示稍后刷新。不要因暂未查到权益而直接认定支付失败、自动再次支付或重复开放服务。 ###### 次数包和积分包 ```mermaid sequenceDiagram autonumber participant U as 用户 participant P as 平台 participant N as 即刻收 OpenAPI participant H as 支付宝托管购买页 P->>N: alipay.aipay.nowpay.quota.query N-->>P: quota_unit / total / used / remaining P->>P: 按服务规则计算所需额度 opt 额度不足或用户主动加购 P->>N: alipay.aipay.nowpay.purchase.create N-->>P: purchase_url / expire_time U->>H: 确认购买并支付 H-->>P: 返回 callback_url P->>N: alipay.aipay.nowpay.quota.query N-->>P: 最新余额 end P->>P: 持久化消费请求号及业务参数 Note over P,N: 平台按约定的服务交付时点发起正式核销 P->>N: alipay.aipay.nowpay.quota.verify N-->>P: 核销状态或业务错误 opt 处理中、超时或结果未知 P->>N: alipay.aipay.nowpay.quota.refresh(原请求号) N-->>P: 核销结果 end P->>P: 按最终结果更新消费和服务记录 ``` 1. 调用 [alipay.aipay.nowpay.quota.query(查询次数或积分余额)](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/quota_query.md),展示用户的可用余额。未购买时返回零余额。 2. 平台按具体服务规则计算所需额度,例如生成一篇文章消耗 1 次,处理一次复杂任务消耗 10 积分。 3. 额度不足或用户主动加购时,调用 [alipay.aipay.nowpay.purchase.create(获取购买链接)](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/purchase_create.md)。可传入查询得到的 `sku_id` 锁定档位,也可省略,让用户在购买页选择。 4. 用户返回后调用 `alipay.aipay.nowpay.quota.query` 刷新余额。未到账时有限次刷新或提示稍后查询。 5. 在平台确定的服务交付时点,调用 [alipay.aipay.nowpay.quota.verify(核销次数或积分)](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/quota_verify.md)。前置余额充足仍需正式核销,不能仅按余额查询结果执行本地扣减。 6. 对处理中或未知结果,使用原 `out_request_no` 调用 [alipay.aipay.nowpay.quota.refresh(查询核销结果)](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/quota_refresh.md),或用完全相同的原参数重试核销。 指定档位购买的 `biz_content` 示例: ```json { "out_request_no": "purchase_20260907_000001", "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001", "sku_id": "S0806000200863003", "callback_url": "https://platform.example.com/nowpay/purchase-return" } ``` `sku_id` 不指定时打开普通购买页。平台不传价格或价格版本参与创单;即刻收在用户确认购买时重新校验商品和档位。购买链接与二维码按不透明入口使用,不解析令牌,不自行拼接。 ###### 额度核销与恢复示例 以下两组参数对应同一笔消费,查询必须使用核销时的原请求号。次数核销也必须显式传入 `amount=1`。 ::::aipay-tabs{defaultActiveKey="核销额度"} :::aipay-tab{key="核销额度" title="核销额度"} ```json { "out_request_no": "consume_20260907_000001", "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001", "amount": 1, "consume_reason": "生成一篇文章" } ``` ::: :::aipay-tab{key="查询原核销结果" title="查询原核销结果"} ```json { "out_request_no": "consume_20260907_000001", "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001" } ``` ::: :::: `consume_reason` 使用最长 256 字符的业务说明,平台自行持久化。不要填写完整提示词、用户隐私、业务 JSON 等内容,也不要依赖查询结果回传该字段恢复原业务上下文。 | 核销结果 | 是否确认扣减 | 平台处理 | | --- | --- | --- | | `code=10000` 且 `consume_status=SUCCEEDED` | 是 | 保存核销流水、实扣量及结果,按业务约定完成服务记录 | | `code=10000` 且 `consume_status=FAILED` | 否 | 按原因处理;余额不足引导补充额度 | | `code=10000` 且 `consume_status=PROCESSING` | 待确认 | 使用原请求号查询,避免并发重扣 | | `NOW_PAY_QUOTA_INSUFFICIENT` | 本次请求未确认成功 | 处理余额不足,不将网关失败忽略为正常成功 | | 网络超时、系统错误或未知状态 | 待确认 | 保存原请求,查询或原参数重试 | | 核销记录不存在 | 待确认 | 核对请求号与商品,继续查询或原参数重试;不换号重扣 | 平台应同时处理业务错误码和成功响应中的核销状态。`remaining` 仅在成功扣减时用作该笔扣减后的余额;结果查询返回的是原核销结果,需要实时余额时调用 `alipay.aipay.nowpay.quota.query`。 核销与平台自身服务交付是两个动作。平台须根据业务明确先核销还是先交付,并对服务执行、超时恢复、交付失败处理做一致设计。当前能力不提供核销成功后的自动返还,不应将核销当作可自动释放的预占。 ##### 第三步:启停新增购买 调用 [alipay.aipay.nowpay.charge.modify(启停收费能力)](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/charge_modify.md): ```json { "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "action": "DISABLE" } ``` `DISABLE` 停止新增购买,`ENABLE` 恢复新增购买。成功后按 `capability_status` 刷新页面;`changed=false` 表示已处于目标状态。若操作超时,先查询当前状态,再决定是否重试原动作。 停用后原有买断、时长或额度权益仍按对应接口结果处理。此接口不变更价格,也不退款或回收已有权益。 #### 请求与响应处理 ##### 服务端调用 业务参数序列化为 JSON 后放入 `biz_content`,与 `app_id`、`method`、`charset`、`sign_type`、`timestamp`、`version` 等公共参数一起签名提交。每份 API 文档均提供 Java 和 cURL 示例,参见 [API 文档索引](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/llms.txt)。 所有接口返回 JSON 业务结果,再由平台打开结果里的页面链接。接口调用使用服务端 SDK 的普通执行方法,如 Java 的 `execute`。不要将这些接口作为直接输出 HTML 支付表单的页面支付接口使用。 以额度查询为例,响应封装如下: ```json { "alipay_aipay_nowpay_quota_query_response": { "code": "10000", "msg": "Success", "quota_unit": "COUNT", "total": 20, "used": 0, "remaining": 20, "as_of_time": "2026-09-07 10:00:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` 上例仅说明响应结构,签名不是有效签名。平台先验签、再判断 `code`;`code=10000` 只说明接口调用成功,业务是否允许访问或扣减是否成功,还需读取对应的业务状态。 ##### 幂等与重试 | 操作 | 平台应保存的定位信息 | 重试原则 | | --- | --- | --- | | alipay.aipay.nowpay.charge.initialize | 商品、创作者和首次初始化参数 | 相同商品复用配置申请;结果未知时原参数重试,已配置则查询管理入口 | | alipay.aipay.nowpay.charge.modify | 商品、创作者和目标 action | 先查状态;必要时重试原动作 | | alipay.aipay.nowpay.purchase.create | 独立购买入口请求号及完整业务参数 | 有效期内同请求复用入口;超时不换号。确认链接失效后,新购买入口使用新号 | | alipay.aipay.nowpay.quota.verify | 消费请求号、商品、受益人、amount、consume_reason | 使用原请求号和原参数重试,或查询原核销结果 | | alipay.aipay.nowpay.quota.refresh | 原消费请求的定位信息 | 只查询原核销记录,不生成新的核销号 | 平台应保证 `out_request_no` 在其业务范围内唯一,不跨商品、用户或不同消费复用。购买链接幂等具有时效,不可用作长期订单查重。不要把购买链接请求号当成支付宝交易号,也不要用购买接口重新生成入口来恢复核销结果。 对可恢复异常采用有限次数、带间隔的查询或重试;超过平台预设等待时间后保留“待确认”状态,由后续查询或排查恢复。不要因达到等待上限就将未知结果强制判为失败。 ##### 页面返回与通知 `callback_url` 仅用于用户或创作者操作结束后的页面跳转。买断与时长包在返回后查询 `alipay.aipay.nowpay.purchase.consult`,额度包查询 `alipay.aipay.nowpay.quota.query`,收费配置查询 `alipay.aipay.nowpay.charge.query`。 ##### 错误处理 1. 网关或签名错误:按[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)排查公共参数、应用权限和验签配置。 2. 参数、商品或模式错误:按具体 API 的 `sub_code` 核对业务参数及商品配置;不依赖 `sub_msg` 的展示文案编写业务分支。 3. 核销余额不足:兼容 `NOW_PAY_QUOTA_INSUFFICIENT` 业务错误及 `FAILED` 的结果表达,不确认消费成功。 4. 幂等冲突:读取平台已保存的原请求进行核对;不能通过替换请求号掩盖一笔未确认的消费。 5. 核销未找到记录或依赖异常:保留原请求号,继续查询或原参数重试。公开预览与当前服务端部分错误码命名存在差异,按核销 API 的“联调兼容处理”覆盖。 --- ### 商品收费能力查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 商品收费能力查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/charge_query.md 查询商品的收费能力状态、收费模式和可售档位,并获取商品管理入口 #### 接口说明 接口名称:`alipay.aipay.nowpay.charge.query` 查询平台商品的收费能力状态、收费模式和可售档位,并获取商品管理入口。平台可据此展示收费配置入口、选择购买流程和刷新商品状态。 支持已获授权的第三方代理调用。所有接口由平台服务端调用。 #### 适用场景 - 进入商品收费设置页,判断应初始化配置还是进入管理页。 - 配置、启停操作结束后刷新状态和可售档位。 - 读取 `billing_mode`,选择访问决策流程或额度包流程。 #### 注意事项 - `NOT_CONFIGURED`、`CONFIGURING`:继续调用 `charge.initialize` 获取 `configuration_url`;其余已配置状态使用 `management_url` 进入管理页。 - `capability_status` 描述商品新增购买能力。用户是否可访问应查询 `purchase.consult`;额度包的余额和扣减结果分别查询 `quota.query`、`quota.verify`。 - `charging_options` 可能为空。`sku_id`、`plan_id` 都按不透明标识保存;价格、价格版本和档位列表只用于展示与选择,不由平台拼装支付订单。 - 遇到未知状态或查询失败时,不自动放行付费访问;展示处理中并刷新,必要时进入返回的管理入口。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.charge.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | `app_writing_001` | | `external_owner_id` | String | 必选 | 128 | 平台内稳定的创作者或商品所有者标识 | 与配置时使用的标识一致;不是必须填写支付宝账号 | `creator_001` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在平台服务端。cURL 中的签名需在发送前按全部实际参数生成;如增加 `app_auth_token`,应一起参与签名。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayChargeQueryRequest; import com.alipay.api.response.AlipayAipayNowpayChargeQueryResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayChargeQueryRequest request = new AlipayAipayNowpayChargeQueryRequest(); request.setBizContent("{\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayChargeQueryResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "app_writing_001", "external_owner_id": "creator_001" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.charge.query' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_charge_query_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 > 协议核对:当前开放平台预览将 `status_version` 定义为 String;本稿依据现有实现整理为 Number 整数。联调需确认最终返回类型,确认前建议兼容字符串和数字版本号。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `capability_status` | String | 必选 | 32 | 商品收费能力状态 | `NOT_CONFIGURED` / `CONFIGURING` / `PENDING` / `ACTION_REQUIRED` / `ENABLED` / `DISABLED` / `TERMINATED` | `ENABLED` | | `product_name` | String | 可选 | 32 | 商品名称 | - | `智能写作助手` | | `product_icon_url` | String | 可选 | 1024 | 商品图标 | - | `https://platform.example.com/assets/writing.png` | | `status_version` | Number | 可选 | 32 | 状态版本 | 整数版本号;用于记录状态版本,不作为启停入参 | `1` | | `billing_mode` | String | 可选 | 32 | 最终收费模式 | 永久买断:`ONE_TIME`;时长包:`ONE_TIME_DURATION`;额度包:`QUANTITY` | `QUANTITY` | | `quota_unit` | String | 特殊可选 | 32 | 额度包返回 | `billing_mode`=`QUANTITY` 时使用;`COUNT`:次数,`POINT`:积分 | `COUNT` | | `charging_options` | ChargingOption[] | 必选 | - | 当前商品的收费档位列表 | 可能为空数组;子字段必选性适用于实际返回的档位元素 | - | | `charging_options[].sku_id` | String | 必选 | 32 | 档位标识,平台原样回传 | 按不透明标识保存和回传,不解析内容 | `S0806000200863003` | | `charging_options[].plan_id` | String | 必选 | 32 | 价格计划标识 | 按不透明标识保存和回传,不解析内容 | `PI0806000200864210` | | `charging_options[].display_name` | String | 必选 | 32 | 档位名称 | - | `20次包` | | `charging_options[].billing_mode` | String | 必选 | 32 | 档位类型 | 永久买断:`ONE_TIME`;时长包:`ONE_TIME_DURATION`;额度包:`QUANTITY` | `QUANTITY` | | `charging_options[].price` | String | 必选 | 32 | 展示价格,十进制,单位元 | - | `1.00` | | `charging_options[].currency` | String | 必选 | 32 | 货币类型 | - | `CNY` | | `charging_options[].price_version` | Number | 必选 | 32 | 价格快照版本 | 整数;价格快照版本,仅展示和记录,不作为购买请求参数 | `1` | | `charging_options[].entitlement_rule` | String | 必选 | 32 | 权益类型 | `PERPETUAL`:买断;`FIXED_DURATION`:时长包;`QUOTA`:额度包 | `QUOTA` | | `charging_options[].duration_period` | String | 特殊可选 | 32 | 时长包周期类型 | `billing_mode`=`ONE_TIME_DURATION` 时返回;`WEEK` / `MONTH` / `QUARTER` / `YEAR` | `WEEK` | | `charging_options[].quota_unit` | String | 特殊可选 | 32 | 额度类型 | `billing_mode`=`QUANTITY` 时使用;`COUNT`:次数,`POINT`:积分 | `COUNT` | | `charging_options[].quota_amount` | Number | 特殊可选 | 32 | 次数或积分数量,单位个 | `billing_mode`=`QUANTITY` 时返回;购买该档位增加的整数额度 | `20` | | `management_url` | String | 特殊可选 | 1024 | 平台直接使用该地址进入商品管理 | 已配置状态返回;初始化返回已配置错误时,调用 `charge.query` 获取管理入口 | `alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET` | | `reason_message` | String | 可选 | 256 | 用于展示的状态说明 | - | - | #### 结果处理 | capability_status | 含义 | 平台处理 | | --- | --- | --- | | `NOT_CONFIGURED` | 尚未初始化 | 调用 charge.initialize | | `CONFIGURING` | 配置尚未完成 | 调用 charge.initialize 继续原配置 | | `PENDING` | 等待审核或发布 | 打开 management_url 查看进度 | | `ACTION_REQUIRED` | 需要创作者处理 | 打开 management_url 完成处理 | | `ENABLED` | 允许新增购买 | 展示购买入口,管理操作使用 management_url | | `DISABLED` | 停止新增购买 | 隐藏新购买入口;原有权益按对应接口判断 | | `TERMINATED` | 商品已归档 | 进入 management_url 查看状态,不新建购买入口 | #### 响应示例 以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpay_charge_query_response": { "code": "10000", "msg": "Success", "capability_status": "ENABLED", "product_name": "智能写作助手", "product_icon_url": "https://platform.example.com/assets/writing.png", "status_version": 1, "billing_mode": "QUANTITY", "quota_unit": "COUNT", "charging_options": [ { "sku_id": "S0806000200863003", "plan_id": "PI0806000200864210", "display_name": "20次包", "billing_mode": "QUANTITY", "price": "1.00", "currency": "CNY", "price_version": 1, "entitlement_rule": "QUOTA", "quota_unit": "COUNT", "quota_amount": 20 } ], "management_url": "alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_charge_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充平台处理建议。错误码列表可能扩展,平台应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `NOW_PAY_PLATFORM_NOT_FOUND` | 平台身份未配置 | 联系即刻收平台管理员补充该平台的身份映射 | --- ### 商品收费配置初始化接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 商品收费配置初始化接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/charge_init.md 为平台商品创建或复用收费配置申请,返回支付宝托管配置页入口。创作者在托管页完成账号绑定、收费模式与档位配置;平台在配置结束后查询最新收费能力。 #### 接口说明 接口名称:`alipay.aipay.nowpay.charge.initialize` 为平台商品创建或复用收费配置申请,返回支付宝托管配置页入口。创作者在托管页完成账号绑定、收费模式与档位配置;平台在配置结束后查询最新收费能力。 支持已获授权的第三方代理调用。所有接口由平台服务端调用。 #### 适用场景 - 创作者首次为平台应用开通收费。 - 收费状态为 `NOT_CONFIGURED` 或 `CONFIGURING`,需要进入或继续完成配置。 #### 注意事项 - 先调用 `charge.query`;仅在 `NOT_CONFIGURED` 或 `CONFIGURING` 时初始化。配置完成后再次初始化可能返回 `NOW_PAY_ALREADY_CONFIGURED`,应重新查询并使用 `management_url`。 - `pricing_mode_list` 描述初始化时提供的收费模式提示,价格与实际档位由创作者在托管页设置。同一商品最终采用一种收费模式,可在该模式下配置多个档位。平台应以配置后的 `charge.query` 结果为准。 - 按公开请求协议传入非空 `pricing_mode_list`,`QUANTITY` 项传入 `quota_unit`。price 为兼容字段,本产品接入时不传;初始化成功不表示收费能力已启用。 - 使用稳定的 `out_product_id` 和 `external_owner_id`;重试保持请求一致。配置尚未完成时复用原申请;已配置商品的启停使用 `charge.modify`。 - `callback_url` 是配置完成后的页面返回地址,不是服务端异步通知地址。返回后调用 `charge.query` 确认状态。配置页链接与二维码使用本次接口实际返回值。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.charge.initialize` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | `app_writing_001` | | `external_owner_id` | String | 必选 | 128 | 平台内稳定的创作者或商品所有者标识 | 与配置时使用的标识一致;不是必须填写支付宝账号 | `creator_001` | | `product_name` | String | 必选 | 128 | 商品名称 | - | `智能写作助手` | | `product_icon_url` | String | 可选 | 1024 | 商品图标链接地址 | - | `https://platform.example.com/assets/writing.png` | | `product_url` | String | 可选 | 1024 | 商品详情页 | - | `https://platform.example.com/apps/app_writing_001` | | `callback_url` | String | 可选 | 1024 | 配置完成返回平台地址 | 页面返回地址,不是异步通知地址;返回后重新查询状态 | `https://platform.example.com/nowpay/config-return` | | `pricing_mode_list` | PricingMode[] | 必选 | - | 初始化收费模式提示列表 | 按公开协议至少传一项;实际模式与价格以托管页配置及后续查询为准 | - | | `pricing_mode_list[].billing_mode` | String | 必选 | 32 | 计费模式 | 永久买断:`ONE_TIME`;时长包:`ONE_TIME_DURATION`;额度包:`QUANTITY` | `QUANTITY` | | `pricing_mode_list[].quota_unit` | String | 特殊可选 | 32 | `QUANTITY` 必填:`COUNT`/`POINT` | `billing_mode`=`QUANTITY` 时使用;`COUNT`:次数,`POINT`:积分 | `COUNT` | | `pricing_mode_list[].price` | String | 可选 | 32 | 兼容保留的价格字段,单位元 | 本产品初始化时不传;价格在托管配置页设置 | - | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在平台服务端。cURL 中的签名需在发送前按全部实际参数生成;如增加 `app_auth_token`,应一起参与签名。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayChargeInitializeRequest; import com.alipay.api.response.AlipayAipayNowpayChargeInitializeResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayChargeInitializeRequest request = new AlipayAipayNowpayChargeInitializeRequest(); request.setBizContent("{\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\",\"product_name\":\"智能写作助手\",\"product_icon_url\":\"https://platform.example.com/assets/writing.png\",\"product_url\":\"https://platform.example.com/apps/app_writing_001\",\"callback_url\":\"https://platform.example.com/nowpay/config-return\",\"pricing_mode_list\":[{\"billing_mode\":\"QUANTITY\",\"quota_unit\":\"COUNT\"}]}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayChargeInitializeResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "product_name": "智能写作助手", "product_icon_url": "https://platform.example.com/assets/writing.png", "product_url": "https://platform.example.com/apps/app_writing_001", "callback_url": "https://platform.example.com/nowpay/config-return", "pricing_mode_list": [ { "billing_mode": "QUANTITY", "quota_unit": "COUNT" } ] }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.charge.initialize' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_charge_initialize_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `configuration_url` | String | 特殊可选 | 1024 | 需要继续配置时返回 | 配置未完成时返回 | `alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fconfig%2Findex%3Fticket%3DSAMPLE_TICKET` | | `configuration_qr_code` | String | 特殊可选 | 1024 | 配置入口二维码 | 配置未完成时返回 | `https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE` | | `management_url` | String | 特殊可选 | 1024 | 已完成配置时返回 | 已配置状态返回;初始化返回已配置错误时,调用 `charge.query` 获取管理入口 | `alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET` | #### 结果处理 收到成功响应后打开 `configuration_url`,或展示 `configuration_qr_code` 引导创作者操作。返回平台后调用 [查询收费能力和档位](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/charge_query.md);只有状态为 `ENABLED` 才展示新的购买入口。已配置错误需走查询获取管理入口,不能依赖失败响应中的链接。 #### 响应示例 以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpay_charge_initialize_response": { "code": "10000", "msg": "Success", "configuration_url": "alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fconfig%2Findex%3Fticket%3DSAMPLE_TICKET", "configuration_qr_code": "https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_charge_initialize_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充平台处理建议。错误码列表可能扩展,平台应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `NOW_PAY_ALREADY_CONFIGURED` | 商品已完成初始化配置,无法重复配置 | 调用 `charge.query`,获取 `management_url` 进入管理页 | --- ### 商品收费启用或停用接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 商品收费启用或停用接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/charge_modify.md 启用或停用商品收费能力。支持将已停用商品重新启用,或将已启用商品停用;商品原有有效权益仍按权益查询结果使用。 #### 接口说明 接口名称:`alipay.aipay.nowpay.charge.modify` 启用或停用商品的新增购买能力。支持将已停用商品重新启用,或将已启用商品停用;商品原有有效权益仍按权益查询结果使用。 支持已获授权的第三方代理调用。所有接口由平台服务端调用。 #### 适用场景 - 创作者暂停商品新增购买。 - 已停用商品恢复新增购买。 #### 注意事项 - action 仅支持 `ENABLE`、`DISABLE`;接口不修改价格、档位、额度数量或权益有效期,也不撤销已发放权益。 - 只对已完成配置且处于可启停状态的商品操作。若已处于目标状态,返回 changed=false,仍表示本次请求成功。 - 超时后先调用 `charge.query` 确认现状;必要时重试原 action。不要直接提交相反动作作为补偿。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.charge.modify` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | `app_writing_001` | | `external_owner_id` | String | 必选 | 128 | 平台内稳定的创作者或商品所有者标识 | 与配置时使用的标识一致;不是必须填写支付宝账号 | `creator_001` | | `action` | String | 必选 | 32 | 修改类型,`ENABLE`/`DISABLE` | 开启:`ENABLE`;关闭:`DISABLE` | `DISABLE` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在平台服务端。cURL 中的签名需在发送前按全部实际参数生成;如增加 `app_auth_token`,应一起参与签名。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayChargeModifyRequest; import com.alipay.api.response.AlipayAipayNowpayChargeModifyResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayChargeModifyRequest request = new AlipayAipayNowpayChargeModifyRequest(); request.setBizContent("{\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\",\"action\":\"DISABLE\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayChargeModifyResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "action": "DISABLE" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.charge.modify' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_charge_modify_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `capability_status` | String | 必选 | 128 | 商品收费能力状态 | `ENABLED` / `DISABLED` | `DISABLED` | | `status_version` | Number | 可选 | 32 | 最新状态版本 | - | `2` | | `changed` | Boolean | 必选 | 10 | 是否实际发生状态变化 | - | `true` | | `reason_message` | String | 可选 | 32 | 用于展示的状态说明 | - | - | #### 结果处理 `code=10000` 后读取 `capability_status` 确认目标状态。`changed=false` 表示此前已经处于目标状态,不应当作失败。操作失败或结果未知时,使用 [查询收费能力和档位](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/charge_query.md) 重新查询。 #### 响应示例 以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpay_charge_modify_response": { "code": "10000", "msg": "Success", "capability_status": "DISABLED", "status_version": 2, "changed": true }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_charge_modify_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充平台处理建议。错误码列表可能扩展,平台应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `NOW_PAY_BINDING_NOT_FOUND` | 未找到绑定的商品 | 请确认相关商品已配置上架 | | `NOW_PAY_CAPABILITY_CHANGE_FAIL` | 商品变更失败:当前状态不允许变更 | 请确认商品最新状态 | --- ### 用户是否拥有商品权益查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 用户是否拥有商品权益查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/purchase_consult.md 查询指定平台用户是否拥有可使用的买断或时长包权益。返回访问决策;需要购买且商品可购买时,同时返回支付宝托管购买页入口。 #### 接口说明 接口名称:`alipay.aipay.nowpay.purchase.consult` 查询指定平台用户是否拥有可使用的买断或时长包权益。返回访问决策;需要购买且商品可购买时,同时返回支付宝托管购买页入口。 #### 适用场景 - 买断或时长包用户进入付费功能前校验访问权限。 - 用户从支付页返回后重新确认权益。 - 时长包需要展示当前权益有效期。 #### 注意事项 - 仅适用于 `ONE_TIME` 和 `ONE_TIME_DURATION`。`QUANTITY` 商品应使用 `quota.query`,并在消费时调用 `quota.verify`。 - 只有 decision=`ALLOW` 才放行。`PURCHASE_REQUIRED` 引导用户使用返回的购买入口;`DENY` 不放行、不展示新的购买入口。 - `callback_url` 只表示页面返回。用户返回后必须再次查询本接口;不要根据跳转、前端参数或本地缓存认定支付和权益成功。 - 时长包有效区间为 [`valid_from`, `valid_until`),到达 `valid_until` 后不再有效;永久买断不返回这两个时间字段。已有有效买断或时长权益时不引导再次购买。 - 商品停止新增购买后,已有有效权益仍可能返回 `ALLOW`。放行以 decision 为准,不能仅按 `capability_status` 决定。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.purchase.consult` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | `app_writing_001` | | `external_owner_id` | String | 必选 | 128 | 平台内稳定的创作者或商品所有者标识 | 与配置时使用的标识一致;不是必须填写支付宝账号 | `creator_001` | | `external_buyer_id` | String | 必选 | 128 | 平台内稳定的权益受益人标识 | 与平台登录用户绑定;不等同于付款账号 | `user_001` | | `callback_url` | String | 可选 | 512 | 购买完成返回地址 | 页面返回地址,不是异步通知地址;返回后重新查询状态 | `https://platform.example.com/nowpay/purchase-return` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在平台服务端。cURL 中的签名需在发送前按全部实际参数生成;如增加 `app_auth_token`,应一起参与签名。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayPurchaseConsultRequest; import com.alipay.api.response.AlipayAipayNowpayPurchaseConsultResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayPurchaseConsultRequest request = new AlipayAipayNowpayPurchaseConsultRequest(); request.setBizContent("{\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\",\"external_buyer_id\":\"user_001\",\"callback_url\":\"https://platform.example.com/nowpay/purchase-return\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayPurchaseConsultResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001", "callback_url": "https://platform.example.com/nowpay/purchase-return" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.purchase.consult' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_purchase_consult_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `decision` | String | 必选 | 32 | 当前访问决策 | `ALLOW`:允许访问;`PURCHASE_REQUIRED`:需要购买;`DENY`:不允许访问且不引导购买 | `ALLOW` | | `reason_code` | String | 可选 | 128 | 业务结果原因码 | 结合 decision 或 `consume_status` 使用;不要按原因文案编写业务分支 | - | | `valid_from` | String | 特殊可选 | 128 | 表示本次有效权益的生效时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | 仅 `ONE_TIME_DURATION` 且 decision=`ALLOW` 时返回;有效区间 [`valid_from`, `valid_until`) | `2026-09-07 10:00:00` | | `valid_until` | String | 特殊可选 | 128 | 表示本次有效权益的结束时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | 仅 `ONE_TIME_DURATION` 且 decision=`ALLOW` 时返回;有效区间 [`valid_from`, `valid_until`) | `2026-10-07 10:00:00` | | `product_name` | String | 可选 | 128 | 商品名称 | - | `智能写作助手` | | `product_icon_url` | String | 可选 | 512 | 商品图标 | - | `https://platform.example.com/assets/writing.png` | | `capability_status` | String | 必选 | 128 | 商品收费能力状态 | `NOT_CONFIGURED` / `CONFIGURING` / `PENDING` / `ACTION_REQUIRED` / `ENABLED` / `DISABLED` / `TERMINATED` | `ENABLED` | | `purchase_url` | String | 特殊可选 | 512 | 购买链接 | `PURCHASE_REQUIRED` 返回 | `alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID` | | `purchase_qr_code` | String | 特殊可选 | 512 | 购买二维码 | `PURCHASE_REQUIRED` 返回 | `https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE` | | `charging_options` | ConsultChargingOption[] | 必选 | - | 当前商品的收费档位列表 | 可能为空数组;子字段必选性适用于实际返回的档位元素 | - | | `charging_options[].sku_id` | String | 必选 | 32 | 档位标识,平台原样回传 | 按不透明标识保存和回传,不解析内容 | `S0806000200863004` | | `charging_options[].plan_id` | String | 必选 | 32 | 价格计划标识 | 按不透明标识保存和回传,不解析内容 | `PI0806000200864211` | | `charging_options[].display_name` | String | 必选 | 32 | 档位名称 | - | `月度使用包` | | `charging_options[].billing_mode` | String | 必选 | 32 | 档位类型 | 本接口仅 `ONE_TIME` / `ONE_TIME_DURATION` | `ONE_TIME_DURATION` | | `charging_options[].price` | String | 必选 | 32 | 展示价格,十进制,单位元 | - | `9.90` | | `charging_options[].currency` | String | 必选 | 32 | 货币 | - | `CNY` | | `charging_options[].price_version` | Number | 必选 | 32 | 价格快照版本 | 整数;价格快照版本,仅展示和记录,不作为购买请求参数 | `1` | | `charging_options[].entitlement_rule` | String | 必选 | 32 | 权益类型 | 本接口仅 `PERPETUAL` / `FIXED_DURATION` | `FIXED_DURATION` | | `charging_options[].duration_period` | String | 特殊可选 | 32 | 时长包周期类型 | `billing_mode`=`ONE_TIME_DURATION` 时返回;`WEEK` / `MONTH` / `QUARTER` / `YEAR` | `MONTH` | | `charging_options[].quota_unit` | String | 特殊可选 | 32 | 额度类型 | 通用档位结构保留字段;仅额度包适用,本接口不返回 | - | | `charging_options[].quota_amount` | Number | 特殊可选 | 32 | 次数或积分数量,单位个 | 通用档位结构保留字段;仅额度包适用,本接口不返回 | - | #### 结果处理 | decision | 平台处理 | | --- | --- | | `ALLOW` | 放行;时长包可展示 valid_from、valid_until | | `PURCHASE_REQUIRED` | 使用 purchase_url 或 purchase_qr_code 引导购买;返回后重新查询 | | `DENY` | 不放行、不新建购买入口;根据 reason_code 展示说明或稍后刷新 | `reason_code` 是业务结果原因,不能代替 `decision`。常见拒绝原因包括权益暂不可用、商品已停用或需要创作者处理;遇到未识别的原因也不自动放行。 #### 响应示例 以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpay_purchase_consult_response": { "code": "10000", "msg": "Success", "decision": "ALLOW", "valid_from": "2026-09-07 10:00:00", "valid_until": "2026-10-07 10:00:00", "product_name": "智能写作助手", "capability_status": "ENABLED", "charging_options": [ { "sku_id": "S0806000200863004", "plan_id": "PI0806000200864211", "display_name": "月度使用包", "billing_mode": "ONE_TIME_DURATION", "price": "9.90", "currency": "CNY", "price_version": 1, "entitlement_rule": "FIXED_DURATION", "duration_period": "MONTH" } ] }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_purchase_consult_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ##### 需要购买示例 ```json { "alipay_aipay_nowpay_purchase_consult_response": { "code": "10000", "msg": "Success", "decision": "PURCHASE_REQUIRED", "capability_status": "ENABLED", "charging_options": [ { "sku_id": "S0806000200863004", "plan_id": "PI0806000200864211", "display_name": "月度使用包", "billing_mode": "ONE_TIME_DURATION", "price": "9.90", "currency": "CNY", "price_version": 1, "entitlement_rule": "FIXED_DURATION", "duration_period": "MONTH" } ], "purchase_url": "alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID", "purchase_qr_code": "https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充平台处理建议。错误码列表可能扩展,平台应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 当前商品收费模式不适用于访问决策 | 仅买断和时长包使用本接口;额度包改用 `quota.query` | | `NOW_PAY_BINDING_INVALID` | 商品未绑定或未查到已上架商品 | 请核对商品是否已开通上架 | --- ### 直接购买链接获取接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 直接购买链接获取接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/purchase_create.md 获取普通购买入口或锁定指定档位的购买入口。传入 `sku_id` 时锁定该档位;不传时由用户在托管购买页选择可售档位。 #### 接口说明 接口名称:`alipay.aipay.nowpay.purchase.create` 获取普通购买入口或锁定指定档位的购买入口。传入 `sku_id` 时锁定该档位;不传时由用户在托管购买页选择可售档位。 #### 适用场景 - 额度不足时引导用户购买次数包或积分包。 - 用户主动加购额度,即使当前仍有余额。 - 平台已展示档位并希望直接打开指定档位购买页。 #### 注意事项 - `out_request_no` 标识一次获取购买入口的请求,不是支付宝交易号。平台应为每次独立请求生成唯一值并持久化;超时重试使用原值与原参数。 - 幂等复用有有效期,不是永久订单查询能力。链接失效时间以 `expire_time` 为准;仅在确认旧入口失效并需要新购买入口时创建新请求,不能因超时立即换号。 - `sku_id` 必须取自当前商品 `charge.query` 的可售档位。不传 `sku_id` 时打开可选档位的普通购买页,响应可不包含 `charging_option`。 - `callback_url` 如传入,使用 `HTTPS` 地址。支付页面返回后,买断或时长包调用 `purchase.consult`;额度包调用 `quota.query`。 - 额度包支持有余额时加购。买断或时长包已有可用权益,或权益处于不可重购状态时,可能拒绝生成新的购买入口。获取链接成功不等于支付成功。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.purchase.create` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | String | 必选 | 128 | 平台生成的幂等请求号 | 重试保持原值与原业务参数;不同请求使用不同值 | `purchase_20260907_000001` | | `out_product_id` | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | `app_writing_001` | | `external_owner_id` | String | 必选 | 128 | 平台内稳定的创作者或商品所有者标识 | 与配置时使用的标识一致;不是必须填写支付宝账号 | `creator_001` | | `external_buyer_id` | String | 必选 | 128 | 平台内稳定的权益受益人标识 | 与平台登录用户绑定;不等同于付款账号 | `user_001` | | `sku_id` | String | 可选 | 128 | 档位标识 | 取自当前商品的 `charging_options`;不传则在购买页选择档位 | `S0806000200863003` | | `callback_url` | String | 可选 | 512 | 购买完成返回地址 | 页面返回地址,不是异步通知地址;返回后重新查询状态;如传入必须为 `HTTPS` | `https://platform.example.com/nowpay/purchase-return` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在平台服务端。cURL 中的签名需在发送前按全部实际参数生成;如增加 `app_auth_token`,应一起参与签名。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayPurchaseCreateRequest; import com.alipay.api.response.AlipayAipayNowpayPurchaseCreateResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayPurchaseCreateRequest request = new AlipayAipayNowpayPurchaseCreateRequest(); request.setBizContent("{\"out_request_no\":\"purchase_20260907_000001\",\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\",\"external_buyer_id\":\"user_001\",\"sku_id\":\"S0806000200863003\",\"callback_url\":\"https://platform.example.com/nowpay/purchase-return\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayPurchaseCreateResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_request_no": "purchase_20260907_000001", "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001", "sku_id": "S0806000200863003", "callback_url": "https://platform.example.com/nowpay/purchase-return" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.purchase.create' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_purchase_create_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 > 协议核对:当前开放平台预览将 `charging_option` 定义为数组;本稿依据现有实现整理为单对象,且普通入口可不返回。编写解析代码前需确认最终网关结构。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `purchase_url` | String | 必选 | 512 | 托管购买页 | - | `alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID` | | `purchase_qr_code` | String | 可选 | 512 | 购买二维码 | - | `https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE` | | `expire_time` | String | 必选 | 32 | 链接失效时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | - | `2026-09-07 10:30:00` | | `charging_option` | Object | 特殊可选 | - | 选中档位摘要 | 指定 `sku_id` 且成功生成指定档位链接时返回;普通链接可不返回 | - | | `charging_option.sku_id` | String | 必选 | 32 | 档位标识,平台原样回传 | 按不透明标识保存和回传,不解析内容 | `S0806000200863003` | | `charging_option.plan_id` | String | 必选 | 32 | 价格计划标识 | 按不透明标识保存和回传,不解析内容 | `PI0806000200864210` | | `charging_option.display_name` | String | 必选 | 32 | 档位名称 | - | `20次包` | | `charging_option.billing_mode` | String | 必选 | 32 | 档位类型 | 永久买断:`ONE_TIME`;时长包:`ONE_TIME_DURATION`;额度包:`QUANTITY` | `QUANTITY` | | `charging_option.price` | String | 必选 | 32 | 展示价格,十进制,单位元 | - | `1.00` | | `charging_option.currency` | String | 必选 | 32 | 货币 | - | `CNY` | | `charging_option.price_version` | Number | 必选 | 32 | 价格快照版本 | 整数;价格快照版本,仅展示和记录,不作为购买请求参数 | `1` | | `charging_option.entitlement_rule` | String | 必选 | 32 | 权益类型 | `PERPETUAL`:买断;`FIXED_DURATION`:时长包;`QUOTA`:额度包 | `QUOTA` | | `charging_option.duration_period` | String | 特殊可选 | 32 | 时长包周期类型 | `billing_mode`=`ONE_TIME_DURATION` 时返回;`WEEK` / `MONTH` / `QUARTER` / `YEAR` | `WEEK` | | `charging_option.quota_unit` | String | 特殊可选 | 32 | 额度类型 | `billing_mode`=`QUANTITY` 时使用;`COUNT`:次数,`POINT`:积分 | `COUNT` | | `charging_option.quota_amount` | Number | 特殊可选 | 32 | 次数或积分数量,单位个 | `billing_mode`=`QUANTITY` 时返回;购买该档位增加的整数额度 | `20` | #### 结果处理 成功后打开 `purchase_url` 或展示 `purchase_qr_code`。链接、二维码和令牌都使用接口实际返回值,不解析、不拼接。到期后先刷新用户权益或额度,再按用户购买意图获取新入口。 #### 响应示例 以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpay_purchase_create_response": { "code": "10000", "msg": "Success", "purchase_url": "alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID", "purchase_qr_code": "https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE", "expire_time": "2026-09-07 10:30:00", "charging_option": { "sku_id": "S0806000200863003", "plan_id": "PI0806000200864210", "display_name": "20次包", "billing_mode": "QUANTITY", "price": "1.00", "currency": "CNY", "price_version": 1, "entitlement_rule": "QUOTA", "quota_unit": "COUNT", "quota_amount": 20 } }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_purchase_create_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ##### 普通购买入口 不传 `sku_id` 时,由用户在托管页选择档位,响应可省略 `charging_option`。 ```json { "alipay_aipay_nowpay_purchase_create_response": { "code": "10000", "msg": "Success", "purchase_url": "alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID", "purchase_qr_code": "https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE", "expire_time": "2026-09-07 10:30:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充平台处理建议。错误码列表可能扩展,平台应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 计价模式不支持 | 请确认商品收费模式 | | `NOW_PAY_BINDING_INVALID` | 商品绑定关系不存在/不匹配 | 请先完成商品配置上架 | | `NOW_PAY_CHARGING_OPTION_UNAVAILABLE` | 指定档位已下架或不存在 | 确认 `sku_id`与 `charge.query` 返回的可售档位一致 | | `NOW_PAY_ORDER_CONFLICT` | 同一幂等请求号对应的业务参数不一致 | 核对原请求参数;原请求结果未知时不要换号重试 | | `NOW_PAY_PRODUCT_NOT_PURCHASABLE` | 用户已有不可重购权益 | 用户已有不可重购权益 | | `NOW_PAY_PURCHASE_LINK_CREATING` | 当前购买链接正在创建中,不允许重复提交请求 | 稍后用原 `out_request_no` 和原参数重试 | | `NOW_PAY_PURCHASE_LINK_INVALID` | 购买链接已过期或不存在 | 确认旧购买入口失效后,按新的购买意图生成新请求号;不要将核销超时按此处理 | --- ### 用户在商品下的额度查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 用户在商品下的额度查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/quota_query.md 查询平台用户在指定额度包商品下的有效发放总额、已用额度和剩余额度。接口返回客观余额,平台根据自己的服务规则决定一次服务需要消耗多少次数或积分。 #### 接口说明 接口名称:`alipay.aipay.nowpay.quota.query` 查询平台用户在指定额度包商品下的有效发放总额、已用额度和剩余额度。接口返回客观余额,平台根据自己的服务规则决定一次服务需要消耗多少次数或积分。 支持已获授权的第三方代理调用。所有接口由平台服务端调用。 #### 适用场景 - 展示剩余次数或积分。 - 用户购买返回后刷新余额。 - 执行服务前进行余额预检查。 #### 注意事项 - 仅适用于 `QUANTITY`;`quota_unit` 为 `COUNT` 或 `POINT`。 - 未购买时 total、used、remaining 都为 0;已用完时 remaining=0。统计仅覆盖当前纳入聚合的有效额度,不代表历史累计购买量。 - 查询只提供当前余额,不预占额度。并发消费场景必须以 `quota.verify` 的原子扣减结果为准。 - 购买后额度到账可能有短暂延迟。可以有限次刷新;尚未到账时提示稍后查询,不能仅凭余额未变化判定支付失败。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.quota.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | `app_writing_001` | | `external_owner_id` | String | 必选 | 128 | 平台内稳定的创作者或商品所有者标识 | 与配置时使用的标识一致;不是必须填写支付宝账号 | `creator_001` | | `external_buyer_id` | String | 必选 | 128 | 平台内稳定的权益受益人标识 | 与平台登录用户绑定;不等同于付款账号 | `user_001` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在平台服务端。cURL 中的签名需在发送前按全部实际参数生成;如增加 `app_auth_token`,应一起参与签名。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayQuotaQueryRequest; import com.alipay.api.response.AlipayAipayNowpayQuotaQueryResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayQuotaQueryRequest request = new AlipayAipayNowpayQuotaQueryRequest(); request.setBizContent("{\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\",\"external_buyer_id\":\"user_001\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayQuotaQueryResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.quota.query' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_quota_query_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `quota_unit` | String | 必选 | 32 | 次数或积分`COUNT`/`POINT` | `COUNT`:次数;`POINT`:积分 | `COUNT` | | `total` | Number | 必选 | 32 | 当前纳入聚合的有效发放额度,单位次数或积分个数 | - | `20` | | `used` | Number | 必选 | 32 | 上述有效发放额度中的已使用量,单位次数或积分个数 | - | `0` | | `remaining` | Number | 必选 | 32 | 当前可消费余额,单位次数或积分个数 | - | `20` | | `as_of_time` | String | 必选 | 32 | 余额计算时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | - | `2026-09-07 10:00:00` | #### 结果处理 平台根据 `quota_unit` 展示次数或积分,按 `remaining` 做服务前置判断。余额充足仍需核销;不足时可调用 [获取购买链接](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/purchase_create.md)。返回 0 余额本身是正常查询结果,不作为接口失败。 #### 响应示例 以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpay_quota_query_response": { "code": "10000", "msg": "Success", "quota_unit": "COUNT", "total": 20, "used": 0, "remaining": 20, "as_of_time": "2026-09-07 10:00:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_quota_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充平台处理建议。错误码列表可能扩展,平台应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 商品不是额度包模式 | 请核对入参参数相关的商品配置信息 | --- ### 商品额度核销接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 商品额度核销接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/quota_verify.md 按平台提供的消费请求号直接核销指定数量的次数或积分。核销成功即正式扣减;平台需结合服务交付时点调用,并保存消费请求与核销结果的对应关系。 #### 接口说明 接口名称:`alipay.aipay.nowpay.quota.verify` 按平台提供的消费请求号直接核销指定数量的次数或积分。核销成功即正式扣减;平台需结合服务交付时点调用,并保存消费请求与核销结果的对应关系。 支持已获授权的第三方代理调用。所有接口由平台服务端调用。 #### 适用场景 - 一次服务需要正式消耗次数或积分。 - 同一消费请求因网络异常需要重试。 #### 注意事项 - amount 必须显式传入正整数;一次扣 1 次时传 1,不依赖服务端默认补值。积分按平台服务规则计算后传入。 - 平台在调用前持久化 `out_request_no`、商品、受益人、amount 和 `consume_reason`。重试保持这些字段一致;不同消费使用不同请求号。 - `consume_reason` 使用不超过 256 字符的简洁业务文本,用于说明本次消费。平台自行保存审计记录,不依赖结果查询接口回传此字段来恢复原始业务上下文。 - 先检查 code,再读取 `consume_status`。只有 `SUCCEEDED` 表示扣减成功;`PROCESSING`、网络超时或系统错误都不能直接当作失败换号重扣。 - 余额不足可能通过业务错误码 `NOW_PAY_QUOTA_INSUFFICIENT` 返回;也需兼容 `FAILED` 与 `reason_code` 的结果表达。额度不足整笔失败,不按部分扣减处理。 - 核销成功后不提供核销撤销、预占释放或服务失败自动返还。平台应事先确定服务交付与核销的时点,并对服务执行本身做好幂等。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.quota.verify` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | String | 必选 | 128 | 平台生成的幂等请求号 | 重试保持原值与原业务参数;不同请求使用不同值 | `consume_20260907_000001` | | `out_product_id` | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | `app_writing_001` | | `external_owner_id` | String | 可选 | 128 | 平台内稳定的创作者或商品所有者标识 | 与配置时使用的标识一致;不是必须填写支付宝账号 | `creator_001` | | `external_buyer_id` | String | 必选 | 128 | 平台内稳定的权益受益人标识 | 与平台登录用户绑定;不等同于付款账号 | `user_001` | | `amount` | Number | 必选 | - | 本次核销数量,单位次数或积分 | 显式传入正整数;`COUNT` 单次扣减传 1;当前预览“长度/取值”为 99999999 | `1` | | `consume_reason` | String | 必选 | 256 | 本次业务消费的简洁原因文本 | 必传普通文本,最长 256 字符;不传 `JSON`、用户隐私或提示词 | `生成一篇文章` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在平台服务端。cURL 中的签名需在发送前按全部实际参数生成;如增加 `app_auth_token`,应一起参与签名。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayQuotaVerifyRequest; import com.alipay.api.response.AlipayAipayNowpayQuotaVerifyResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayQuotaVerifyRequest request = new AlipayAipayNowpayQuotaVerifyRequest(); request.setBizContent("{\"out_request_no\":\"consume_20260907_000001\",\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\",\"external_buyer_id\":\"user_001\",\"amount\":1,\"consume_reason\":\"生成一篇文章\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayQuotaVerifyResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_request_no": "consume_20260907_000001", "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001", "amount": 1, "consume_reason": "生成一篇文章" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.quota.verify' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_quota_verify_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `consume_status` | String | 必选 | 32 | `SUCCEEDED`/`FAILED`/`PROCESSING` | 成功:`SUCCEEDED`;失败:`FAILED`;进行中:`PROCESSING` | `SUCCEEDED` | | `consume_order_id` | String | 可选 | 128 | 消费流水标识 | - | `202609071000000001` | | `consume_reason` | String | 必选 | 256 | 消费原因 | 平台应持久化原始原因;查询结果可能不返回 | `生成一篇文章` | | `quota_unit` | String | 必选 | 32 | 次数或积分,`COUNT`/`POINT` | `COUNT`:次数;`POINT`:积分 | `COUNT` | | `consumed` | Number | 必选 | 32 | 本次实际扣减量,单位次数或积分 | 非成功状态按 0 处理,不据此确认成功 | `1` | | `remaining` | Number | 特殊可选 | 32 | 本次核销成功时,原子扣减后的可消费余额 | 仅 `SUCCEEDED` 时使用;不是当前实时余额 | `19` | | `reason_code` | String | 可选 | 128 | 业务结果原因码 | 结合 decision 或 `consume_status` 使用;不要按原因文案编写业务分支 | - | | `update_time` | String | 必选 | 32 | 更新时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | - | `2026-09-07 10:05:00` | #### 结果处理 | 情况 | 平台处理 | | --- | --- | | `code=10000` 且 `consume_status=SUCCEEDED` | 确认本次扣减,保存 consumed、remaining、consume_order_id;避免重复交付 | | `code=10000` 且 `consume_status=FAILED` | 按 reason_code 处理,不标记核销成功 | | `code=10000` 且 `consume_status=PROCESSING` | 保留原请求号,调用 quota.refresh 查询 | | 余额不足业务错误 | 提示购买或补充额度,不标记消费成功 | | 超时、系统错误、未知状态 | 标记本地待确认,使用原请求查询或重试,不换号 | `code=10000` 不能单独作为扣减成功依据;同样不能只处理 `consume_status` 而忽略网关失败。 #### 响应示例 以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpay_quota_verify_response": { "code": "10000", "msg": "Success", "consume_status": "SUCCEEDED", "consume_order_id": "202609071000000001", "quota_unit": "COUNT", "consumed": 1, "remaining": 19, "update_time": "2026-09-07 10:05:00", "consume_reason": "生成一篇文章" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_quota_verify_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ##### 余额不足错误示例 ```json { "alipay_aipay_nowpay_quota_verify_response": { "code": "40004", "msg": "Business Failed", "sub_code": "NOW_PAY_QUOTA_INSUFFICIENT", "sub_msg": "额度不足" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充平台处理建议。错误码列表可能扩展,平台应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 商品不是额度包模式 | 请核对入参参数相关的商品配置信息 | | `CONSUME_REQUEST_NOT_FOUND` | 未找到匹配的幂等请求记录,请确认幂等号和请求状态 | 核对原请求号与商品;继续查询或原参数重试核销,不因未找到记录直接换号 | | `NOW_PAY_QUOTA_INSUFFICIENT` | 额度不足 | 提示购买或补充额度;本次不记为核销成功 | --- ### 商品额度核销结果查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 商品额度核销结果查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/quota_refresh.md 使用原消费请求号查询一笔额度核销的处理结果,用于核销超时、处理中或结果丢失后的恢复。此接口不刷新或增加余额,也不会发起新的额度扣减。 #### 接口说明 接口名称:`alipay.aipay.nowpay.quota.refresh` 使用原消费请求号查询一笔额度核销的处理结果,用于核销超时、处理中或结果丢失后的恢复。此接口不刷新或增加余额,也不会发起新的额度扣减。 #### 适用场景 - `quota.verify` 超时,无法确定是否已扣减。 - 核销返回 `PROCESSING`,需要继续查询最终状态。 - 恢复平台本地未确认的消费记录。 #### 注意事项 - `out_request_no`、商品和受益人应与原 `quota.verify` 请求完全对应;无需重复传入 amount 或 `consume_reason`。 - 查询成功只表示获得了记录,仍需检查 `consume_status`。`SUCCEEDED` 完成本地消费确认,`FAILED` 按原因处理,`PROCESSING` 继续查询。 - 未找到记录时,不代表原请求一定未执行。核对原请求号并继续查询,或用完全相同的原请求重试 `quota.verify`,不能换新请求号重复扣减。 - remaining 表示原核销成功时的扣减后余额,后续购买或消费可能已改变余额;查询最新余额使用 `quota.query`。 - `consume_reason` 可能不返回,业务原因请读取平台持久化的原始消费记录。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.quota.refresh` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | String | 必选 | 128 | 平台生成的幂等请求号 | 重试保持原值与原业务参数;不同请求使用不同值 | `consume_20260907_000001` | | `out_product_id` | String | 必选 | 128 | 平台内稳定的商品或应用标识 | - | `app_writing_001` | | `external_owner_id` | String | 可选 | 128 | 平台内稳定的创作者或商品所有者标识 | 与配置时使用的标识一致;不是必须填写支付宝账号 | `creator_001` | | `external_buyer_id` | String | 必选 | 128 | 平台内稳定的权益受益人标识 | 与平台登录用户绑定;不等同于付款账号 | `user_001` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在平台服务端。cURL 中的签名需在发送前按全部实际参数生成;如增加 `app_auth_token`,应一起参与签名。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayQuotaRefreshRequest; import com.alipay.api.response.AlipayAipayNowpayQuotaRefreshResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayQuotaRefreshRequest request = new AlipayAipayNowpayQuotaRefreshRequest(); request.setBizContent("{\"out_request_no\":\"consume_20260907_000001\",\"out_product_id\":\"app_writing_001\",\"external_owner_id\":\"creator_001\",\"external_buyer_id\":\"user_001\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayQuotaRefreshResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_request_no": "consume_20260907_000001", "out_product_id": "app_writing_001", "external_owner_id": "creator_001", "external_buyer_id": "user_001" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.quota.refresh' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_quota_refresh_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `consume_status` | String | 必选 | 32 | 核销状态 | 成功:`SUCCEEDED`;失败:`FAILED`;进行中:`PROCESSING` | `SUCCEEDED` | | `consume_order_id` | String | 可选 | 128 | 消费流水标识 | - | `202609071000000001` | | `consume_reason` | String | 可选 | 256 | 消费原因 | 平台应持久化原始原因;查询结果可能不返回 | - | | `quota_unit` | String | 必选 | 32 | 额度类型 | `COUNT`:次数;`POINT`:积分 | `COUNT` | | `consumed` | Number | 必选 | 32 | 本次实际扣减量,单位次数或积分 | 非成功状态按 0 处理,不据此确认成功 | `1` | | `remaining` | Number | 特殊可选 | 32 | 本次核销成功时,原子扣减后的可消费余额 | 仅 `SUCCEEDED` 时使用;不是当前实时余额 | `19` | | `reason_code` | String | 可选 | 128 | 业务结果原因码 | 结合 decision 或 `consume_status` 使用;不要按原因文案编写业务分支 | - | | `update_time` | String | 必选 | 32 | 更新时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | - | `2026-09-07 10:05:00` | #### 结果处理 处理规则与 [核销次数或积分](https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/quota_verify.md) 一致。仅在 `code=10000` 且 `consume_status=SUCCEEDED` 时确认原核销成功。未找到记录、超时、处理中及未知状态都进入平台待确认流程,保留原请求号。 #### 响应示例 以下为按单一业务场景整理的示例。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpay_quota_refresh_response": { "code": "10000", "msg": "Success", "consume_status": "SUCCEEDED", "consume_order_id": "202609071000000001", "quota_unit": "COUNT", "consumed": 1, "remaining": 19, "update_time": "2026-09-07 10:05:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_quota_refresh_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ##### 请求未查询到错误示例 ```json { "alipay_aipay_nowpay_quota_refresh_response": { "code": "40004", "msg": "Business Failed", "sub_code": "CONSUME_REQUEST_NOT_FOUND", "sub_msg": "额度不足" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充平台处理建议。错误码列表可能扩展,平台应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 商品不是额度包模式 | 请核对入参参数相关的商品配置信息 | | `CONSUME_REQUEST_NOT_FOUND` | 未找到匹配的幂等请求记录,请确认幂等号和请求状态 | 核对原请求号与商品;继续查询或原参数重试核销,不因未找到记录直接换号 | --- ### 商品基础信息修改接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 商品基础信息修改接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/product_modify.md #### 接口说明 接口名称:`alipay.aipay.nowpay.product.modify` 修改商品基础信息,包括商品名称、简短描述、图标地址和商品详情地址。通过外部平台商品所有者标识与商品或应用标识定位商品。 #### 适用场景 - 商品名称或简短描述调整后,同步商品基础信息。 - 商品图标或详情页地址变更后,更新对应地址。 #### 注意事项 - `external_owner_id`、`out_product_id` 为必选字段;其余四个商品信息字段为可选字段。 - 原文未说明可选字段省略、传空字符串或传 `null` 时的更新语义,也未说明是否必须至少传入一个修改字段;接入时需核对这些规则。 - 请求需按 接口 规则签名;修改请求体或参与签名的请求信息后,应重新生成签名。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.product.modify` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `external_owner_id` | String | 必选 | 128 | 外部平台商品所有者标识 | - | `usr_01` | | `out_product_id` | String | 必选 | 128 | 外部平台商品/应用标识 | - | `gc_1001002` | | `product_name` | String | 可选 | 128 | 新商品名称 | - | `写作助手` | | `product_description` | String | 可选 | 4096 | 新简短描述 | - | `智能提示` | | `product_icon_url` | String | 可选 | 4096 | 新图标地址 | - | https://mdn.alipayobjects.com/
huamei_82ubz2/afts/img/
vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/
original | | `product_url` | String | 可选 | 4096 | 新商品详情地址 | - | https://aipay.alipay.com/
community/events/
payathon-2026 | #### 常见请求示例 以下沿用原文商品信息示例。发送前需准备实际应用 ID、时间戳、随机串、请求标识及签名;签名需基于本次实际请求生成。授权令牌按实际调用场景配置。 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "external_owner_id": "usr_01", "out_product_id": "gc_1001002", "product_name": "写作助手", "product_description": "智能提示", "product_icon_url": "https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original", "product_url": "https://aipay.alipay.com/community/events/payathon-2026" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.product.modify' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayProductModifyRequest; import com.alipay.api.response.AlipayAipayNowpayProductModifyResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayProductModifyRequest request = new AlipayAipayNowpayProductModifyRequest(); request.setBizContent("{\"external_owner_id\":\"usr_01\",\"out_product_id\":\"gc_1001002\",\"product_name\":\"写作助手\",\"product_description\":\"智能提示\",\"product_icon_url\":\"https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original\",\"product_url\":\"https://aipay.alipay.com/community/events/payathon-2026\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayProductModifyResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_product_modify_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `product_name` | String | 必选 | 128 | 新商品名称 | `写作助手` | | `product_description` | String | 必选 | 4096 | 新简短描述 | `智能提示` | | `product_icon_url` | String | 必选 | 4096 | 新图标地址 | https://mdn.alipayobjects.com/
huamei_82ubz2/afts/img/
vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/
original | | `product_url` | String | 必选 | 4096 | 新商品详情地址 | https://aipay.alipay.com/
community/events/
payathon-2026 | #### 结果处理 - 调用成功:读取响应中的四个商品基础信息字段,更新平台侧展示。 - 返回 `INVALID_PARAMETER`:根据具体错误信息修正参数后重试。 - 返回 `SYSTEM_ERROR`:原文允许使用同样的请求重试。重新发送时,应按实际请求重新生成认证签名。 - 其他失败:结合 HTTP 状态和 接口 公共错误码处理,并保留请求标识以便排查。 #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "product_name": "写作助手", "product_description": "智能提示", "product_icon_url": "https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original", "product_url": "https://aipay.alipay.com/community/events/payathon-2026" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_product_modify_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常,可能发生了网络或者系统异常,导致服务调用失败;商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 根据接口返回的参数非法的具体错误信息,修改参数后重试 | --- ### 批量查询商品接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 批量查询商品接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/product_batchquery.md #### 接口说明 接口名称:`alipay.aipay.nowpay.product.batchquery` 批量查询指定外部平台资源归属账号下的商品,返回命中的商品列表;无命中时返回空数组。 #### 适用场景 - 根据多个外部商品 ID,批量获取商品信息。 - 在商品列表页集中展示商品基础信息和收费配置。 - 查询指定商品的记录状态及创建、修改时间。 #### 注意事项 - `external_owner_id`、`out_product_ids` 均为必选字段。 - `out_product_ids` 的列表范围为 0~100;原文同时标注长度范围为 1~4096,但未明确该长度约束的适用对象,接入时需核对。 - 无命中时 `items` 为空数组。按每个元素的 `out_product_id` 关联平台商品,不依赖返回顺序。 - 原文未展开 `NowpayProduct` 及收费配置子字段的完整定义。下文子字段根据响应示例整理,未提供的必选性、长度和完整枚举不作推定。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.product.batchquery` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `external_owner_id` | String | 必选 | 128 | 外部平台资源归属账号 | - | `usr_01` | | `out_product_ids` | String[] | 必选 | 4096 | 外部商品 ID 列表 | 列表范围:0~100 | ["pro_01",
"pro_02"] | #### 常见请求示例 以下账号和商品 ID 均为演示值。Java 使用支付宝服务端 SDK;私钥保存在平台服务端。cURL 签名需基于本次实际请求生成,授权令牌按实际调用场景配置。 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "external_owner_id": "usr_01", "out_product_ids": [ "pro_01", "pro_02" ] }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.product.batchquery' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayProductBatchqueryRequest; import com.alipay.api.response.AlipayAipayNowpayProductBatchqueryResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayProductBatchqueryRequest request = new AlipayAipayNowpayProductBatchqueryRequest(); request.setBizContent("{\"external_owner_id\":\"usr_01\",\"out_product_ids\":[\"pro_01\",\"pro_02\"]}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayProductBatchqueryResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_product_batchquery_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 下表数组子字段使用 `[]` 表示元素路径。“未提供”表示来源未展开字段定义,字段名称和示例值来自正常响应示例。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `items` | NowpayProduct[] | 必选 | - | 命中的商品列表;无命中时为空数组 | `[]` | | `items[].out_product_id` | String | 未提供 | 未提供 | 外部商品 ID | `gc_1001002` | | `items[].product_id` | String | 未提供 | 未提供 | 商品 ID | `P0806000200867536` | | `items[].product_name` | String | 未提供 | 未提供 | 商品名称 | `写作助手` | | `items[].product_icon_url` | String | 未提供 | 未提供 | 商品图标地址 | https://mdn.alipayobjects.com/
huamei_82ubz2/afts/img/
vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/
original | | `items[].product_url` | String | 未提供 | 未提供 | 商品详情地址 | https://aipay.alipay.com/
community/events/
payathon-2026 | | `items[].product_description` | String | 未提供 | 未提供 | 商品描述 | `描述` | | `items[].record_status` | String | 未提供 | 未提供 | 商品记录状态;完整枚举未提供 | `INIT` | | `items[].pricing_mode_list` | Object[] | 未提供 | 未提供 | 收费配置列表 | 见响应示例 | | `items[].pricing_mode_list[].billing_mode` | String | 未提供 | 未提供 | 收费模式 | `ONE_TIME` | | `items[].pricing_mode_list[].price` | String | 未提供 | 未提供 | 价格 | `0.01` | | `items[].pricing_mode_list[].display_name` | String | 未提供 | 未提供 | 收费配置展示名称 | `一次性买断` | | `items[].pricing_mode_list[].currency` | String | 未提供 | 未提供 | 币种 | `CNY` | | `items[].pricing_mode_list[].duration_period` | String | 未提供 | 未提供 | 时长周期 | `WEEK` | | `items[].pricing_mode_list[].quota_unit` | String | 未提供 | 未提供 | 额度单位 | `COUNT` | | `items[].pricing_mode_list[].quota_amount` | Number | 未提供 | 未提供 | 额度数量 | `10` | | `items[].gmt_create` | String | 未提供 | 未提供 | 创建时间 | `2026-10-10 10:10:10` | | `items[].gmt_modified` | String | 未提供 | 未提供 | 修改时间 | `2026-10-10 10:10:10` | #### 结果处理 - 调用成功:遍历 `items`,根据 `out_product_id` 关联并更新对应商品信息。 - `items` 为空数组:本次查询无命中商品。 - 返回 `INVALID_PARAMETER`:根据具体错误信息检查归属账号、商品 ID 列表及数量,修正后重试。 - 返回 `SYSTEM_ERROR`:可使用同样的业务参数重试;重新发送时按实际请求生成签名。 #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} 以下沿用来源示例。实际收费模式与周期、额度字段的适用关系以接口返回及完整字段定义为准。 ```json { "items": [ { "out_product_id": "gc_1001002", "product_id": "P0806000200867536", "product_name": "写作助手", "product_icon_url": "https://mdn.alipayobjects.com/huamei_82ubz2/afts/img/vr_lQonyBf8AAAAAQBAAAAgADup2AQJr/original", "product_url": "https://aipay.alipay.com/community/events/payathon-2026", "product_description": "描述", "record_status": "INIT", "pricing_mode_list": [ { "billing_mode": "ONE_TIME", "price": "0.01", "display_name": "一次性买断", "currency": "CNY", "duration_period": "WEEK", "quota_unit": "COUNT", "quota_amount": 10 } ], "gmt_create": "2026-10-10 10:10:10", "gmt_modified": "2026-10-10 10:10:10" } ] } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_product_batchquery_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常,可能发生了网络或者系统异常,导致服务调用失败;商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 根据接口返回的参数非法的具体错误信息,修改参数后重试 | --- ### 商品权益购买结果查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 平台模式接入 > API列表 > 商品权益购买结果查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/platform/api_list/platform_purchase_query.md #### 接口说明 接口名称:`alipay.aipay.nowpay.purchase.query` 查询即刻收平台商品购买结果。通过外部商品标识、平台商品所有者标识和平台买家标识定位查询范围,并可使用创建购买链接时的请求幂等号、购买链接标识及指定档位查询对应购买结果。 #### 适用场景 - 买家完成购买流程后,查询商品购买结果。 - 额度包购买后,使用原请求幂等号或购买链接标识查询对应订单结果。 - 创建购买链接时指定了档位,携带该档位标识查询购买结果。 #### 注意事项 - `out_product_id`、`external_owner_id`、`external_buyer_id` 为必选字段,需与实际商品及买家对应。 - 额度包查询必须传入 `out_request_no` 或 `purchase_link_id`,否则返回 `ILLEGAL_PARAMETERS`。 - 额度包场景尽量传入创建购买链接时的 `out_request_no`;原文提示,不传时超过半小时的订单无法查询结果。 - `purchase_link_id` 使用 `purchase.create` 或 `purchase.consult` 返回的购买链接标识,按原值保存和传入。 - `purchase.create` 创建购买链接时若指定了档位,查询时需传入对应的 `sku_id`。 - 原文枚举说明存在错列,将 `SUCCESS`、`WAIT_PAY` 分别与商品类型并列展示。本文保留状态值;状态与商品类型的对应关系需在接入时核对。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpay.purchase.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 外部商品标识 | - | `app_1029001` | | `external_owner_id` | String | 必选 | 128 | 平台商品所有者标识 | - | `owner_10001` | | `external_buyer_id` | String | 必选 | 128 | 平台买家标识 | - | `buyer_10001` | | `out_request_no` | String | 可选 | 64 | `purchase.create` 创建购买链接时传入的请求幂等号 | 额度包查询必须传入本字段或 `purchase_link_id`;尽量传入本字段,否则超过半小时的订单无法查询结果 | 1c4c07f08f4f41a8
9615c1f2e212d3e0 | | `purchase_link_id` | String | 可选 | 128 | `purchase.create` / `purchase.consult` 响应中的购买链接标识 | 额度包查询必须传入本字段或 `out_request_no` | Tk9XUEFZOlBVUkNIQVNFOjgy
NzQ2Y2M2MWNkMDRmNGJhYTVi
NDZmYTIyMzVhNjE4XyQ3MA | | `sku_id` | String | 可选 | 32 | 指定档位标识 | 创建购买链接时若指定档位,查询时需传入 | `S0806000200864400` | #### 常见请求示例 以下商品、所有者、买家、请求号及购买链接标识均为演示值。Java 使用支付宝服务端 SDK;私钥保存在平台服务端。cURL 签名需基于本次实际请求生成,授权令牌按实际调用场景配置。 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "app_1029001", "external_owner_id": "owner_10001", "external_buyer_id": "buyer_10001", "out_request_no": "1c4c07f08f4f41a89615c1f2e212d3e0", "purchase_link_id": "Tk9XUEFZOlBVUkNIQVNFOjgyNzQ2Y2M2MWNkMDRmNGJhYTViNDZmYTIyMzVhNjE4XyQ3MA", "sku_id": "S0806000200864400" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpay.purchase.query' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpayPurchaseQueryRequest; import com.alipay.api.response.AlipayAipayNowpayPurchaseQueryResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpayPurchaseQueryRequest request = new AlipayAipayNowpayPurchaseQueryRequest(); request.setBizContent("{\"out_product_id\":\"app_1029001\",\"external_owner_id\":\"owner_10001\",\"external_buyer_id\":\"buyer_10001\",\"out_request_no\":\"1c4c07f08f4f41a89615c1f2e212d3e0\",\"purchase_link_id\":\"Tk9XUEFZOlBVUkNIQVNFOjgyNzQ2Y2M2MWNkMDRmNGJhYTViNDZmYTIyMzVhNjE4XyQ3MA\",\"sku_id\":\"S0806000200864400\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpayPurchaseQueryResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpay_purchase_query_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `purchase_status` | String | 必选 | 32 | 购买结果 | `SUCCESS` / `WAIT_PAY` / `UNKNOWN`;`UNKNOWN` 表示参数不全,无法确认 | `SUCCESS` | | `trade_no` | String | 可选 | 64 | 支付宝订单号 | 按实际返回读取 | `2026100122001431111104111324` | #### 结果处理 - `purchase_status` 为 `SUCCESS`:按购买成功处理,并记录返回的支付宝订单号。 - `purchase_status` 为 `WAIT_PAY`:按待支付处理,可在买家完成支付后再次查询。 - `purchase_status` 为 `UNKNOWN`:参数不全,无法确认购买结果;补充原请求幂等号、购买链接标识或所需档位后查询,不按购买成功处理。 - 返回 `ILLEGAL_PARAMETERS`:额度包查询补充 `out_request_no` 或 `purchase_link_id` 后重试。 - 返回 `NOW_PAY_BINDING_INVALID`:核对外部商品标识及平台商品所有者标识。 - 返回 `NOW_PAY_NO_PERMISSION`:核对订单是否属于当前平台买家,不按购买成功处理。 - 返回 `SYSTEM_ERROR`:可使用同样的业务参数重试;重新发送时按实际请求生成签名。 #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "purchase_status": "SUCCESS", "trade_no": "2026100122001431111104111324" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpay_purchase_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常,可能发生了网络或者系统异常,导致服务调用失败;商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 根据接口返回的参数非法的具体错误信息,修改参数后重试 | | `ILLEGAL_PARAMETERS` | 缺少必要参数:`out_request_no` 或 `purchase_link_id` | 额度包查询必须传入 `out_request_no` 或 `purchase_link_id` | | `NOW_PAY_BINDING_INVALID` | 商品不存在或商品标识与所有者不匹配 | 商品不存在,请核对商品标识和所有者标识 | | `NOW_PAY_NO_PERMISSION` | 订单归属越权 | 所查订单不属于当前平台买家,请核对买家标识及订单归属 | --- ### 接入指南 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 直连模式接入 > 接入指南 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/nowpay-direct.md 直连模式接入指南 #### 即刻收直连模式接入指南 ##### 适用场景 直连模式面向独立开发者、创作者或自行经营应用的商户。商户在支付宝管理小程序完成商品配置,应用服务端直接调用即刻收 OpenAPI,为应用用户提供托管购买、权益校验以及次数/积分核销能力。 ###### 支持的收费模式 | 收费模式 | billing_mode | 权益或额度 | 应用使用方式 | 重复购买 | | --- | --- | --- | --- | --- | | 永久买断 | `ONE_TIME` | 永久使用权益 | 使用前查询访问决策 | 已有有效权益时不再购买 | | 时长包 | `ONE_TIME_DURATION` | 固定有效期权益 | 使用前查询访问决策,可展示有效期 | 有效期内不续购;到期后按查询结果购买 | | 次数包 | `QUANTITY`,`quota_unit=COUNT` | 可消耗次数 | 查询余额,每次服务按约定数量核销 | 可加购,新增额度累加 | | 积分包 | `QUANTITY`,`quota_unit=POINT` | 可消耗积分 | 查询余额,按服务规则核销积分 | 可加购,新增额度累加 | 同一商品最终采用一种收费模式,该模式下可配置多个档位。例如,次数包可提供“20 次包”和“100 次包”,用户购买后增加相应次数。 时长包支持以下周期,按日历计算,不能将“一个月”固定换算成 30 天: | duration_period | 对客名称 | 计算口径 | | --- | --- | --- | | `WEEK` | 一周 | 按日历增加 1 周 | | `MONTH` | 一个月 | 按日历增加 1 个月 | | `QUARTER` | 三个月 | 按日历增加 3 个月 | | `YEAR` | 一年 | 按日历增加 1 年 | 本接入范围支持买断、固定周期时长包和次数/积分额度包,不包含自动续费、任意天数、有效期内时长续购或核销撤销。商品资料、价格与上下架以管理小程序支持的操作为准。 ##### 接入准备 ###### 商户与支付宝的职责 | 参与方 | 负责内容 | | --- | --- | | 商户/独立开发者 | 在管理小程序完成开通、商品资料、收费模式和档位配置,并管理商品上下架 | | 应用服务端 | 使用商户的应用凭证签名调用 API;维护业务用户标识及消费记录;按权益和核销结果控制服务 | | 应用客户端 | 展示商品、价格和余额;打开购买入口或展示二维码;页面返回后触发服务端查询 | | 即刻收 | 提供托管购买页、支付与权益处理、权益查询和额度核销能力 | ###### 开始前完成以下准备 1. 在管理小程序(支付宝搜索 **即刻收** ,或扫描集成流程中的小程序码进入)完成所需认证与签约,创建商品并配置收费模式、档位和价格;等待商品可售。 2. 在商品详情页复制商品 ID,作为接口入参 `out_product_id`。该 ID 由即刻收生成,必须使用本次调用商户名下的商品,不可自行编造。 3. 准备支付宝应用 `app_id`、应用私钥、对应支付宝公钥,完成所需接口权限与直连接入配置。应用调用身份应与商品所属商户一致;已获授权的第三方代理调用按授权规则传入 `app_auth_token`。 4. 应用服务端接入支付宝 SDK,配置签名和验签。网关为 `https://openapi.alipay.com/gateway.do`,版本为 `1.0`,使用 `RSA2`、`UTF-8` 和 JSON。 5. 为自身业务用户维护稳定的会员id标识,对应参数 `external_buyer_id`,保存购买入口请求和消费请求的业务上下文,支付前后及后续查询、核销必须保持一致。 ##### 手动集成 ###### 第一步:在管理小程序配置商品,查询可售状态 **子章节:** 商品配置 章节路径:即刻收直连模式接入指南 > 手动集成 > 第一步:在管理小程序配置商品,查询可售状态 > 商品配置 1、支付宝搜索 **即刻收** ,如未搜索到可扫码进入 ::aipay-image{src="https://mdn.alipayobjects.com/aipay_assets/afts/file/XJiWQ4FxxGEAAAAASeAAAAgAeoh5AQJr" width="100%"} 2、配置商品 ::aipay-image{src="https://mass.alipay.com/aipay_assets/afts/file/3qkfQ5Zlg2AAAAAASHAAAAgAeoh5AQJr" width="100%"} **子章节:** 系统流程 章节路径:即刻收直连模式接入指南 > 手动集成 > 第一步:在管理小程序配置商品,查询可售状态 > 系统流程 ```mermaid sequenceDiagram autonumber actor M as 商户 participant C as 即刻收管理小程序 participant N as 即刻收 participant S as 应用服务端 M->>C: 填写商品资料、收费方式和档位价格 C->>N: 提交商品配置 opt 需要完成开通 C-->>M: 展示认证与签约步骤 M->>C: 完成认证、签约 C->>N: 继续处理商品申请 end N->>N: 创建商品、审核与发布 N-->>C: 商品状态、外部商品 ID M->>C: 进入商品详情,复制商品 ID M->>S: 配置 out_product_id S->>N: alipay.aipay.nowpaydirect.charge.query N-->>S: capability_status、billing_mode、charging_options S->>S: ENABLED 时展示新增购买入口 ``` 商户在小程序完成全部商品配置。直连模式不提供商品初始化、商品配置或商品启停 OpenAPI,开发者无需对接小程序内部接口。 调用 [alipay.aipay.nowpaydirect.charge.query(查询商品收费能力和档位)](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/charge_query.md),`biz_content` 示例: ```json { "out_product_id": "np_d_f83a7c91" } ``` 从响应读取实际 `billing_mode`、`quota_unit` 和 `charging_options`。同一商品采用一种收费模式,可在该模式下配置多个档位;价格由小程序配置,应用不通过购买接口传入价格。 **子章节:** 收费状态与页面处理 章节路径:即刻收直连模式接入指南 > 手动集成 > 第一步:在管理小程序配置商品,查询可售状态 > 收费状态与页面处理 | capability_status | 商品含义 | 处理方式 | | --- | --- | --- | | `NOT_CONFIGURED` | 未找到收费配置 | 核对当前商户与商品 ID,在小程序完成配置 | | `CONFIGURING` | 配置尚未完成 | 在小程序继续配置 | | `PENDING` | 等待审核或发布 | 在小程序查看进度 | | `ACTION_REQUIRED` | 需要商户处理 | 在小程序处理认证、签约或商品资料 | | `ENABLED` | 允许新增购买 | 展示购买入口 | | `DISABLED` | 停止新增购买 | 隐藏新购买入口;已有权益继续按权益接口判断 | | `TERMINATED` | 商品已归档 | 不新增购买,在小程序查看状态 | 查询返回 `management_url` 时,可供商品所有者进入管理页;不要将管理地址作为用户购买入口。商品不可售时仍可能返回档位,不能只看档位列表非空就判定可以购买。 商品收费状态与用户权益状态分别判断。已下架不能直接推断已有权益失效;已上架也不意味着用户已获得权益。 ###### 第二步:按收费模式选择流程 | billing_mode | 使用前查询 | 需要购买时 | 支付页面返回后 | 实际消费时 | | --- | --- | --- | --- | --- | | `ONE_TIME` | alipay.aipay.nowpaydirect.purchase.consult | 使用 alipay.aipay.nowpaydirect.purchase.consult 返回的购买入口,或通过 alipay.aipay.nowpaydirect.purchase.create 选择指定档位 | 再查 alipay.aipay.nowpaydirect.purchase.consult | 按访问决策放行 | | `ONE_TIME_DURATION` | alipay.aipay.nowpaydirect.purchase.consult | 同上 | 再查 alipay.aipay.nowpaydirect.purchase.consult,读取当前有效期 | 按访问决策放行 | | `QUANTITY` | alipay.aipay.nowpaydirect.quota.query | alipay.aipay.nowpaydirect.purchase.create | 再查 alipay.aipay.nowpaydirect.quota.query | alipay.aipay.nowpaydirect.quota.verify;结果未知用 alipay.aipay.nowpaydirect.quota.refresh | **子章节:** 买断和时长包 章节路径:即刻收直连模式接入指南 > 手动集成 > 第二步:按收费模式选择流程 > 买断和时长包 ```mermaid sequenceDiagram autonumber participant U as 用户 participant P as 应用 participant N as 即刻收 OpenAPI participant H as 支付宝托管购买页 U->>P: 使用付费功能 P->>N: alipay.aipay.nowpaydirect.purchase.consult N-->>P: decision alt ALLOW P-->>U: 开放服务 else PURCHASE_REQUIRED P-->>U: 展示购买入口 U->>H: 选择档位并支付 H-->>P: 返回 callback_url P->>N: alipay.aipay.nowpaydirect.purchase.consult N-->>P: 最新 decision P-->>U: 按查询结果开放服务或提示刷新 else DENY P-->>U: 不开放服务,按原因展示说明 end ``` 调用 [alipay.aipay.nowpaydirect.purchase.consult(查询买断或时长访问决策)](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/purchase_consult.md),业务入参示例: ```json { "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001", "callback_url": "https://app.example.com/nowpay/purchase-return" } ``` | decision | 应用操作 | | --- | --- | | `ALLOW` | 放行。时长包按返回的 `valid_from`、`valid_until` 展示有效期 | | `PURCHASE_REQUIRED` | 使用返回的 `purchase_url` 或 `purchase_qr_code` 引导购买 | | `DENY` | 不放行、不新建购买入口;根据 `reason_code` 展示说明或刷新 | 时长包权益区间为 `[valid_from, valid_until)`,在结束时间点失效。有效权益存在时,不引导用户重复购买。购买返回后仍需重新查询,只有新的 `decision=ALLOW` 才开放服务。 `purchase.consult` 不要求幂等请求号,多次查询可能产生不同购买入口;需要请求级幂等时使用 `purchase.create`。 若支付页面返回后权益暂未可用,可进行有限次查询并提示稍后刷新。不要因暂未查到权益而直接认定支付失败、自动再次支付或重复开放服务。 **子章节:** 次数包和积分包 章节路径:即刻收直连模式接入指南 > 手动集成 > 第二步:按收费模式选择流程 > 次数包和积分包 ```mermaid sequenceDiagram autonumber participant U as 用户 participant P as 应用 participant N as 即刻收 OpenAPI participant H as 支付宝托管购买页 P->>N: alipay.aipay.nowpaydirect.quota.query N-->>P: quota_unit / total / used / remaining P->>P: 按服务规则计算所需额度 opt 额度不足或用户主动加购 P->>N: alipay.aipay.nowpaydirect.purchase.create N-->>P: purchase_url / expire_time U->>H: 确认购买并支付 H-->>P: 返回 callback_url P->>N: alipay.aipay.nowpaydirect.quota.query N-->>P: 最新余额 end P->>P: 持久化消费请求号及业务参数 Note over P,N: 应用按约定的服务交付时点发起正式核销 P->>N: alipay.aipay.nowpaydirect.quota.verify N-->>P: 核销状态或业务错误 opt 处理中、超时或结果未知 P->>N: alipay.aipay.nowpaydirect.quota.refresh(原请求号) N-->>P: 核销结果 end P->>P: 按最终结果更新消费和服务记录 ``` 1. 调用 [alipay.aipay.nowpaydirect.quota.query(查询次数或积分余额)](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/quota_query.md),展示用户的可用余额。未购买时返回零余额,查询失败不按零余额处理。`remaining` 已排除预占,不能用 `total-used` 替代。 2. 应用按具体服务规则计算所需额度,例如生成一篇文章消耗 1 次,处理一次复杂任务消耗 10 积分。 3. 额度不足或用户主动加购时,调用 [alipay.aipay.nowpaydirect.purchase.create(获取购买链接)](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/purchase_create.md)。可传入查询得到的 `sku_id` 锁定档位,也可省略,让用户在购买页选择。 4. 用户返回后调用 `alipay.aipay.nowpaydirect.quota.query` 刷新余额。未到账时有限次刷新或提示稍后查询。 5. 在应用确定的服务交付时点,调用 [alipay.aipay.nowpaydirect.quota.verify(核销次数或积分)](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/quota-verify.md)。前置余额充足仍需正式核销,不能仅按余额查询结果执行本地扣减。 6. 对处理中或未知结果,使用原 `out_request_no` 调用 [alipay.aipay.nowpaydirect.quota.refresh(查询核销结果)](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/quota-verify-query.md),或用完全相同的原参数重试核销。 指定档位购买的 `biz_content` 示例: ```json { "out_request_no": "purchase_20260927_000001", "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001", "sku_id": "S0806000200863003", "callback_url": "https://app.example.com/nowpay/purchase-return" } ``` `sku_id` 不指定时打开普通购买页。应用不传价格或价格版本参与创单;即刻收在用户确认购买时重新校验商品和档位。购买链接与二维码按不透明入口使用,不解析令牌,不自行拼接。 **子章节:** 额度核销与恢复示例 章节路径:即刻收直连模式接入指南 > 手动集成 > 第二步:按收费模式选择流程 > 额度核销与恢复示例 以下两组参数对应同一笔消费,查询必须使用核销时的原请求号。次数核销也必须显式传入 `amount=1`。 ::::aipay-tabs{defaultActiveKey="核销额度"} :::aipay-tab{key="核销额度" title="核销额度"} ```json { "out_request_no": "consume_20260927_000001", "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001", "amount": 1, "consume_reason": "生成一篇文章" } ``` ::: :::aipay-tab{key="查询原核销结果" title="查询原核销结果"} ```json { "out_request_no": "consume_20260927_000001", "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001" } ``` ::: :::: `consume_reason` 使用最长 256 字符的业务说明,应用自行持久化(当前代码限制严于预览文档的 512 字符)。不要填写完整提示词、用户隐私、业务 JSON 等内容,也不要依赖查询结果回传该字段恢复原业务上下文。 | 核销结果 | 是否确认扣减 | 应用处理 | | --- | --- | --- | | `code=10000` 且 `consume_status=SUCCEEDED` | 是 | 保存核销流水、实扣量及结果,按业务约定完成服务记录 | | `code=10000` 且 `consume_status=FAILED` | 否 | 按原因处理;余额不足引导补充额度 | | `code=10000` 且 `consume_status=PROCESSING` | 待确认 | 使用原请求号查询,避免并发重扣 | | `NOW_PAY_QUOTA_INSUFFICIENT` | 本次请求未确认成功 | 处理余额不足,不将网关失败忽略为正常成功 | | 网络超时、系统错误或未知状态 | 待确认 | 保存原请求,查询或原参数重试 | | 核销记录不存在 | 待确认 | 核对请求号与商品,继续查询或原参数重试;不换号重扣 | 应用应同时处理业务错误码和成功响应中的核销状态。`PROCESSING` 时 `consumed`、`remaining` 可能缺失,不能补零后推断结果。`remaining` 仅在成功扣减时用作该笔扣减后的余额;结果查询返回的是原核销结果,需要实时余额时调用 `alipay.aipay.nowpaydirect.quota.query`。 核销与应用自身服务交付是两个动作。应用须根据业务明确先核销还是先交付,并对服务执行、超时恢复、交付失败处理做一致设计。当前能力不提供核销成功后的自动返还,不应将核销当作可自动释放的预占。应用服务端应记录并校验消费记录的用户归属,结果查询使用原消费记录中的参数。 ###### 第三步:在管理小程序维护商品 商户在管理小程序查看审核进度、处理资料和管理上下架。操作后调用 `alipay.aipay.nowpaydirect.charge.query` 刷新应用中的商品状态。 下架停止新增购买,原有买断、时长包或额度权益仍按对应接口结果处理;下架操作不等同于退款或回收权益。 ##### 请求与响应处理 ###### 服务端调用 业务参数序列化为 JSON 后放入 `biz_content`,与 `app_id`、`method`、`charset`、`sign_type`、`timestamp`、`version` 等公共参数一起签名提交。每份 API 文档均提供 Java 和 cURL 示例,参见 [API 文档索引](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/llms.txt)。 所有接口返回 JSON 业务结果,再由应用打开结果里的页面链接。接口调用使用服务端 SDK 的普通执行方法,如 Java 的 `execute`。不要将这些接口作为直接输出 HTML 支付表单的页面支付接口使用。 以额度查询为例,响应封装如下: ```json { "alipay_aipay_nowpaydirect_quota_query_response": { "code": "10000", "msg": "Success", "quota_unit": "COUNT", "total": 20, "used": 0, "remaining": 20, "as_of_time": "2026-09-27 10:00:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` 上例仅说明响应结构,签名不是有效签名。应用先验签、再判断 `code`;`code=10000` 只说明接口调用成功,业务是否允许访问或扣减是否成功,还需读取对应的业务状态。 ###### 幂等与重试 | 操作 | 应用应保存的定位信息 | 重试原则 | | --- | --- | --- | | alipay.aipay.nowpaydirect.purchase.create | 独立购买入口请求号及完整业务参数 | 默认有效期为 30 分钟 | | alipay.aipay.nowpaydirect.quota.verify | 消费请求号、商品、受益人、amount、consume_reason | 使用原请求号和原参数重试,或查询原核销结果 | | alipay.aipay.nowpaydirect.quota.refresh | 原消费请求的定位信息 | 只查询原核销记录,不生成新的核销号 | 商户应保证 `out_request_no` 在其业务范围内唯一,不跨商品、用户或不同消费复用。 对可恢复异常采用有限次数、带间隔的查询或重试;超过应用预设等待时间后保留“待确认”状态,由后续查询或排查恢复。不要因达到等待上限就将未知结果强制判为失败。 ###### 页面返回与通知 `callback_url` 仅用于用户操作结束后的页面跳转。买断与时长包在返回后查询 `alipay.aipay.nowpaydirect.purchase.consult`,额度包查询 `alipay.aipay.nowpaydirect.quota.query`,小程序商品管理操作后查询 `alipay.aipay.nowpaydirect.charge.query`。 ###### 错误处理 1. 网关或签名错误:按[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)排查公共参数、应用权限和验签配置。 2. 参数、商品或模式错误:按具体 API 的 `sub_code` 核对业务参数及商品配置;不依赖 `sub_msg` 的展示文案编写业务分支。 3. 核销余额不足:兼容 `NOW_PAY_QUOTA_INSUFFICIENT` 业务错误及 `FAILED` 的结果表达,不确认消费成功。 4. 幂等冲突:读取应用已保存的原请求进行核对;不能通过替换请求号掩盖一笔未确认的消费。 5. 核销未找到记录或依赖异常:保留原请求号,继续查询或原参数重试。 --- ### 商品收费能力查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 直连模式接入 > API列表 > 商品收费能力查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/charge_query.md 直连模式商品收费能力查询接口 #### 接口说明 接口名称:`alipay.aipay.nowpaydirect.charge.query` 查询当前商户在管理小程序中创建的直连商品,获取收费状态、收费模式、档位与商品管理入口。商品配置和上下架由商户在管理小程序操作。 #### 适用场景 - 商品完成小程序配置后,验证商品 `ID`、收费状态和档位。 - 在应用中展示商品价格、选择购买档位。 - 商户在小程序处理审核或上下架后,刷新商品状态。 #### 注意事项 - `out_product_id` 从管理小程序商品详情页复制,商品需属于本次请求的商户。直连模式无需调用收费初始化或启停 OpenAPI。 - 只有 `ENABLED` 表示允许新增购买。`NOT_CONFIGURED` 时核对商品 `ID` 和商户账号;`CONFIGURING`、`PENDING`、`ACTION_REQUIRED` 时到管理小程序继续配置或处理审核。 - `capability_status` 描述商品新增购买能力。用户是否可访问查询 `purchase.consult`;额度余额与扣减分别使用 `quota.query`、`quota.verify`。 - `charging_options` 按数组处理,可能为空;商品不可售时也可能保留档位,不能仅凭档位非空展示新购买入口。`billing_mode` 从查询到的档位得出,未配置或档位缺失时可能为空。 - `management_url` 供商户管理商品;终端用户购买应使用 `purchase.consult` 或 `purchase.create` 返回的入口。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpaydirect.charge.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-27 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 直连商品的外部商品 `ID`,从管理小程序商品详情页复制 | 使用当前商户创建的商品;不要自行生成或使用内部商品号 | `np_d_f83a7c91` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在应用服务端。cURL 中的签名需在发送前按全部实际参数生成。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpaydirectChargeQueryRequest; import com.alipay.api.response.AlipayAipayNowpaydirectChargeQueryResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpaydirectChargeQueryRequest request = new AlipayAipayNowpaydirectChargeQueryRequest(); request.setBizContent("{\"out_product_id\":\"np_d_f83a7c91\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpaydirectChargeQueryResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "np_d_f83a7c91" }' # app_id、timestamp、sign 由商户准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpaydirect.charge.query' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpaydirect_charge_query_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `capability_status` | String | 必选 | 32 | 商品收费能力状态 | `NOT_CONFIGURED` / `CONFIGURING` / `PENDING` / `ACTION_REQUIRED` / `ENABLED` / `DISABLED` / `TERMINATED` | `ENABLED` | | `product_name` | String | 特殊可选 | 32 | 商品名称 | 配置尚不存在时可能缺省,不因缺少名称认定收费已启用 | `智能写作助手` | | `product_icon_url` | String | 可选 | 1024 | 商品图标 | - | `https://app.example.com/assets/writing.png` | | `billing_mode` | String | 可选 | 32 | 最终收费模式 | 永久买断:`ONE_TIME`;时长包:`ONE_TIME_DURATION`;额度包:`QUANTITY` | `QUANTITY` | | `quota_unit` | String | 特殊可选 | 32 | 额度包单位 | `billing_mode`=`QUANTITY` 时使用;`COUNT`:次数,`POINT`:积分 | `COUNT` | | `charging_options` | Object[] | 必选 | - | 当前商品的收费档位列表 | 可能为空数组;子字段必选性适用于实际返回的档位元素 | - | | `charging_options[].sku_id` | String | 必选 | 32 | 档位标识 | 按不透明标识保存和回传,不解析内容 | `S0806000200863003` | | `charging_options[].display_name` | String | 必选 | 128 | 档位名称 | - | `20次包` | | `charging_options[].price` | String | 必选 | 32 | 展示价格,十进制,单位元 | - | `1.00` | | `charging_options[].duration_period` | String | 特殊可选 | 32 | 时长包周期类型 | `billing_mode`=`ONE_TIME_DURATION` 时返回;`WEEK` / `MONTH` / `QUARTER` / `YEAR` | `WEEK` | | `charging_options[].quota_amount` | Number | 特殊可选 | 32 | 额度数量 | `billing_mode`=`QUANTITY` 时返回;购买该档位增加的整数额度 | `20` | | `management_url` | String | 可选 | 1024 | 使用该地址进入商品管理 | 供商品所有者进入管理小程序;不要作为面向购买用户的购买入口 | `alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET` | #### 结果处理 | capability_status | 含义 | 应用或商户处理 | | --- | --- | --- | | `NOT_CONFIGURED` | 未找到收费配置 | 核对当前商户及小程序复制的商品 ID,在小程序完成配置 | | `CONFIGURING` | 配置尚未完成 | 商户在小程序继续配置 | | `PENDING` | 等待审核或发布 | 在小程序查看进度 | | `ACTION_REQUIRED` | 需要商户处理 | 在小程序处理认证、签约或商品资料 | | `ENABLED` | 允许新增购买 | 展示购买入口 | | `DISABLED` | 停止新增购买 | 隐藏新购买入口;已有权益按权益或额度接口判断 | | `TERMINATED` | 商品已归档 | 不新增购买,在小程序查看状态 | #### 响应示例 以下示例仅使用公开预览定义的字段,并按单一业务场景整理。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpaydirect_charge_query_response": { "code": "10000", "msg": "Success", "capability_status": "ENABLED", "product_name": "智能写作助手", "product_icon_url": "https://app.example.com/assets/writing.png", "billing_mode": "QUANTITY", "quota_unit": "COUNT", "charging_options": [ { "sku_id": "S0806000200863003", "display_name": "20次包", "price": "1.00", "quota_amount": 20 } ], "management_url": "alipays://platformapi/startapp?appId=2021006179678000&page=pages%2Fnow-pay%2Fproduct-detail%2Findex%3Fticket%3DSAMPLE_TICKET" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpaydirect_charge_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充应用处理建议。错误码列表可能扩展,商户应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | --- ### 用户权益访问决策接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 直连模式接入 > API列表 > 用户权益访问决策接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/purchase_consult.md 直连模式用户权益访问决策接口 #### 用户商品权益查询接口 ##### 接口说明 接口名称:`alipay.aipay.nowpaydirect.purchase.consult` 查询指定应用用户是否拥有可使用的买断或时长包权益。需要购买且商品可购买时,同时返回支付宝托管购买页入口。 ##### 适用场景 - 买断或时长包用户进入付费功能前校验访问权限。 - 用户从支付页返回后重新确认权益。 - 时长包需要展示当前权益有效期。 ##### 注意事项 - 仅适用于 `ONE_TIME` 和 `ONE_TIME_DURATION`。`QUANTITY` 商品应使用 `quota.query`,并在消费时调用 `quota.verify`。 - 只有 decision=`ALLOW` 才放行。`PURCHASE_REQUIRED` 引导用户使用返回的购买入口;`DENY` 不放行、不展示新的购买入口。 - `callback_url` 只表示页面返回。用户返回后必须再次查询本接口;不要根据跳转、前端参数或本地缓存认定支付和权益成功。 - 时长包有效区间为 [`valid_from`, `valid_until`),到达 `valid_until` 后不再有效;永久买断不返回这两个时间字段。已有有效买断或时长权益时不引导再次购买。 - 商品停止新增购买后,已有有效权益仍可能返回 `ALLOW`。放行以 decision 为准,不能仅按 `capability_status` 决定。 - 本接口不接收 `out_request_no`,多次查询不承诺复用同一购买链接。 - `callback_url` 建议统一使用完整 `HTTPS` 地址 ##### 公共请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpaydirect.purchase.consult` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-27 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | ##### 业务请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 直连商品的外部商品 `ID`,从管理小程序商品详情页复制 | 使用当前商户创建的商品;不要自行生成或使用内部商品号 | `np_d_f83a7c91` | | `external_buyer_id` | String | 必选 | 128 | 应用内稳定的权益受益人标识 | 与应用登录用户绑定;不等同于付款账号 | `user_001` | | `callback_url` | String | 可选 | 128 | 购买完成返回地址 | 页面返回地址,不是异步通知地址;返回后重新查询状态 | `https://app.example.com/nowpay/purchase-return` | ##### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在应用服务端。cURL 中的签名需在发送前按全部实际参数生成。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpaydirectPurchaseConsultRequest; import com.alipay.api.response.AlipayAipayNowpaydirectPurchaseConsultResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpaydirectPurchaseConsultRequest request = new AlipayAipayNowpaydirectPurchaseConsultRequest(); request.setBizContent("{\"out_product_id\":\"np_d_f83a7c91\",\"external_buyer_id\":\"user_001\",\"callback_url\":\"https://app.example.com/nowpay/purchase-return\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpaydirectPurchaseConsultResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001", "callback_url": "https://app.example.com/nowpay/purchase-return" }' # app_id、timestamp、sign 由商户准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpaydirect.purchase.consult' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: ##### 公共响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpaydirect_purchase_consult_response`。先完成验签并判断 `code`,再读取业务结果。 ##### 业务响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `decision` | String | 必选 | 32 | 当前访问决策 | `ALLOW`:允许访问;`PURCHASE_REQUIRED`:需要购买;`DENY`:不允许访问且不引导购买 | `ALLOW` | | `reason_code` | String | 可选 | 128 | 业务结果原因码 | 结合 decision 使用;不要按原因文案编写业务分支 | - | | `valid_from` | String | 特殊可选 | 128 | 表示本次有效权益的生效时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | 仅 `ONE_TIME_DURATION` 且 decision=`ALLOW` 时返回;有效区间 [`valid_from`, `valid_until`) | `2026-09-27 10:00:00` | | `valid_until` | String | 特殊可选 | 128 | 表示本次有效权益的结束时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | 仅 `ONE_TIME_DURATION` 且 decision=`ALLOW` 时返回;有效区间 [`valid_from`, `valid_until`) | `2026-10-27 10:00:00` | | `product_name` | String | 可选 | 128 | 商品名称 | - | `智能写作助手` | | `product_icon_url` | String | 可选 | 1024 | 商品图标 | - | `https://app.example.com/assets/writing.png` | | `capability_status` | String | 必选 | 32 | 商品收费能力状态 | `NOT_CONFIGURED` / `CONFIGURING` / `PENDING` / `ENABLED` / `DISABLED` / `TERMINATED` | `ENABLED` | | `purchase_url` | String | 特殊可选 | 512 | 购买链接 | `PURCHASE_REQUIRED` 返回 | `alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID` | | `purchase_qr_code` | String | 特殊可选 | 512 | 购买二维码 | `PURCHASE_REQUIRED` 返回 | `https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE` | | `charging_options` | Object[] | 必选 | - | 当前商品的收费档位列表 | 可能为空数组;子字段必选性适用于实际返回的档位元素 | - | | `charging_options[].sku_id` | String | 必选 | 32 | 档位标识 | 按不透明标识保存和回传,不解析内容 | `S0806000200863004` | | `charging_options[].display_name` | String | 必选 | 128 | 档位名称 | - | `月度使用包` | | `charging_options[].price` | String | 必选 | 32 | 展示价格,十进制,单位元 | - | `9.90` | | `charging_options[].duration_period` | String | 特殊可选 | 32 | 时长包周期类型 | `billing_mode`=`ONE_TIME_DURATION` 时返回;`WEEK` / `MONTH` / `QUARTER` / `YEAR` | `MONTH` | | `charging_options[].quota_amount` | Number | 特殊可选 | 32 | 额度数量 | 通用档位结构保留字段;仅额度包适用,本接口不返回 | - | ##### 结果处理 | decision | 应用处理 | | --- | --- | | `ALLOW` | 放行;时长包可展示 valid_from、valid_until | | `PURCHASE_REQUIRED` | 使用 purchase_url 或 purchase_qr_code 引导购买;返回后重新查询 | | `DENY` | 不放行、不新建购买入口;根据 reason_code 展示说明或稍后刷新 | `reason_code` 是业务结果原因,不能代替 `decision`。常见拒绝原因包括权益暂不可用、商品已停用或需要创作者处理。 ##### 响应示例 以下示例仅使用公开预览定义的字段,并按单一业务场景整理。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpaydirect_purchase_consult_response": { "code": "10000", "msg": "Success", "decision": "ALLOW", "valid_from": "2026-09-27 10:00:00", "valid_until": "2026-10-27 10:00:00", "product_name": "智能写作助手", "capability_status": "ENABLED", "charging_options": [ { "sku_id": "S0806000200863004", "display_name": "月度使用包", "price": "9.90", "duration_period": "MONTH" } ] }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpaydirect_purchase_consult_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ###### 需要购买示例 ```json { "alipay_aipay_nowpaydirect_purchase_consult_response": { "code": "10000", "msg": "Success", "decision": "PURCHASE_REQUIRED", "capability_status": "ENABLED", "charging_options": [ { "sku_id": "S0806000200863004", "display_name": "月度使用包", "price": "9.90", "duration_period": "MONTH" } ], "purchase_url": "alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID", "purchase_qr_code": "https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ##### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 ##### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充应用处理建议。错误码列表可能扩展,商户应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 当前商品收费模式不适用于访问决策 | 仅买断和时长包使用本接口;额度包改用 `quota.query` | | `NOW_PAY_BINDING_INVALID` | 商品未绑定或未查到已上架商品 | 请核对商品是否已开通上架 | --- ### 用户额度查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 直连模式接入 > API列表 > 用户额度查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/quota_query.md 直连模式用户额度查询接口 #### 接口说明 接口名称:`alipay.aipay.nowpaydirect.quota.query` 查询业务用户在指定额度包商品下的有效发放总额、已用额度和剩余额度。接口返回客观余额,应用根据自己的服务规则决定一次服务需要消耗多少次数或积分。 #### 适用场景 - 展示剩余次数或积分。 - 用户购买返回后刷新余额。 - 执行服务前进行余额预检查。 #### 注意事项 - 仅适用于 `QUANTITY`;`quota_unit` 为 `COUNT` 或 `POINT`。 - 未购买时 total、used、remaining 都为 0;已用完时 remaining=0。 - 查询只提供当前余额,不预占额度。并发消费场景必须以 `quota.verify` 的原子扣减结果为准。 - 购买后额度到账可能有短暂延迟。可以有限次刷新;尚未到账时提示稍后查询,不能仅凭余额未变化判定支付失败。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpaydirect.quota.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-27 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 直连商品的外部商品 `ID`,从管理小程序商品详情页复制 | 使用当前商户创建的商品;不要自行生成或使用内部商品号 | `np_d_f83a7c91` | | `external_buyer_id` | String | 必选 | 128 | 应用内稳定的权益受益人标识 | 与应用登录用户绑定;不等同于付款账号 | `user_001` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在应用服务端。cURL 中的签名需在发送前按全部实际参数生成。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpaydirectQuotaQueryRequest; import com.alipay.api.response.AlipayAipayNowpaydirectQuotaQueryResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpaydirectQuotaQueryRequest request = new AlipayAipayNowpaydirectQuotaQueryRequest(); request.setBizContent("{\"out_product_id\":\"np_d_f83a7c91\",\"external_buyer_id\":\"user_001\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpaydirectQuotaQueryResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001" }' # app_id、timestamp、sign 由商户准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpaydirect.quota.query' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpaydirect_quota_query_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `quota_unit` | String | 必选 | 32 | 次数或积分`COUNT`/`POINT` | `COUNT`:次数;`POINT`:积分 | `COUNT` | | `total` | Number | 必选 | 99999999 | 已发放总额度 | - | `20` | | `used` | Number | 必选 | 99999999 | 已使用总额度 | - | `0` | | `remaining` | Number | 必选 | 99999999 | 剩余额度 | - | `20` | | `as_of_time` | String | 必选 | 32 | 余额计算时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | - | `2026-09-27 10:00:00` | #### 结果处理 应用根据 `quota_unit` 展示次数或积分,按 `remaining` 做服务前置判断。余额充足仍需核销;不足时可调用 [购买链接获取接口](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/purchase_create.md)。返回 0 余额本身是正常查询结果,不作为接口失败。 #### 响应示例 以下示例仅使用公开预览定义的字段,并按单一业务场景整理。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpaydirect_quota_query_response": { "code": "10000", "msg": "Success", "quota_unit": "COUNT", "total": 20, "used": 0, "remaining": 20, "as_of_time": "2026-09-27 10:00:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpaydirect_quota_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充应用处理建议。错误码列表可能扩展,商户应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 商品不是额度包模式 | 请核对入参参数相关的商品配置信息 | --- ### 直接购买链接获取接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 直连模式接入 > API列表 > 直接购买链接获取接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/purchase_create.md 直连模式直接购买链接获取接口 #### 接口说明 接口名称:`alipay.aipay.nowpaydirect.purchase.create` 获取普通购买入口或锁定指定档位的购买入口。传入 `sku_id` 时锁定该档位;不传时由用户在托管购买页选择可售档位。 #### 适用场景 - 额度不足时引导用户购买次数包或积分包。 - 用户主动加购额度,即使当前仍有余额。 - 应用已展示档位并希望直接打开指定档位购买页。 #### 注意事项 - `out_request_no` 标识一次获取购买入口的请求,不是支付宝交易号。商户应为每次独立请求生成唯一值并持久化;超时重试使用原值与原参数。 - `sku_id` 必须取自当前商品 `charge.query` 的可售档位。不传 `sku_id` 时打开可选档位的普通购买页。 - `callback_url` 如传入,使用 `HTTPS` 地址。 - 同一请求号重试须保持商品、受益人、`sku_id` 和 `callback_url` 一致。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpaydirect.purchase.create` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-27 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | String | 必选 | 128 | 商户生成的幂等请求号 | 重试保持原值与原业务参数;不同请求使用不同值 | `purchase_20260927_000001` | | `out_product_id` | String | 必选 | 128 | 直连商品的外部商品 `ID`,从管理小程序商品详情页复制 | 使用当前商户创建的商品;不要自行生成或使用内部商品号 | `np_d_f83a7c91` | | `external_buyer_id` | String | 必选 | 128 | 应用内稳定的权益受益人标识 | 与应用登录用户绑定;不等同于付款账号 | `user_001` | | `sku_id` | String | 可选 | 64 | 可选,希望直接指定购买档位时可传入 | 取自当前商品的 `charging_options`;不传则在购买页选择档位 | `S0806000200863003` | | `callback_url` | String | 可选 | 512 | 购买完成返回地址 | 页面返回地址,不是异步通知地址;返回后重新查询状态;如传入必须为 `HTTPS` | `https://app.example.com/nowpay/purchase-return` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在应用服务端。cURL 中的签名需在发送前按全部实际参数生成。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpaydirectPurchaseCreateRequest; import com.alipay.api.response.AlipayAipayNowpaydirectPurchaseCreateResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpaydirectPurchaseCreateRequest request = new AlipayAipayNowpaydirectPurchaseCreateRequest(); request.setBizContent("{\"out_request_no\":\"purchase_20260927_000001\",\"out_product_id\":\"np_d_f83a7c91\",\"external_buyer_id\":\"user_001\",\"sku_id\":\"S0806000200863003\",\"callback_url\":\"https://app.example.com/nowpay/purchase-return\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpaydirectPurchaseCreateResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_request_no": "purchase_20260927_000001", "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001", "sku_id": "S0806000200863003", "callback_url": "https://app.example.com/nowpay/purchase-return" }' # app_id、timestamp、sign 由商户准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpaydirect.purchase.create' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpaydirect_purchase_create_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `purchase_url` | String | 必选 | 512 | 购买链接地址,用于手机端直接跳转购买 | - | `alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID` | | `purchase_qr_code` | String | 必选 | 512 | 购买二维码,用于pc端直接展示二维码后扫码购买 | - | `https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE` | | `expire_time` | String | 必选 | 32 | 链接失效时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | - | `2026-09-27 10:30:00` | #### 结果处理 成功后打开 `purchase_url` 或展示 `purchase_qr_code`。链接、二维码和令牌都使用接口实际返回值,不解析、不拼接。到期后先刷新用户权益或额度,再按用户购买意图获取新入口。 #### 响应示例 以下示例仅使用公开预览定义的字段,并按单一业务场景整理。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpaydirect_purchase_create_response": { "code": "10000", "msg": "Success", "purchase_url": "alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID", "purchase_qr_code": "https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE", "expire_time": "2026-09-27 10:30:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpaydirect_purchase_create_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ##### 普通购买入口 不传 `sku_id` 时,由用户在托管页选择档位。 ```json { "alipay_aipay_nowpaydirect_purchase_create_response": { "code": "10000", "msg": "Success", "purchase_url": "alipays://platformapi/startapp?appId=2021006180624128&page=pages%2Forder%2Findex%3FpurchaseLinkId%3DSAMPLE_LINK_ID", "purchase_qr_code": "https://mobilecodec.alipay.com/show.htm?code=SAMPLE_QR_CODE", "expire_time": "2026-09-27 10:30:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充应用处理建议。错误码列表可能扩展,商户应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 计价模式不支持 | 请确认商品收费模式 | | `NOW_PAY_BINDING_INVALID` | 商品绑定关系不存在/不匹配 | 商品绑定关系不存在/不匹配 | | `NOW_PAY_CHARGING_OPTION_UNAVAILABLE` | 指定档位已下架或不存在 | 确认 `sku_id`与 `charge.query` 返回的可售档位一致 | | `NOW_PAY_ORDER_CONFLICT` | 同一幂等请求号对应的业务参数不一致 | 核对原请求参数;原请求结果未知时不要换号重试 | | `NOW_PAY_PRODUCT_NOT_PURCHASABLE` | 该商品不可购买 | 请检查商品上架状态 | | `NOW_PAY_PURCHASE_LINK_CREATING` | 当前购买链接正在创建中,不允许重复提交请求 | 稍后用原 `out_request_no` 和原参数重试 | | `NOW_PAY_PURCHASE_LINK_INVALID` | 购买链接已过期或不存在 | 确认旧购买入口失效后,按新的购买意图生成新请求号;不要将核销超时按此处理 | --- ### 商品额度核销接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 直连模式接入 > API列表 > 商品额度核销接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/quota-verify.md 直连模式商品额度核销接口 #### 接口说明 接口名称:`alipay.aipay.nowpaydirect.quota.verify` 按应用提供的消费请求号直接核销指定数量的次数或积分。核销成功即正式扣减;应用需结合服务交付时点调用,并保存消费请求与核销结果的对应关系。 #### 适用场景 - 一次服务需要正式消耗次数或积分。 - 同一消费请求因网络异常需要重试。 #### 注意事项 - amount 必须显式传入正整数;一次扣 1 次时传 1,不依赖服务端默认补值。积分按应用服务规则计算后传入。 - 先检查 code,再读取 `consume_status`。只有 `SUCCEEDED` 表示扣减成功;`PROCESSING`、网络超时或系统错误都不能直接当作失败换号重扣。 - 余额不足可能通过业务错误码 `NOW_PAY_QUOTA_INSUFFICIENT` 返回;也需兼容 `consume_status`=`FAILED` 的结果表达。额度不足整笔失败,不按部分扣减处理。 - 核销成功后不提供核销撤销、或服务失败自动返还。商户应事先确定服务交付与核销的时点,并对服务执行本身做好幂等。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpaydirect.quota.verify` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-27 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | String | 必选 | 128 | 商户生成的幂等请求号 | 重试保持原值与原业务参数;不同请求使用不同值 | `consume_20260927_000001` | | `out_product_id` | String | 必选 | 128 | 直连商品的外部商品 `ID`,从管理小程序商品详情页复制 | 使用当前商户创建的商品;不要自行生成或使用内部商品号 | `np_d_f83a7c91` | | `external_buyer_id` | String | 必选 | 128 | 应用内稳定的权益受益人标识 | 与应用登录用户绑定;不等同于付款账号 | `user_001` | | `amount` | Number | 必选 | 99999999 | 本次核销数量,单位次数或积分 | 显式传入正整数;`COUNT` 单次扣减传 1;当前预览“长度/取值”为 99999999 | `1` | | `consume_reason` | String | 必选 | 256 | 本次业务消费的简洁原因文本 | 普通文本 | `生成一篇文章` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在应用服务端。cURL 中的签名需在发送前按全部实际参数生成。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpaydirectQuotaVerifyRequest; import com.alipay.api.response.AlipayAipayNowpaydirectQuotaVerifyResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpaydirectQuotaVerifyRequest request = new AlipayAipayNowpaydirectQuotaVerifyRequest(); request.setBizContent("{\"out_request_no\":\"consume_20260927_000001\",\"out_product_id\":\"np_d_f83a7c91\",\"external_buyer_id\":\"user_001\",\"amount\":1,\"consume_reason\":\"生成一篇文章\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpaydirectQuotaVerifyResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_request_no": "consume_20260927_000001", "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001", "amount": 1, "consume_reason": "生成一篇文章" }' # app_id、timestamp、sign 由商户准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpaydirect.quota.verify' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpaydirect_quota_verify_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `consume_status` | String | 必选 | 32 | 核销状态 | 成功:`SUCCEEDED`;失败:`FAILED`;进行中:`PROCESSING` | `SUCCEEDED` | | `consume_reason` | String | 必选 | 512 | 消费原因 | 商户应持久化原始原因;查询结果可能不返回 | `生成一篇文章` | | `quota_unit` | String | 必选 | 32 | 额度类型 | `COUNT`:次数;`POINT`:积分 | `COUNT` | | `consumed` | Number | 特殊可选 | 99999999 | 本次实际扣减量,单位次数或积分 | `SUCCEEDED` 时使用;`PROCESSING` 时可能缺失,不补零、不推断扣减结果 | `1` | | `remaining` | Number | 特殊可选 | 99999999 | 本次核销成功时,原子扣减后的可消费余额 | 仅 `SUCCEEDED` 时使用;不是当前实时余额 | `19` | | `update_time` | String | 特殊可选 | 32 | 更新时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | `SUCCEEDED`时返回 | `2026-09-27 10:05:00` | #### 结果处理 | 情况 | 应用处理 | | --- | --- | | `code=10000` 且 `consume_status=SUCCEEDED` | 确认本次扣减,保存原请求号、consumed、remaining;避免重复交付 | | `code=10000` 且 `consume_status=FAILED` | 不标记核销成功,结合原消费记录排查;本接口未定义失败原因字段 | | `code=10000` 且 `consume_status=PROCESSING` | 保留原请求号,调用 quota.refresh 查询 | | 余额不足业务错误 | 提示购买或补充额度,不标记消费成功 | | 超时、系统错误、未知状态 | 标记本地待确认,使用原请求查询或重试,不换号 | `code=10000` 不能单独作为扣减成功依据;同样不能只处理 `consume_status` 而忽略网关失败。 #### 响应示例 以下示例仅使用公开预览定义的字段,并按单一业务场景整理。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpaydirect_quota_verify_response": { "code": "10000", "msg": "Success", "consume_status": "SUCCEEDED", "quota_unit": "COUNT", "consumed": 1, "remaining": 19, "update_time": "2026-09-27 10:05:00", "consume_reason": "生成一篇文章" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpaydirect_quota_verify_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ##### 余额不足错误示例 ```json { "alipay_aipay_nowpaydirect_quota_verify_response": { "code": "40004", "msg": "Business Failed", "sub_code": "NOW_PAY_QUOTA_INSUFFICIENT", "sub_msg": "额度不足" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ##### 处理中示例 扣减量和余额可能缺失;保留原请求号继续查询,不把缺失值补为零后判定失败。 ```json { "alipay_aipay_nowpaydirect_quota_verify_response": { "code": "10000", "msg": "Success", "consume_status": "PROCESSING", "quota_unit": "COUNT", "consume_reason": "生成一篇文章" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充应用处理建议。错误码列表可能扩展,商户应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 商品不是额度包模式 | 请核对入参参数相关的商品配置信息 | | `NOW_PAY_BINDING_INVALID` | 商品绑定无效 | 请检查商品id是否属于本次请求的商户账号 | | `NOW_PAY_QUOTA_CONSUME_CONFLICT` | 额度消费请求幂等冲突 | 检查核销请求`out_request_no`是否已被使用 | | `NOW_PAY_QUOTA_INSUFFICIENT` | 额度不足 | 提示购买或补充额度;本次不记为核销成功 | --- ### 商品额度核销结果查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 直连模式接入 > API列表 > 商品额度核销结果查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/quota-verify-query.md 直连模式商品额度核销结果查询接口 #### 接口说明 接口名称:`alipay.aipay.nowpaydirect.quota.refresh` 使用原消费请求号查询一笔额度核销的处理结果,用于核销超时、处理中或结果丢失后的恢复。此接口不刷新或增加余额,也不会发起新的额度扣减。 #### 适用场景 - `quota.verify` 超时,无法确定是否已扣减。 - 核销返回 `PROCESSING`,需要继续查询最终状态。 - 恢复应用本地未确认的消费记录。 #### 注意事项 - `out_request_no`、商品和受益人应与原 `quota.verify` 请求完全对应;无需重复传入 amount 或 `consume_reason`。 - 查询成功只表示获得了记录,仍需检查 `consume_status`。`SUCCEEDED` 完成本地消费确认,`FAILED` 按原因处理,`PROCESSING` 继续查询。 - 未找到记录时,不代表原请求一定未执行。核对原请求号并继续查询,或用完全相同的原请求重试 `quota.verify`,不能换新请求号重复扣减。 - remaining 表示原核销成功时的扣减后余额,后续购买或消费可能已改变余额;查询最新余额使用 `quota.query`。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpaydirect.quota.refresh` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-27 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | String | 必选 | 128 | 商户生成的幂等请求号 | 重试保持原值与原业务参数;不同请求使用不同值 | `consume_20260927_000001` | | `out_product_id` | String | 必选 | 128 | 直连商品的外部商品 `ID`,从管理小程序商品详情页复制 | 使用当前商户创建的商品;不要自行生成或使用内部商品号 | `np_d_f83a7c91` | | `external_buyer_id` | String | 必选 | 128 | 应用内稳定的权益受益人标识 | 与应用登录用户绑定;不等同于付款账号 | `user_001` | #### 常见请求示例 示例商品、用户、域名及请求号均为演示值。Java 使用包含该接口请求类的支付宝服务端 SDK;示例按公钥模式初始化,私钥仅保存在应用服务端。cURL 中的签名需在发送前按全部实际参数生成。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpaydirectQuotaRefreshRequest; import com.alipay.api.response.AlipayAipayNowpaydirectQuotaRefreshResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpaydirectQuotaRefreshRequest request = new AlipayAipayNowpaydirectQuotaRefreshRequest(); request.setBizContent("{\"out_request_no\":\"consume_20260927_000001\",\"out_product_id\":\"np_d_f83a7c91\",\"external_buyer_id\":\"user_001\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpaydirectQuotaRefreshResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_request_no": "consume_20260927_000001", "out_product_id": "np_d_f83a7c91", "external_buyer_id": "user_001" }' # app_id、timestamp、sign 由商户准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpaydirect.quota.refresh' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpaydirect_quota_refresh_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 长度/取值 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `consume_status` | String | 必选 | 32 | 核销状态 | 成功:`SUCCEEDED`;失败:`FAILED`;进行中:`PROCESSING` | `SUCCEEDED` | | `consume_reason` | String | 可选 | 512 | 消费原因 | 商户应持久化原始原因;查询结果可能不返回 | - | | `quota_unit` | String | 必选 | 32 | 额度类型 | `COUNT`:次数;`POINT`:积分 | `COUNT` | | `consumed` | Number | 特殊可选 | 99999999 | 本次实际扣减量,单位次数或积分 | `SUCCEEDED` 时使用;`PROCESSING` 时可能缺失,不补零、不推断扣减结果 | `1` | | `remaining` | Number | 特殊可选 | 99999999 | 本次核销成功时,原子扣减后的可消费余额 | 仅 `SUCCEEDED` 时使用;不是当前实时余额 | `19` | | `update_time` | String | 特殊可选 | 32 | 更新时间;格式 `yyyy-MM-dd HH:mm:ss`,时区 `Asia/Shanghai` | `SUCCEEDED` 时返回 | `2026-09-27 10:05:00` | #### 结果处理 处理规则与 [商品额度核销接口](https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/quota-verify.md) 一致。仅在 `code=10000` 且 `consume_status=SUCCEEDED` 时确认原核销成功。未找到记录、超时、处理中及未知状态都进入应用待确认流程,保留原请求号。 #### 响应示例 以下示例仅使用公开预览定义的字段,并按单一业务场景整理。签名、链接令牌和二维码均为占位值,不可直接使用。 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_nowpaydirect_quota_refresh_response": { "code": "10000", "msg": "Success", "consume_status": "SUCCEEDED", "quota_unit": "COUNT", "consumed": 1, "remaining": 19, "update_time": "2026-09-27 10:05:00" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpaydirect_quota_refresh_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ##### 余额不足错误示例 ```json { "alipay_aipay_nowpaydirect_quota_refresh_response": { "code": "40004", "msg": "Business Failed", "sub_code": "NOW_PAY_QUOTA_INSUFFICIENT", "sub_msg": "额度不足" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` ##### 处理中示例 扣减量和余额可能缺失;保留原请求号继续查询,不把缺失值补为零后判定失败。 ```json { "alipay_aipay_nowpaydirect_quota_refresh_response": { "code": "10000", "msg": "Success", "consume_status": "PROCESSING", "quota_unit": "COUNT" }, "sign": "RESPONSE_SIGNATURE_PLACEHOLDER" } ``` #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 以下保留当前开放平台预览已列出的错误码,并补充应用处理建议。错误码列表可能扩展,商户应保留未知错误的待确认处理。 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 稍后使用原参数重试;消费结果未知时先查询原请求 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `BILLING_MODE_NOT_SUPPORTED` | 商品不是额度包模式 | 请核对入参参数相关的商品配置信息 | | `CONSUME_REQUEST_NOT_FOUND` | 未找到匹配的幂等请求记录,请确认幂等号和请求状态 | 核对原请求号与商品;继续查询或原参数重试核销,不因未找到记录直接换号 | --- ### 权益购买结果查询接口 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 直连模式接入 > API列表 > 权益购买结果查询接口 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/direct/api-list/purchase_query.md #### 接口说明 接口名称:`alipay.aipay.nowpaydirect.purchase.query` 查询直连模式下的权益购买结果。通过外部商品标识和平台买家标识定位查询范围,并可使用创建购买链接时的请求幂等号、购买链接标识及指定档位查询对应购买结果。 #### 适用场景 - 买家完成购买流程后,查询商品购买结果。 - 额度包购买后,使用原请求幂等号或购买链接标识查询对应订单结果。 - 创建购买链接时指定了档位,携带该档位标识查询购买结果。 #### 注意事项 - `out_product_id`、`external_buyer_id` 为必选字段,需与实际商品及买家对应。 - 额度包场景尽量传入创建购买链接时的 `out_request_no`;原文提示,不传时超过半小时的订单无法查询结果。 - `purchase_link_id` 使用 `purchase.create` 或 `purchase.consult` 返回的购买链接标识,按原值保存和传入。 - `purchase.create` 创建购买链接时若指定了档位,查询时需传入对应的 `sku_id`。 - 原文枚举说明存在错列,将 `SUCCESS`、`WAIT_PAY` 分别与商品类型并列展示。本文保留状态值;状态与商品类型的对应关系需在接入时核对。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用ID | `YOUR_APP_ID` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.nowpaydirect.purchase.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 请求签名算法,推荐 RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2026-09-07 10:00:00` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 已获授权的第三方代调用场景使用的应用授权令牌,详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 业务请求参数的 JSON 字符串,字段使用 snake_case;详见下表 | - | #### 业务请求参数 业务字段统一放入 `biz_content`。下表数组子字段使用 `[]` 表示元素路径。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_product_id` | String | 必选 | 128 | 外部商品标识 | - | `app_1029001` | | `external_buyer_id` | String | 必选 | 128 | 平台买家标识 | - | `buyer_10001` | | `out_request_no` | String | 可选 | 64 | `purchase.create` 创建购买链接时传入的请求幂等号 | 额度包场景尽量传入,否则超过半小时的订单无法查询结果 | 1c4c07f08f4f41a8
9615c1f2e212d3e0 | | `purchase_link_id` | String | 可选 | 128 | `purchase.create` / `purchase.consult` 响应中的购买链接标识 | - | Tk9XUEFZOlBVUkNIQVNFOjgy
NzQ2Y2M2MWNkMDRmNGJhYTVi
NDZmYTIyMzVhNjE4XyQ3MA | | `sku_id` | String | 可选 | 32 | 指定档位标识 | 创建购买链接时若指定档位,查询时需传入 | `S0806000200864400` | #### 常见请求示例 以下商品、买家、请求号及购买链接标识均为演示值。Java 使用支付宝服务端 SDK;私钥保存在平台服务端。cURL 签名需基于本次实际请求生成,授权令牌按实际调用场景配置。 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="cURL" title="cURL"} ```bash biz_content='{ "out_product_id": "app_1029001", "external_buyer_id": "buyer_10001", "out_request_no": "1c4c07f08f4f41a89615c1f2e212d3e0", "purchase_link_id": "Tk9XUEFZOlBVUkNIQVNFOjgyNzQ2Y2M2MWNkMDRmNGJhYTViNDZmYTIyMzVhNjE4XyQ3MA", "sku_id": "S0806000200864400" }' # app_id、timestamp、sign 由平台准备;sign 必须基于本次完整参数生成。 curl --request POST 'https://openapi.alipay.com/gateway.do' \ --data-urlencode "app_id=${app_id}" \ --data-urlencode 'method=alipay.aipay.nowpaydirect.purchase.query' \ --data-urlencode 'format=json' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode "timestamp=${timestamp}" \ --data-urlencode 'version=1.0' \ --data-urlencode "biz_content=${biz_content}" \ --data-urlencode "sign=${sign}" ``` ::: :::aipay-tab{key="Java" title="Java"} ```java import com.alipay.api.AlipayConfig; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.request.AlipayAipayNowpaydirectPurchaseQueryRequest; import com.alipay.api.response.AlipayAipayNowpaydirectPurchaseQueryResponse; public class NowpayExample { public static void main(String[] args) throws Exception { AlipayConfig config = new AlipayConfig(); config.setServerUrl("https://openapi.alipay.com/gateway.do"); config.setAppId(System.getenv("ALIPAY_APP_ID")); config.setPrivateKey(System.getenv("ALIPAY_PRIVATE_KEY")); config.setAlipayPublicKey(System.getenv("ALIPAY_PUBLIC_KEY")); config.setFormat("json"); config.setCharset("UTF-8"); config.setSignType("RSA2"); AlipayClient client = new DefaultAlipayClient(config); AlipayAipayNowpaydirectPurchaseQueryRequest request = new AlipayAipayNowpaydirectPurchaseQueryRequest(); request.setBizContent("{\"out_product_id\":\"app_1029001\",\"external_buyer_id\":\"buyer_10001\",\"out_request_no\":\"1c4c07f08f4f41a89615c1f2e212d3e0\",\"purchase_link_id\":\"Tk9XUEFZOlBVUkNIQVNFOjgyNzQ2Y2M2MWNkMDRmNGJhYTViNDZmYTIyMzVhNjE4XyQ3MA\",\"sku_id\":\"S0806000200864400\"}"); // 仅在已获授权的第三方代调用场景设置 app_auth_token。 String appAuthToken = System.getenv("ALIPAY_APP_AUTH_TOKEN"); if (appAuthToken != null && !appAuthToken.isEmpty()) { request.putOtherTextParam("app_auth_token", appAuthToken); } AlipayAipayNowpaydirectPurchaseQueryResponse response = client.execute(request); if (!response.isSuccess()) { // 按 code/sub_code 处理;结果未知时保留原业务请求号。 System.out.println(response.getCode() + ":" + response.getSubCode()); return; } // 网关成功后,按本页“结果处理”读取业务字段。 System.out.println(response.getBody()); } } ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码;10000 表示接口调用成功 | `10000` | | `msg` | String | 必选 | - | 网关返回码说明 | `Success` | | `sub_code` | String | 可选 | - | 业务错误码;仅用于接口失败处理 | - | | `sub_msg` | String | 可选 | - | 业务错误说明;不用于编写固定业务分支 | - | | `sign` | String | 必选 | - | 响应签名,位于响应根对象;由 SDK 按配置验签 | - | 响应业务对象名为 `alipay_aipay_nowpaydirect_purchase_query_response`。先完成验签并判断 `code`,再读取业务结果。 #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `purchase_status` | String | 必选 | 32 | 购买结果 | `SUCCESS` / `WAIT_PAY` / `UNKNOWN`;`UNKNOWN` 表示参数不全,无法确认 | `SUCCESS` | | `trade_no` | String | 可选 | 64 | 支付宝订单号 | 按实际返回读取 | `2026100122001431111104111324` | #### 结果处理 - `purchase_status` 为 `SUCCESS`:按购买成功处理,并记录返回的支付宝订单号。 - `purchase_status` 为 `WAIT_PAY`:按待支付处理,可在买家完成支付后再次查询。 - `purchase_status` 为 `UNKNOWN`:参数不全,无法确认购买结果;补充原请求幂等号、购买链接标识或所需档位后查询,不按购买成功处理。 - 返回 `SYSTEM_ERROR`:可使用同样的业务参数重试;重新发送时按实际请求生成签名。 #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "purchase_status": "SUCCESS", "trade_no": "2026100122001431111104111324" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_aipay_nowpaydirect_purchase_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 参见[支付宝公共错误码](https://opendoc.alipay.com/common/02km9f)。网关或系统异常时,按原请求查询或重试;写操作不能在结果未确认时更换幂等号。 #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常,可能发生了网络或者系统异常,导致服务调用失败;商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 根据接口返回的参数非法的具体错误信息,修改参数后重试 | --- ### 即刻收商品经营范围规范 目录路径:Vibe Pay · AI应用收款 > 智能收款套件-即刻收 > 即刻收商品经营范围规范 来源:https://aipay.alipay.com/docs/vibe-pay/nowpay/rules.md 为保障交易安全、用户权益与合规经营,即刻收对部分经营范围不予开通收款服务,对部分经营范围实行资质准入。本规范适用于通过即刻收提交收款开通申请的全部商品与服务页面。 **一、不支持的经营范围** 以下经营范围不予开通收款服务,提交申请将不予受理 | 类目 | 类目描述 | 备注说明 | | --- | --- | --- | | 政治类 | 非法政治音像制品、出版物;涉及分裂国家、邪教组织、违反伦理等反动思想的各类物品;非法反动卡类和节目台;国家机密文件资料;政治时政信息内容服务;颠覆政权、煽动分裂、抹黑领导人、歪曲党史国史等内容;其他反动物品及言论 | | | 黄赌毒类 | 毒品、吸毒工具与毒品检测试剂;黄色低俗音像制品、出版物、物品、卡类和节目台;色情服务与违法违规线上租友;泡妞秘籍,以及恋足、恋童、人体摄影(以是否露点为准)、丝袜、原味、捆绑等带不正当引导倾向的内容;含色情、恐怖、暴力内容的剧本杀及同类互动;赌博器具;私彩;一元购等随机性付费玩法;需投入法定货币的随机性玩法、押注竞猜等变相赌博;赌博与博彩服务,含游戏货币可直接兑换现金或可经账户流转且有银商收购贩卖的棋牌类网站 | 伴游服务无色情描述暂不做限制;导游平台、私人导游需提供导游资格证;德州扑克牌局定义为桌游产品,不视为赌博工具;已获广电许可的出版物不做限制;毒品检测试剂只提供给有资质的戒毒所机构,毒品检测工具不允许出售 | | 军警类 | 军火武器、枪械及枪支配件(含枪瞄器、枪套);冒用军队标志或军用描述的军用物品;警用服装与器材(如电警棍);带警用标志的物品(如警徽) | 仿真枪以 90% 大小相似的,按枪支配件处理;军被、军帽、军鞋等军用日常用品可合作 | | 治安类(危险品) | 管制器具(管制刀具、弩等);犯罪物品与犯罪工具(开锁工具、汽车解码器等);剧毒物品;爆炸品、易燃液体、易燃固体、自燃物品和遇湿易燃物品、毒害品和感染性物品、放射性物品、腐蚀品;甩棍、电棍、电击棍等 | 管制器具依《管制刀具管理条例》认定;非管制刃具除外;持证备案的开锁服务按资质要求办理 | | 医药器械类 | 麻醉药品和精神类药品、毒性药品;处方药;无批准文号药品;禁用药品、禁用农药兽药、假劣过期药品与未注册医疗器械;无资质销售药品与医疗器械;无证诊疗与非法美容手术;辅助生殖技术、代孕及中介引流;非医学需要的胎儿性别鉴定;隐私、个人与司法亲子鉴定及孕期检测、邮寄检材;涉及人类遗传资源出境的服务;非医学需要的儿童微量元素检测;口服类成人催情药品;无合法资质或含违禁成分的性保健品 | 灭鼠药、蟑螂药、兽药不做限制;处方药参照《互联网药品交易服务审批暂行规定》;持证医美机构、司法许可鉴定机构按资质要求办理 | | 网络服务 | 第三方转支付平台,即未取得《支付业务许可证》开展资金支付结算的二清无牌机构、POS 支付结算等业务;销售或推广未经认证的 POS、MPOS、刷卡器;炒信与刷单服务,含刷粉刷赞刷票刷量刷评删帖及工具、兼职下载任务;买卖支付账户、店铺、群发软件等危害平台生态的软件与服务;买卖互联网账号、游戏账号、成品号与卡密等账号权益,含代练、账号出租与游戏币私下交易;跨区或海外区号低价代充会员、额度与权益;无授权的游戏币、Q 币、平台积分充值与非官方商城充值;非即时到账的话费与点券慢充业务;恶意刷店铺流量、空包网;翻墙与 VPN 服务;企业内部系统对外开放;引导线下交易以规避线上监管;未经授权调用或滥用平台接口 | 经批准的企业合规跨境专线除外;官方渠道直充、官方授权道具商城、运营商官方过户与平台内官方交易除外 | | 涉外婚介 | 涉外婚姻介绍机构或变相从事涉外婚介业务 | 依《国务院办公厅关于加强涉外婚姻介绍管理的通知》第一条,严禁成立涉外婚姻介绍机构,任何个人不得以营利为目的从事或变相从事涉外婚姻介绍活动 | | 黑客相关 | 外挂、作弊器、破解工具、黑客工具、记牌器、自动抢红包、root 刷机引导;接码平台、群控、电话卡批量插入设备、批量账号与地址切换系统、防封号防封卡等电信网络诈骗工具;漏洞利用与攻击服务 | 出版社已出版的黑客类书籍不做处理 | | 恶意软件 | 短信轰炸机;办证刻章(假证假章),含伪造、变造、买卖公文、印章、身份证、社保卡、护照、文凭、驾照;病毒木马及其他恶意程序 | 备案刻章企业凭营业执照承接的除外 | | 侵害隐私类 | 身份证信息等侵犯个人隐私的信息;间谍器材;偷拍偷录设备与服务,售卖偷拍图片视频;个人信息买卖、人肉搜索、手机号与虚拟定位;欺诈、伪造材料、虚构劳动关系骗取社保待遇,含非法代缴补缴挂靠 | 持证人力资源机构合规代缴的除外 | | 金融类 | 传销与金融互助平台,虚假宣传致富、出售成功学、终身返利、排队返利、发展下线的金字塔型提成,以养老、光伏、云种植、云养殖等名义吸收资金;虚拟货币交易、挖矿、钱包服务及相关资讯;信用卡套现,伪造变造买卖信用卡等金融票证;假币;出借、出售银行账户、支付账户、电话卡与物联网卡;非法集资、非法众筹与未备案股权众筹;外汇兑换与按金交易、非法本外币兑换与炒汇;黄金期货;有价证券和凭证(如承兑汇票、股票);融资租赁平台与非实物众筹;配资与 P2P;面向在校学生与未成年人的互联网消费贷款;交友、现金、金融经营类盲盒,以及以盲盒形式销售食品化妆品药品器械、易燃易爆物品、活体动物;未经授权发行与二级交易的数字藏品;黄金、奢侈品、电子产品等高价值回收未报备或涉洗钱嫌疑;芝麻粒等信用分的交易、助力与买卖 | 彩票销售不予合作;持牌机构面向成年人的合规信贷、已备案私募基金面向合格投资者、普通商品盲盒、一级发行且有版权授权的数字藏品除外 | | 收藏类 | 考古文物;国有文物买卖;禁止流通文物;无文物经营许可从事文物交易 | 依《文物保护法》第五十一条、第五十二条,国有文物不得买卖;持证文物商店按资质要求办理 | | 通讯/数码类 | 手机魔卡、蹭网卡、卫星天线等;未经许可的 SIM 卡、电话卡、物联网卡与改号软件;违规买卖手机号、QQ 号等虚拟身份标识 | 持证运营商官方渠道与官方选号除外 | | 食品类 | 假冒产品;烟草制品;电子烟线上售卖 | 鼻烟、水烟等含烟草成分的,按烟草类别认定 | | 其他 | 原油与成品油;人体器官;代孕服务;走私物品与禁止或限制进出境货物、水货与未缴税免税货;偷渡、非法出入境证件与非法出境旅游服务;替考、代考、代写论文、学术造假与刷课代学;国家保护动物、国家保护植物及制品与活体动物买卖;烟花爆竹;封建迷信类,含算命、占卜、打卦、风水等付费服务;以宗教名义商业宣传募捐、经销宗教用品与非法出版物;发表辱华言论或有辱华行为的品牌商品;明星榜单、投票打榜、应援集资等饭圈违规;虚拟众筹(如股权众筹);特殊时期特殊规定(版权及国家同步规定等) | 民俗文化科普除外;人工繁育持证经营除外;宗教事务部门批准的出版物除外 | | 经营授权类 | 未经授权代运营商家账户;未经授权的装修设计与施工;无资质定制软件、小程序开发与系统集成;付费高考志愿填报咨询;以公益名义开展但缺乏资质或透明度的捐赠;未经授权的社交平台与交友服务;无平台许可或诱导充值、涉赌的小游戏;违反国家有关规定开展的学科类培训、超纲教学与违规竞赛辅导 | 平台官方服务商、持证装饰企业、持证或备案主体、教育主管部门认可机构、持牌慈善组织、持证版号游戏、持证非学科类培训机构按资质要求办理 | | 未成年人保护类 | 面向未成年人的金融借贷、租赁、社交与游戏服务;破解或绕过防沉迷与实名认证;向未成年人提供或诱导占卜 | | | 侵权与造假类 | 盗版与未授权资源分发;未签名软件安装包;商标与品牌仿冒;素材造假、聊天记录与转账截图造假;伪造他人肖像与声音(含深度合成);删除、篡改、伪造或隐匿依法应标注的内容标识 | | | 人工智能服务类(境外模型) | 境外人工智能模型及其订阅、额度、接口的代充、转售与分销 | 境内人工智能模型及其生成合成类服务,见第二部分「人工智能服务类(境内生成合成类)」 | **二、需提交资质后开通的经营范围** 以下经营范围在提交并核验相应资质后可开通收款服务 | 类目 | 需提交的资质或证明 | 备注说明 | | --- | --- | --- | | 支付与收单 | 支付业务许可证,或与持牌机构的合作协议及通道来源说明 | 含聚合支付、收银台、受理终端推广 | | 金融、保险、征信 | 监管部门许可或备案文件;保险中介许可证或保险公司授权 | 征信服务需持牌机构授权查询;未经授权的信用查询、信用评分与征信修复不予开通 | | 医疗、医美、药品 | 执业许可、互联网药品信息服务资格、医美备案等 | 含二级及以上医院、基层医疗、器械销售、康复理疗 | | 教育培训 | 办学许可证、非学科类培训许可或人社备案文件 | 学科类培训按国家有关规定执行 | | 食品餐饮 | 食品经营许可 | | | 物流与运输 | 快递业务经营许可证,道路、铁路、航运、航空运输许可,邮政业务批复 | | | 电信与互联网经营 | 增值电信业务经营许可证 | | | 预付卡 | 单用途预付卡备案文件,或资金存管通道合作协议 | 类预付卡按同一口径办理 | | 租赁 | 租赁经营资质或平台准入证明 | 面向未成年人的租赁不予开通 | | 成人情趣与计生用品 | 商品合规说明及相应许可(涉及医疗器械、消毒产品的需对应资质) | 不面向未成年人营销;含违禁成分或无资质的性保健品不予开通 | | 彩票 | 官方彩票代销资质 | 仅支持官方彩票资讯展示与代销信息类经营;互联网销售彩票、私彩、以开奖结果变相赌博一律禁止 | | 人工智能服务类(境内生成合成类) | 互联网信息服务算法备案(生成合成类)文件与生成内容标识方案;使用第三方模型的,另需上游授权文件与备案信息 | 含深度合成、情感陪伴、拟人化互动等形态;情感陪伴与拟人化互动类另需提交未成年人保护方案,向未成年人提供的须取得其父母或者其他监护人同意;境外模型相关服务见第一部分,不予开通 | **三、其他说明** + 类目认定以商品与服务的实际经营内容为准。以人工智能、自动化脚本或其他技术手段实现本规范所列经营范围的,按对应类目要求执行;实现方式不同不改变类目认定,亦不构成开通依据。 + 本规范所称未成年人,指未满十八周岁的公民(《中华人民共和国未成年人保护法》第二条);所称监护人同意,指其父母或者其他监护人的同意。 + 除本规范所列类目外,法律法规禁止经营或监管规定明确不予支持的经营范围,一律不予受理。 + 本规范所列类目与要求随法律法规及监管规定更新而调整,以最新发布版本为准。 + 资质材料提交、复核进度与结果咨询,请通过客服渠道办理;个案认定以审核意见为准。 + 售卖商品的经营场所 应根据运营主体、服务内容、服务对象、部署方式及实际经营活动,依法履行适用的备案、许可及其他合规义务;涉及依法须取得行业资质或行政许可的业务,还应满足相应要求。对于依法应在开展相关业务前完成的手续,请在完成后开展相应业务。支付宝将依法及依照适用的产品规则、服务协议履行相应审核、风险管理等职责;如有需要,可能要求补充相关材料,并根据核查情况及适用规则采取相应措施。 --- ## Machine Pay · AI按量付费 ### Machine Pay|AI 按量付费 目录路径:Machine Pay · AI按量付费 > 产品与 Skill 介绍 > Machine Pay|AI 按量付费 来源:https://aipay.alipay.com/products/machine-pay.md 专为智能体经济打造的收款产品,支持按量计费、自动结算,让每一个 AI 技能、MCP 服务、API 等资源都能实时变现。 #### Machine Pay(AI 按量付费) 专为智能体经济打造,让每一个 AI 技能、MCP 服务、API 都能实时变现。 `通过 npx -y @alipay/alipay-aipay@latest install 安装支付宝 AI 付 Skill,加载 alipay-aipay 技能为我的 api 接口集成按量付费,完成沙箱测试,并完成签约入驻` [一站式接入]() [接入文档]() ##### 产品介绍 Machine Pay 是支付宝 AI 付推出的基于 402 Payment Required HTTP 状态码的 A2M 方案,可让您的 API、数字内容或算力资源,能够直接向访问它们的 AI 智能体(AI Agents)发起自动收款。 ###### 收款方 接入支付宝 AI按量付费,让 Agent 调用你的服务时按调用付费,实现服务变现。 ###### Skill 与 MCP 平台方 一次接入,赋能平台下所有开发者在 Agent 调用服务时进行变现。 ![AI 按量付费产品介绍](https://mdn.alipayobjects.com/huamei_5fajmi/afts/img/J3TUQoPLn9IAAAAAVNAAAAgADlahAQFr/fmt.webp) ##### 核心能力 ###### 真正的按用量收费 告别低效率的月费订阅,为每一次 API / MCP-Tool 调用精准定价并收费。 ###### AI 客户自动买单 当 AI 访问你的资源时,A402 自动触发支付请求并完成结算,无需人工干预。 ###### 402 协议原生适配 基于 HTTP 402 Payment Required 状态码的 A2M 方案,专为 Agent 调用场景设计。 ###### 自动结算 按调用计量、计费和结算,让资源提供方专注服务本身,坐等收钱。 ##### 欢迎了解 A402 A402 是一种面向 AI 服务的按量付费方式。 当用户或 AI 应用想调用一个付费能力,比如查询数据、使用工具、生成内容、调用接口时,不需要先注册复杂账号、充值套餐或人工结算。服务方可以直接标明价格,调用方用一次、付一次,付款成功后立即获得服务结果。 简单说,A402 让 AI 服务像扫码买东西一样自然: 需要服务,发起请求;确认价格,完成支付;支付成功,马上使用。 ###### A402 是怎么工作的 ###### 发起服务请求 用户或智能体发起服务请求。 ###### 返回价格 服务方返回价格。 ###### 完成付款 用户或智能体通过支付宝 AI 付完成付款。 ###### 校验付款 服务方校验付款是否成功。 ###### 返回结果 校验通过后,服务方返回结果。 ```mermaid %%{init: {"sequence":{"useMaxWidth":false,"actorMargin":148,"messageMargin":40,"messageAlign":"center","diagramMarginX":18,"diagramMarginY":6,"mirrorActors":false,"wrap":true,"wrapPadding":10}}}%% sequenceDiagram participant 调用方 participant 服务端 participant 支付辅助方 participant 结算网络 调用方->>服务端: GET /api 请求付费资源 服务端-->>调用方: 402 需要支付:返回付款要求 调用方->>调用方: 根据付款要求生成支付载荷 调用方->>服务端: GET /api 携带支付签名 服务端->>支付辅助方: POST /verify 验证支付签名与付款要求 支付辅助方-->>服务端: 200 验证通过 Note over 服务端,支付辅助方: 支付辅助方可选;服务端也可以自行完成验签与结算 服务端->>服务端: 执行业务逻辑 服务端->>支付辅助方: POST /settle 发起结算 支付辅助方->>结算网络: 提交交易 结算网络-->>支付辅助方: 交易确认 支付辅助方-->>服务端: 200 结算完成,返回交易哈希 服务端-->>调用方: 200 OK 返回支付结果与内容 ``` ##### 客户场景 从服务托管到 Skill 平台,AI按量付费覆盖多种智能体变现路径。 ###### 服务托管到支付宝 免研托管自己服务到支付宝,自动化完成变现,只用等着收钱就行。 ###### 博查 · 茅茅虫 一句话完成,在个人助理里面写论文。 ###### API 类资源服务 面向 API、数字内容或算力资源提供方,Agent 每次调用自动触发收款与结算。 ##### 开始接入 AI 按量付费 开通 AI按量付费能力,让你的 API、Skill 与 MCP 服务在 Agent 经济中实时变现。 [一站式接入]() [接入文档]() --- ### 产品接入指南 目录路径:Machine Pay · AI按量付费 > 产品接入指南 来源:https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.md AI按量付费接入指南 商家/服务商可根据本文指引快速接入 **AI按量付费** 产品。 说明: + **AI按量付费** 产品支持自研商家/服务商通过 [自研应用](https://opendocs.alipay.com/common/02bijh#%E8%87%AA%E7%A0%94%E6%9C%8D%E5%8A%A1%E5%9E%8B%E5%BA%94%E7%94%A8) 或 [第三方应用](https://opendocs.alipay.com/common/02bijh#%E4%B8%89%E6%96%B9%E6%9C%8D%E5%8A%A1%E5%9E%8B%E5%BA%94%E7%94%A8) 代调用(传入 app_auth_token)方式,调用 API 接入。 #### 产品特色 **AI按量付费** 是支付宝AI付推出的基于402 Payment Required HTTP状态码的 A2M 方案,可让您的 API、数字内容或算力资源,能够直接向访问它们的 AI 智能体(AI Agents) 发起自动收款。 + **按量收费**:每次调用都可以独立定价,不必强依赖包月订阅。 + **原生适配 AI 智能体**:通过 `402 Payment Required` 告诉智能体“这个资源需要先付款”。 + **链路更短**:用户不需要在商家侧注册、登录、跳转到复杂页面后再回来。 + **AI Agent 自动购买资源**:用户授权后,由智能体完成请求、支付、交付。 #### 典型场景 1. 用户通过支付宝 App 支付并开通 AI付。 ![](https://mdn.alipayobjects.com/huamei_k1uezb/afts/img/4k7rSbZKjvQAAAAAXGAAAAgADmlSAQFr/original) 2. 用户向智能体下达指令,智能体访问商家的付费资源。 3. 商家服务端检测到用户需要付费,调用支付宝预下单接口,取得 `amt_pre_pay_id`。 4. 商家服务端返回 `402 Payment Required`,通过 `amtPaymentLink` 响应头传递预下单号。 5. 智能体将支付信息交给支付宝支付能力,用户确认后完成付款。 6. 智能体携带 `Payment-Proof` 再次请求商家资源,商家调用支付宝接口验证支付凭证。 7. 验证通过后,商家返回资源内容。 ![](https://mdn.alipayobjects.com/aipay_assets/afts/file/6zOYSJIjARAAAAAAZHAAAAgAeoh5AQJr) #### Vibe coding 快速集成(推荐) ```markdown 通过 npx -y @alipay/alipay-aipay@latest install 安装支付宝 AI 付 Skill,加载 alipay-aipay 技能为我的 api 接口集成按量付费,完成沙箱测试,并完成签约入驻 ``` #### 手动集成(传统) 你需要在自己的服务端完成两件事: 1. 用户未支付时,调用支付宝预下单接口,并返回 `402 Payment Required` 和包含预下单号的 `amtPaymentLink` 响应头。 2. 用户支付后,读取 `Payment-Proof` 并调用支付宝支付凭证验证接口。 ##### 示例代码 请访问[AI按量计费示例代码](https://github.com/alipay/ai/tree/main/code_example/aipay-402-example)获取示例代码。 ##### 完整接口时序图 ```mermaid sequenceDiagram actor User as 用户 participant Client as 商家客户端 participant Server as 商家服务端 participant Alipay as 支付宝 Note over User,Alipay: 访问付费资源并预下单获取账单 User->>Client: 访问付费资源
(如 /market/antgroup/trend) activate Client Client->>Server: GET /market/antgroup/trend activate Server Server->>Server: 检查资源需要付费
固定本地订单(out_trade_no/金额/商品) Server->>Alipay: alipay.aipay.agent.payment.precreate activate Alipay Alipay->>Alipay: 校验并生成预下单号 Alipay-->>Server: 返回 amt_pre_pay_id deactivate Alipay Server->>Server: 生成402响应 Server-->>Client: 402 Payment Required
amtPaymentLink: amtpp_v1_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx Client-->>User: 展示支付账单
(金额、商品、过期时间等) deactivate Client deactivate Server Note over User,Alipay: 用户完成支付(简化示例) User->>Alipay: 通过支付宝完成支付 activate Alipay Alipay-->>User: 返回支付凭证和订单号 deactivate Alipay Note over User,Alipay: 携带支付凭证访问资源 User->>Client: 提交支付凭证、交易号、买家客户端标识 activate Client Client->>Server: GET /market/antgroup/trend
Payment-Proof: Base64编码的支付凭证、交易号、买家客户端标识 activate Server Server->>Server: 解析Payment-Proof请求头 Server->>Alipay: alipay.aipay.agent.payment.verify activate Alipay Alipay-->>Server: 返回验证结果 deactivate Alipay alt 验证失败(active=false) Server-->>Client: 402 Payment Required
支付凭证无效或已过期 Client-->>User: 提示支付凭证无效
需重新支付 else 验证成功(active=true) Server->>Server: 返回资源内容 Server-->>Client: 200 OK
返回付费资源内容 Client-->>User: 展示资源内容 end deactivate Server deactivate Client ``` ##### 第一步:预下单并构造 402 响应 商家在检测到用户需要付费时,调用 [alipay.aipay.agent.payment.precreate(按量付费预下单接口)](),由支付宝创建预下单并返回 `amt_pre_pay_id`。 | 参数 | 要求 | 说明 | | --- | --- | --- | | `out_trade_no` | 必选 | 商户订单号,用于幂等控制 | | `service_id` | 必选 | 按量付费注册分配的服务标识;获取方式见[常见问题](https://opendocs.alipay.com/open/0ix1me?pathHash=99428df2) | | `goods_name` | 必选 | 商品或服务名称 | | `amount` | 必选 | 接口付费金额,单位元,不超过 50 元 | | `pay_before` | 必选 | 支付截止时间 | | `currency` | 可选 | 币种,仅支持 `CNY` | | `memo` | 可选 | 交易备注 | 预下单成功后,将返回的预下单号通过 `amtPaymentLink` 响应头传递给调用方,同时返回 HTTP `402 Payment Required`: ```http HTTP/1.1 402 Payment Required amtPaymentLink: ``` 完整请求和响应字段见[按量付费预下单接口]()。 ##### 第二步:验证 Payment-Proof 用户支付成功后,智能体会再次请求商家资源,并在请求头里带上 `Payment-Proof`。 ```http GET /market/antgroup/trend HTTP/1.1 Payment-Proof: ``` 商家服务端解析 `Payment-Proof` 后,可以得到支付凭证、支付宝订单号和买家客户端会话标识。 ```latex Payment-Proof (Base64前): { "protocol": { "payment_proof": "7cf8a6a93c924e13eaa4bf20c3a487f30d1fbdb759a1f229b4091b7d0158xxxx", "trade_no": "2026040900828111317760000001xxxx" }, "method": { "client_session": "xxxxxxxxxxxxxsCiAgICAic2Vzc2lvbklkIjogInh4IiwKICAgICJzaWduYXR1cmUiOiAi5Yqg562+5ZCO57uT5p6c77yM6YCa6L+HY3JlZGVudGlhbElk5Yqg562+YWdlbnRUb2tlbiArIHNlc3Npb25JZCkiCn0=", } } ``` 解密后,商家需调用 [alipay.aipay.agent.payment.verify(A2A 商户支付凭证验证接口)]() 接口验证支付凭证,支付宝会返回已支付订单的基本信息(如外部订单号、资源 ID 等,详细出参见 API 文档)。 入参均来自用户(买家)的 `Payment-Proof`: + 支付凭证:`payment_proof` + 支付宝订单号:`trade_no` + 买家客户端会话标识:`client_session` ###### 请求示例 ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayAipayAgentPaymentVerifyModel; import com.alipay.api.request.AlipayAipayAgentPaymentVerifyRequest; import com.alipay.api.response.AlipayAipayAgentPaymentVerifyResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayAipayAgentPaymentVerify { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayAipayAgentPaymentVerifyRequest request = new AlipayAipayAgentPaymentVerifyRequest(); AlipayAipayAgentPaymentVerifyModel model = new AlipayAipayAgentPaymentVerifyModel(); // 设置交易号 model.setTradeNo("20260324008281172041220000012182"); // 设置支付凭证 model.setPaymentProof("62922589b11acfc70faf4ebab1da7a9bbc438554e40d0a1dcdc7f35b3085xxxx"); // 设置买家客户端会话标识 model.setClientSession("ImNsaWVudFNlc3N"); request.setBizModel(model); AlipayAipayAgentPaymentVerifyResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ###### 响应示例 ```json { "alipay_aipay_agent_payment_verify_response":{ "msg":"Success", "amount":"0.01", "code":"10000", "out_trade_no":"ORDER_1774598472720_etm5dy", "trade_no":"20260324008281172041220000012182", "resource_id":"out_res_id_0000123", "active":true }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` 验证通过不只看接口调用成功,还要检查业务字段: + `active` 必须为 `true`。 + `amount` 必须等于本次资源价格。 + `out_trade_no` 必须是你生成的商户订单号。 + `resource_id` 必须和用户本次访问的资源一致。 + `trade_no` 不应被重复履约,避免同一笔支付被多次使用。 --- ### 按量付费预下单接口 目录路径:Machine Pay · AI按量付费 > API列表 > 按量付费预下单接口 来源:https://aipay.alipay.com/docs/ai-receive/api-list/alipay-aipay-agent-payment-precreate.md 商户调用预下单接口获取预下单号,用于 AI 按量付费。 #### 接口说明 接口名称:`alipay.aipay.agent.payment.precreate` #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.agent.payment.precreate` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 是否必选 | 类型与长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | | `pay_before` | 必选 | string [1,32] | 支付截止时间,超过后禁止支付,不超过当前时间12h | `2026-09-15T18:00:00+08:00` | | `amount` | 必选 | string [1,32] | 接口付费金额,单位元;**不超过 50 元** | `0.01` | | `goods_name` | 必选 | string [1,32] | 商品或服务名称 | `天气查询服务` | | `service_id` | 必选 | string [1,32] | 按量付费注册分配的服务 ID | `API2094383984` | | `out_trade_no` | 必选 | string [1,32] | 商户自身订单号,用于幂等控制 | `merchant001` | | `currency` | 必选 | string [1,32] | 币种,仅支持 `CNY` | `CNY` | | `memo` | 可选 | string [1,32] | 交易备注,用于账单展示 | `青铜套餐` | `service_id` 的获取方式见[常见问题](https://opendocs.alipay.com/open/0ix1me?pathHash=99428df2)。 #### 常见请求示例 以下为开放平台的第三方代调用示例;自研应用不使用示例中的 `app_auth_token`。 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayAipayAgentPaymentPrecreateModel; import com.alipay.api.request.AlipayAipayAgentPaymentPrecreateRequest; import com.alipay.api.response.AlipayAipayAgentPaymentPrecreateResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayAipayAgentPaymentPrecreate { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayAipayAgentPaymentPrecreateRequest request = new AlipayAipayAgentPaymentPrecreateRequest(); AlipayAipayAgentPaymentPrecreateModel model = new AlipayAipayAgentPaymentPrecreateModel(); // 业务参数与开放平台的预下单接口示例保持一致。 model.setMemo("青铜套餐"); model.setPayBefore("2026-09-15T18:00:00+08:00"); model.setCurrency("CNY"); model.setAmount("0.01"); model.setGoodsName("天气查询服务"); model.setServiceId("API2094383984"); model.setOutTradeNo("merchant001"); request.setBizModel(model); // 第三方代调用时设置应用授权令牌。 // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayAipayAgentPaymentPrecreateResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayAipayAgentPaymentPrecreate { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayAipayAgentPaymentPrecreateRequest request = new AlipayAipayAgentPaymentPrecreateRequest(); AlipayAipayAgentPaymentPrecreateModel model = new AlipayAipayAgentPaymentPrecreateModel(); // 业务参数与开放平台的预下单接口示例保持一致。 model.Memo = "青铜套餐"; model.PayBefore = "2026-09-15T18:00:00+08:00"; model.Currency = "CNY"; model.Amount = "0.01"; model.GoodsName = "天气查询服务"; model.ServiceId = "API2094383984"; model.OutTradeNo = "merchant001"; request.SetBizModel(model); // 第三方代调用时设置应用授权令牌。 // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayAipayAgentPaymentPrecreateResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 第三方代调用时,传入应用授权令牌。 $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.aipay.agent.payment.precreate&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "memo":"青铜套餐", "pay_before":"2026-09-15T18:00:00+08:00", "currency":"CNY", "amount":"0.01", "goods_name":"天气查询服务", "service_id":"API2094383984", "out_trade_no":"merchant001" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 是否必选 | 类型与长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | | `amt_pre_pay_id` | 必选 | string (32) | 按量付费预下单订单号,用于后续支付 | `amt_pre_pay_20260915_000001` | #### 响应示例 ```json { "alipay_aipay_agent_payment_precreate_response": { "code": "10000", "msg": "Success", "amt_pre_pay_id": "amt_pre_pay_20260915_000001" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` 预下单成功后,商家按[接入指南]()将 `amt_pre_pay_id` 通过 `amtPaymentLink` 响应头返回给调用方,并返回 HTTP `402 Payment Required`。 #### 公共错误码 [前往查看公共错误码](https://opendoc.alipay.com/common/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常或网络异常时,官方接口页允许使用同一请求重试 | | `INVALID_PARAMETER` | 参数有误 | 根据接口返回的具体参数错误信息修正后重试 | --- ### 商户支付凭证验证接口 目录路径:Machine Pay · AI按量付费 > API列表 > 商户支付凭证验证接口 来源:https://aipay.alipay.com/docs/ai-receive/api-list/alipay-aipay-agent-payment-verify.md 商户拿到支付凭证向支付宝请求验证 #### 接口说明 接口名称:`alipay.aipay.agent.payment.verify` #### 适用场景 A2A场景下商户拿到支付凭证向支付宝请求验证。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.aipay.agent.payment.verify` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | String | 必选 | 32 | 支付宝交易号,交易的唯一标识 | - | `20260324008281172041220000012182` | | `payment_proof` | String | 必选 | 64 | 支付凭证 | - | `62922589b11acfc70faf4ebab1da7a9bbc438554e40d0a1dcdc7f35b3085xxxx` | | `client_session` | String | 可选 | 1024 | 客户端会话标识,用于校验买家安全性、真实性 | - | `ImNsaWVudFNlc3N` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayAipayAgentPaymentVerifyModel; import com.alipay.api.request.AlipayAipayAgentPaymentVerifyRequest; import com.alipay.api.response.AlipayAipayAgentPaymentVerifyResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayAipayAgentPaymentVerify { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayAipayAgentPaymentVerifyRequest request = new AlipayAipayAgentPaymentVerifyRequest(); AlipayAipayAgentPaymentVerifyModel model = new AlipayAipayAgentPaymentVerifyModel(); // 设置交易号 model.setTradeNo("20260324008281172041220000012182"); // 设置支付凭证 model.setPaymentProof("62922589b11acfc70faf4ebab1da7a9bbc438554e40d0a1dcdc7f35b3085xxxx"); // 设置买家客户端会话标识 model.setClientSession("ImNsaWVudFNlc3N"); request.setBizModel(model); AlipayAipayAgentPaymentVerifyResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayAipayAgentPaymentVerify { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayAipayAgentPaymentVerifyRequest request = new AlipayAipayAgentPaymentVerifyRequest(); AlipayAipayAgentPaymentVerifyModel model = new AlipayAipayAgentPaymentVerifyModel(); // 设置交易号 model.TradeNo = "20260324008281172041220000012182"; // 设置支付凭证 model.PaymentProof = "62922589b11acfc70faf4ebab1da7a9bbc438554e40d0a1dcdc7f35b3085xxxx"; // 设置买家客户端会话标识 model.ClientSession = "ImNsaWVudFNlc3N"; request.SetBizModel(model); AlipayAipayAgentPaymentVerifyResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); $responseResult = $alipayClient->execute($request); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.aipay.agent.payment.verify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'biz_content={ "trade_no":"20260324008281172041220000012182", "payment_proof":"62922589b11acfc70faf4ebab1da7a9bbc438554e40d0a1dcdc7f35b3085xxxx", "client_session":"ImNsaWVudFNlc3N" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | String | 必选 | 32 | 支付宝交易号,交易的唯一标识 | - | `20260324008281172041220000012182` | | `amount` | Price | 必选 | 6 | 订单金额,CNY | - | `0.01` | | `active` | Boolean | 必选 | 10 | 支付凭证是否有效 | - | `true` | | `out_trade_no` | String | 必选 | 16384 | 外部幂等号 | - | `ORDER_1774598472720_etm5dy` | | `resource_id` | String | 可选 | 32 | 卖家自定义的resourceId(字段已废弃) | - | `out_res_id_0000123` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_aipay_agent_payment_verify_response":{ "code":"10000", "msg":"Success", "trade_no":"20260324008281172041220000012182", "amount":"0.01", "resource_id":"out_res_id_0000123", "active":true, "out_trade_no":"ORDER_1774598472720_etm5dy" }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` 必须检查active=true和使用支付宝公钥验证sign的正确性 ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_aipay_agent_payment_verify_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://opendoc.alipay.com/common/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `CLIENT_SESSION_IS_EMPTY` | 凭证校验阶段clientSession为空 | C agent需要升级最新CLI | | `PAYMENT_PROOF_AGENT_MISMATCH` | 智能体与凭证商户不一致 | 请确认智能体商户与支付凭证所属商户一致 | | `PAYMENT_PROOF_BUYER_MISMATCH` | 支付买家与凭证买家不一致 | 卖家凭证水平越权,请检查权限后发起 | | `PAYMENT_PROOF_EMPTY` | 支付凭证为空 | 请传入有效的paymentProof参数 | | `PAYMENT_PROOF_ID_MISMATCH` | seller_id与凭证商户不一致 | 请确认发起请求的商户与支付凭证所属商户一致 | | `PAYMENT_PROOF_INVALID` | 支付凭证格式错误 | 支付凭证需要为64位 | | `PAYMENT_PROOF_NOT_FOUND` | 支付凭证过期或不存在 | 请确认支付凭证是否有效,凭证可能已过期 | | `PAYMENT_PROOF_STATUS_INVALID` | 支付凭证状态无效 | 请确认支付凭证状态,凭证可能已被使用或失效 | | `PAYMENT_PROOF_TRADE_NO_MISMATCH` | 交易号与凭证不一致 | 请确认交易号与支付凭证关联的交易号一致 | | `TRADE_NOT_FOUND` | 交易不存在 | 请确认交易号是否正确 | | `TRADE_NO_EMPTY` | 交易号不能为空 | 请传入有效的tradeNo参数 | | `TRADE_NO_INVALID` | 订单号格式错误 | 订单号长度需要为32位 | | `TRADE_STATUS_CLOSED` | 交易已关闭 | 该交易已关闭,无法验证支付凭证 | | `TRADE_STATUS_UNPAID` | 交易未支付 | 该交易尚未完成支付,请等待支付完成后再验证 | --- ## Token Pay · AI 连续订阅 ### Token Pay(AI 连续订阅):为AI行业打造的变现基础设施 目录路径:Token Pay · AI 连续订阅 > 产品与 Skill 介绍 > Token Pay(AI 连续订阅):为AI行业打造的变现基础设施 来源:https://aipay.alipay.com/products/token-pay.md 专为 AI 应用打造的智能订阅产品,帮助你快速构建会员体系、提升用户留存,并通过 Skill 一行命令接入。 一个平台,统一实现定价、订阅、收款、留存和增长 个人身份或注册新企业:[联系销售]() 已有企业身份:[立即接入]() [接入文档]() #### 产品价值 手动续费拖慢回款,营销手段有限推高获客成本,用量变化又让定价更复杂。支付宝 AI 连续订阅为 AI 业务提供灵活定价、自动收款和营销工具,帮助企业提升用户留存,支持多种变现方式。 #### 产品优势 ##### 低代码快速部署 仅需简单配置,即可渲染商品套餐前端页面,无需开发收银台。在 Vibe Coding 模式下即可快速构建商业闭环,让支付集成进入开箱即用的智能时代。 ##### 多元定价策略 周期订阅、低价试用+付费转化——轻松将多元定价策略推向市场。支持多周期定价(日/月/季/年)、试用转付费、首购优惠等多模式组合,产品演进与商业变现同步迭代。 ##### 团体订阅&席位增减 面向企业团队的按席位计费模式,支持席位灵活增加与减少,按比例即时结算。项目高峰随时扩容,项目结束灵活缩减,无需重新签约。 ##### 套餐灵活升降级 支持用户随时升级或降级订阅套餐,系统自动计算差价并调整下期扣款,无需重新签约,承接用户不同阶段的付费意愿,帮助商户延长用户生命周期。 ##### 自动续购 余额不足自动触发充值,服务不中断。用户设置余额阈值和续购金额,系统智能扣款补充,让按量计费场景从此告别手动充值的流失风险。自动续购暂未向公海开放,需要 BD 定向邀约。 ##### 全链路营销工具 低价试用降低决策门槛,首购优惠锁定新客首单,教育优惠拓展学生群体——多种策略驱动用户增长。智能重试扣款、宽限期保障、到期提醒——用柔性策略替代生硬解约,将流失转化为暂时休眠。 #### 接入流程 面向 Agent 的 Skill 安装并执行集成的命令 ##### Skill 安装 将以下命令复制给 Agent `通过 npx alipay-subscription-skill@latest 安装支付宝订阅接入 skill,加载 alipay-subscription 技能告诉我怎么接入订阅` #### 产品核心功能 ##### 低代码快速接入 面向企业与个人开发者,简单配置商品即可低代码部署。 - **AI 开发者友好:**支付方案封装为 Skill,接入文档支持 AI 全文读取,无需处理复杂底层逻辑,可通过 Vibe Coding 完成集成。 - **配置轻量化:**自动生成前端商品列表,减少开发工作。 ##### 灵活订阅产品 为 AI 商户提供多样化计费模式,满足个人与企业团队的订阅需求。 - **灵活升降级:**随时调整套餐,自动计算差价和下期扣款,无需重新签约,帮助提升留存。 - **团体订阅:**按周期计费,支持个人与团队订阅,席位可灵活增减。 - **智能扣款:**算法触发扣款,失败后动态重试,提高成功率、减少非意愿流失。 ##### 营销工具包 提供首购立减、教育优惠、会员折扣等工具,支持订阅业务从拉新到留存。 - **新客拉新:**通过新客试用、首购优惠降低门槛,促进转化。 - **老客留存:**通过订阅降级、暂停和续费立减减少流失。 - **增长转化:**通过一键升级、教育优惠提升客单价与 GMV。 ##### 交易基础设施 为 AI 业务提供交易、账户、核验与通信配套能力。 - **发票:**支付后一键开票,兼顾合规与财务效率。 - **场景钱包:**为 AI 企业提供安全合规、灵活的平台储值账户。 - **实名认证:**支持个人与企业用户身份核验。 - **登录安全识别:**通过 AI+ 行为验证应对人机及 AI 攻防。 - **邮箱&短信网关:**提供统一、安全可靠的通信服务。 #### 最佳实践 ##### MiniMax 全球领先的通用人工智能科技公司,旗下自研大模型及 AI 原生产品覆盖文本、语音、图像、视频和音乐等多模态能力。 需求 企业采买大模型服务需解决席位管理、套餐选择、席位调整与报销对齐等全链路需求。 解决方案 - 接入支付宝团体席位订阅,按成员数弹性计费,项目高峰随时扩容、灵活缩减 - 配套支企付大额支付,支持企业银行转账采购,票款报销流程一步到位 #### 常见问题 什么是支付宝 Token Pay? 专为 AI 行业设计的订阅计费基础设施,整合个人订阅、团体席位、积分自动续购(需 BD 定向邀约)、营销增长等全链路能力。无论是单次订阅、周期扣款还是按量续费,一套方案全面支撑。 支持哪些定价模式? 支持周期订阅(日/月/季/年)、按席位订阅、按量自动续购(需 BD 定向邀约)、低价试用+付费转化、首购优惠、教育优惠等多种定价和营销策略,灵活组合满足各类场景。 是否支持企业客户? 完全支持。团体席位订阅专为企业团队设计,支持多人统一付费、大额支付方案、席位弹性扩缩容、发票开具,适配企业采购流程。 #### 开始接入 Token Pay 与我们的解决方案专家取得联系,获取一对一接入支持。 个人身份或注册新企业:[联系销售]() 已有企业身份:[立即接入]() [接入文档]() --- ### 产品介绍 目录路径:Token Pay · AI 连续订阅 > 产品介绍 来源:https://aipay.alipay.com/docs/subscribe/introduce.md #### 基本介绍 面向AI行业,从首个付费用户到规模化订阅增长,支付宝提供全链路支付与资金管理方案。大幅降低收款成本与运营复杂度,助力业务高效变现。 + **核心订阅能力:**个人&团体订阅。同时提供低代码配置、灵活升降级、席位增加&减少等核心能力,同时支持单笔支付能力。 + **营销工具包:**覆盖从用户拉新、老客留存到增长转化的全生命周期营销场景,帮助商户加速获客、减少流失。 + **用户管理门户**:为商户提供开箱即用的用户自助管理页面,用户可自主完成订阅管理、套餐升降级、账单 + **交易基础设施:**实名认证与发票保障交易合规等能力,构建安全可靠的金融基础设施,为AI商户持续经营保驾护航。   商家可以通过 [AI订阅接入指引](https://b.alipay.com/page/checkout-management/subscription-onboarding) 来完成接入配置,完成后请认真阅读相关商家服务规范。 :::tips 支付宝面向开发者提供 **Skill安装并执行集成的命令 **,将以下命令复制给 Agent,即可快速接入「AI订阅」产品: ::: ```json 通过 npx alipay-subscription-skill@latest 安装支付宝订阅接入 skill,加载 alipay-subscription 技能接入个体订阅/团队订阅 ```   此外,支付宝为开发者提供了低代码的友好接入方式,配置商品信息即可生成前端页面,帮助开发者快速完成支付能力对接,快速实现商业化。 ![](https://mdn.alipayobjects.com/afts/img/A*WprJQ4LA3i0AAAAAgCAAAAgAeq8wAA/original?bz=openpt_doc&t=2WcN9UuBj8DSIdusq3r2fNL_guTYEYuyb17lvs2ycmMDAAAAZAAAMK8AAAAA) #### 适用场景 ##### 轻量灵活的订阅产品 **低代码接入:**面向AI行业开发者提供的接入友好方式,简单配置,即可自动生成前端商品列表页面。支付宝将支付解决方案封装为Skill组件,开发者无需处理复杂底层逻辑,在Vibe Coding模式下即可快速构建商业闭环。 ![](https://mdn.alipayobjects.com/afts/img/A*5WYeQLUK8yYAAAAAVgAAAAgAeq8wAA/original?bz=openpt_doc&t=a1vufCPyJ4EEn1dQ-mbJbeESiu_1C12sOlMdp9OCW9sDAAAAZAAAMK8AAAAA) **个体&团体订阅:**面向个人客户及企业团体客户使用AI模型服务所提供的订阅付费模式,主要包括用户首次购买、变更已有套餐、持续扣款、服务退订等应用场景,团体客户还支持席位数量灵活调整的能力。 ![](https://mdn.alipayobjects.com/afts/img/A*futSSYMPPXIAAAAAWMAAAAgAeq8wAA/original?bz=openpt_doc&t=1I8untozZohlih2jrLG_34rkk83lkg5D7VjUSkVDzdsDAAAAZAAAMK8AAAAA) ##### 营销工具包 为AI商户打造一站式营销解决方案,支持灵活配置,从拉新到留存,助力业务增长。 | **营销策略** | **场景案例** | | :---: | :---: | | 用户拉新 | 5元试用7天,后续订阅38元/月 | | 老客留存 | 连续按月订阅享受8折优惠 | | 人群优惠 | 通过身份认证后,享受5折教育优惠 | 为保障支付宝用户的权益,当前 **营销工具包** 使用存在部分限制,具体如下: 1. **试用期能力:**仅对部分特邀商户开放; 2. **优惠能力:**优惠后的金额不得低于正价的1/3。若首次实际支付金额低于正价的1/3,会导致用户在续费时扣款失败。 ![](https://mdn.alipayobjects.com/afts/img/A*evGrT7U5HRgAAAAAU9AAAAgAeq8wAA/original?bz=openpt_doc&t=D1iKk9_VsoL5S3ASvAjLlnRACKlwwTT8wXMCB2ivTlUDAAAAZAAAMK8AAAAA) ##### **商业化********基础设施** 面向AI行业计费与交易特性,提供全栈配套解决方案,为AI行业商户提供安全、高效、合规的交易保障体系。 + **实名认证:**个人以及企业用户的身份核验产品,为AI商户提供极致体验与广泛覆盖的身份核验能力。 + **发票产品**:提供支付后一键开票能力,确保交易合规、财务高效。 ![](https://mdn.alipayobjects.com/afts/img/A*4-PaT4dAOF8AAAAAUoAAAAgAeq8wAA/original?bz=openpt_doc&t=245Xy8cRWv6GMAVo9wjXEq27XEaed77R07XdatofIL8DAAAAZAAAMK8AAAAA) ##### **用户门户** 用户门户是支付宝为商户托管的用户自助管理订阅页面,将页面嵌入商户产品后,用户可自行完成订阅管理、升降级、取消续费、账单查询等操作。 + **用户自助管理:**用户可随时完成订阅状态、自助调整订阅套餐、查询账单等操作,提升用户体验,大幅减少商户客服咨询量与人工处理成本。 + **多元挽留策略:**在用户取消订阅时,可收集取消原因,帮助分析流失因素、优化留存策略,降低流失率。 ![](https://mdn.alipayobjects.com/afts/img/A*6tUARpE_HFAAAAAAgBAAAAgAeq8wAA/original?bz=openpt_doc&t=EnlNS1gcsorIVucJ_fLoyIgprgy-0Hnwh5HtTB6M-hQDAAAAZAAAMK8AAAAA) #### 准入条件 目前只针对满足以下条件的商户开放,审核通过后可使用: 1. 支持的账号类型:[支付宝企业账号](https://opendocs.alipay.com/common/02kkum) 2. 适用商家经营类目(MCC):** 网络通讯-软件开发服务(B0121)、网络通讯-互联网数据服务(B0120)、网络通讯-信息检索服务/网络论坛(B0113)、网络通讯-其他在线应用或综合类服务(B0125)、商业生活服务-在线工具(B0112)、生活缴费-话费充值与缴费(B0164)**。[查看详情](https://opendocs.alipay.com/common/02khjv#%E5%95%86%E4%B8%9A%E7%94%9F%E6%B4%BB%E6%9C%8D%E5%8A%A1) 若不符合以上条件的商家,但希望接入AI订阅解决方案,可[点此链接](https://render.alipay.com/p/yuyan/180022670000100564/index.html)提交意向信息。 #### 计费模式 + 涉及收单产品([商家扣款](https://b.alipay.com/page/product-workspace/product-detail/I1080300001000066811/newProductList?)、[APP支付](https://b.alipay.com/page/product-workspace/product-detail/I1080300001000041313/newProductList?)、[电脑网站支付](https://b.alipay.com/page/product-workspace/product-detail/I1080300001000041203/newProductList?))将按照对应产品的收单费率单笔计费。 + 解决方案实际计费以方案开通时签约的基础产品费率为准,可进入 **商家平台** > **账号中心** > [签约管理](https://b.alipay.com/page/products-sign/dynlink/productSign/signManage.htm) 查看产品签约费率详情。 #### 接入要求和规范 商家可以通过 [订阅接入指引](https://b.alipay.com/page/checkout-management/subscription-onboarding) 来完成接入配置,完成后请认真阅读相关商家服务规范。 **产品开通**:按要求填写并提交产品开通申请,提交后进入系统审核流程,审核通过结果将以短信通知到商户。商户也可点此查询 [产品开通情况](https://b.alipay.com/page/products-sign/dynlink/productSign/signManage.htm) 。 ##### 商家服务规范 1. 商家需按照[《AI订阅解决方案产品运营规则》](https://opendocs.alipay.com/pre-open/0jt6df)、[《商家扣款产品使用规范》](https://opendocs.alipay.com/b/06aql9?pathHash=c82109d2)、[《商家扣款产品服务质量管理规则》](https://opendocs.alipay.com/b/0cbc33?pathHash=9a845fe4)以及与之相关的补充协议/平台规则等开展业务。对于服务质量不达标的商户,支付宝对商户采取警告、延长结算周期、关闭自动续费新增签约、关闭自动续费扣费权限等处罚措施。如出现客诉超标等情形,支付宝将有权**代商户发起退款,**商户须及时关注消费者投诉处理情况。 2. 为保障用户使用支付宝支付服务的体验,支付宝支持用户发起交易反馈与投诉。支付宝会将用户发起的售后诉求、投诉诉求同步至商家,商家可通过商家平台管理后台及时关注并处理,同时支付宝提供API接口服务,商家可通过API对接实现系统交互处理。详见[《商家支付交易风险投诉处理指南&说明》](https://opendocs.alipay.com/b/05f8ww)。 3. 商家可通过AI订阅解决方案使用商家扣款产品,订阅场景下限制 **新签用户数5000个**,若超出此上限,需要扩容,请[点此链接](https://render.alipay.com/p/yuyan/180022670000138080/index.html)提交信息申请。 ##### 结算规范 **收款账户:**默认收款到签约账号的支付宝余额账户。 **结算周期:**根据商家经营情况的不同,商家通过AI订阅解决方案使用商家扣款的所有订单将以不同的账期进行交易资金管控,管控期间资金处于“止付”状态。产品开通成功后,支付宝将通过站内信/邮件方式通知商家具体结算账期,后续**支付宝将根据商户的具体经营情况动态调整结算账期**。详见[《AI订阅解决方案产品运营规则》](https://opendocs.alipay.com/pre-open/0jt6df)。 --- ### 个体订阅 目录路径:Token Pay · AI 连续订阅 > 接入指南 > 个体订阅 来源:https://aipay.alipay.com/docs/subscribe/integration-guide/individual.md #### 产品特色 **订阅能力**是支付宝为AI行业打造的专属解决方案,面向于**个体客户**帮助商家进行订阅类商品的管理、售卖,降低运营管理成本。 个体用户在购买订阅产品时,通过授权将商户账号和用户支付宝账号进行绑定,借助支付宝账号资金渠道,直接帮助商家完成周期性自动扣款。此外,支持用户一键操作升级/降级,支付宝将自动计算需要补充支付的金额或变更订阅的信息。 产品优势: + **降低收款成本**:用户一次签约后支付宝自动完成周期性扣款,无需手动确认,降低用户付费摩擦和流失率; + **提升用户留存**:支持用户随时升级或降级订阅套餐,自动结算无需重新签约,帮助商户延长用户生命周期。 #### 订阅商品与价格管理 提供商品价格管理后台,商家可直接登录支付宝商家平台进行可视化配置,维护自己的商品和服务信息,并关联多种计价模式、设置默认价格等。支持两种方式接入: **1、低代码接入**:通过后台进行简单配置,通过低代码接入自动生成的商品展示页面与收银台页面。 ![](https://mdn.alipayobjects.com/afts/img/A*VWGvSo6nkpIAAAAAVgAAAAgAeq8wAA/original?bz=openpt_doc&t=xuZbMY0mMKktiGfGrmYwdIIoKR_OvQssdNAQV4Ryo2kDAAAAZAAAMK8AAAAA) **2、通过API接口接入**:通过商品价格增删改查的全套API接口接入,支持商家直接调用。 商家可按如下指引调用接口,进行 **商品管理、价格管理** 等操作。 ```mermaid sequenceDiagram participant 商户 participant 支付宝 商户->>支付宝: 1: 管理后台/api创建商品信息(alipay.trade.product.create) 支付宝-->>商户: 1.1: 返回商品id 商户->>支付宝: 2: 管理后台/api创建商户下的价格信息(alipay.trade.price.create),该接口具备同时创建新商品 支付宝-->>商户: 2.1: 返回价格id 商户->>支付宝: 3: 管理后台/api设置商品下默认金额(alipay.trade.product.modify) 支付宝-->>商户: 3.1: 返回设置结果 ``` ##### 商品创建 商家可调用 [alipay.trade.product.create(商品创建接口)](https://opendocs.alipay.com/solution/615bfd8c_alipay.trade.product.create.md),获取 **商品id(product_id)** **注意:** + **商品名称(name)** 后续将在用户的签约页面进行展示,请务必保证名称的准确 + **商品模型元数据(metadata)** 支持商户进行自定义传参,用于记录商户需要消费的个性信息。 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **name** | **商品名称** | String | 是 | [1,255] | Gold 会员 | 商品名称 | | **description** | **商品描述** | String | 是 | [1,255] | 基础权益 | 商品描述 | | **metadata** | **商品模型元数据** | String | 否 | [1,2000] | {"key":"value"} | 商户需要保存在商品模型中的元数据 | | **images** | **图片地址** | String | 否 | [1,4000] | [["https://antgroup.com"]](https://antgroup.com"]) | 图片地址,支持传入不超过5个地址 | | **marketing_features** | **营销信息** | String | 否 | [1,4000] | ["16000积分"] | 营销信息,支持传入不超过5个营销信息 | | **unit_label** | **单位别名** | String | 否 | [1,100] | 积分 | 单位别名 | | **url** | **跳转地址** | String | 否 | [1,500] | [https://antgroup.com](https://antgroup.com) | 可用于跳转商户网址地址 | **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "name":"Gold 会员", "description":"基础权益", "metadata":"{\"key\":\"value\"}", "images":"[\"https://antgroup.com\"]", "marketing_features":"[\"16000积分\"]", "unit_label":"积分", "url":"https://antgroup.com" }' ``` ##### 价格创建 商家可调用 [alipay.trade.price.create(价格创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/price-create.md)创建价格信息,获取 **价格实例id(price_id)** **注意:** + **价格实例id(price_id)** 与创建时传入的 **商品id(product_id)** 相关联,会在结果中一同返回 + 订阅类商品,必传 **循环计价模型(recurring)** 相关信息 - **计价周期单位(interval)**:计价周期单位和 **interval_count** 组合使用,支持枚举值为 DAY 和 MONTH,分别代表周期的单位为「天」或「月」 - **计价周期间隔(interval_count)** :计价周期间隔和 **interval** 组合使用。例如 **interval** 为 MONTH,**interval_count** = 1,则扣款周期为 1 月:系统以首次购买日期为周期起始日,下一周期起始日按设定间隔顺延,若目标日期不存在则自动调整至当月最后一天。例如首次购买日为1月31日,则下一周期起始日为2月28日(或29日),再下一周期起始日恢复为3月31日。实际扣款将在周期起始日前1天发起,确保资金及时到账,服务无缝续期。 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **unit_amount** | **单位金额** | Number | 是 | [1,1000000000] | 1000 | 单位金额,单位:分 | | **product_id** | **商品id** | String | 条件必选 | [1,32] | 202603230010000006783 | 商品id,通过商品创建接口获取;和product_data二选其一 | | **product_data** | **商品信息** | Object | 条件必选 | - | - | 商品模型,可以通过该参数一并创建商品信息 | | **┗ name** | **商品名称** | String | 是 | [1,255] | Gold 会员 | 商品名称 | | **┗ description** | **商品描述** | String | 是 | [1,255] | 基础权益 | 商品描述 | | **┗ metadata** | **商品信息元数据** | String | 否 | [1,2000] | {"key":"value"} | 商户需要保存在商品模型中的元数据 | | **recurring** | **循环计价模型** | Object | 否 | - | - | 循环计价配置,用于订阅等场景 | | **┗ interval** | **计价周期单位** | String | 是 | [1,32] | MONTH | 计价周期单位,和interval_count组合使用。枚举值:MONTH(月)、DAY(日) | | **┗ interval_count** | **计价周期间隔** | Number | 是 | [1,10000] | 1 | 计价周期间隔,和interval组合使用 | | **eligibility_type** | **价格限定购买的身份类型** | String | 否 | [1,32] | student | 只有满足该类型的身份才可以购买。具体的枚举值待支付宝侧分配 | | **eligibility_expire_time** | **指定身份购买后的时效时间** | String | 否 | [1,32] | 3d | 满足了eligibility_type的身份购买后,失效的时间。如3d = 3天, 3m = 3月 | | **metadata** | **价格信息元数据** | String | 否 | [1,2000] | {"key":"value"} | 商户需要保存在价格模型中的元数据 | 注意:其它参数若有传参需要,请与支付宝技术支持沟通确认 **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "unit_amount":1000, "product_id":"202603230010000006783", "product_data":{ "metadata":"{\"key\":\"value\"}", "name":"Gold 会员", "description":"基础权益" }, "recurring":{ "interval_count":1, "interval":"MONTH" }, "eligibility_type":"student", "eligibility_expire_time":"3d", "metadata":"{\"key\":\"value\"}" }' ``` ##### 商品修改 商家可调用 [alipay.trade.product.modify(商品修改接口)](https://opendocs.alipay.com/solution/26d7e027_alipay.trade.product.modify.md),为商品设置默认的价格(price_id) **注意:** 每个商品仅能配置一个价格为默认价格 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **product_id** | **商品id** | String | 是 | [1,32] | 20260324001001 | 本次更新的商品id | | **name** | **商品名称** | String | 否 | [1,255] | Gold 会员 | 商品名称 | | **description** | **商品描述** | String | 否 | [1,255] | 基础权益 | 商品描述 | | **default_price_id** | **默认价格id** | String | 否 | [1,32] | 20260324001001 | 该商品默认价格id | | **metadata** | **商品元数据** | String | 否 | [1,1024] | {"key":"value"} | 商品元数据 | **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "product_id":"20260324001001", "name":"Gold 会员", "description":"基础权益", "default_price_id":"20260324001001", "metadata":"{\"key\":\"value\"}" }' ``` ##### 商品查询 商家可调用 [alipay.trade.product.query(商品查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/product-query.md),查询已创建的商品信息 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **product_id** | **商品id** | String | 否 | [1,32] | 202603230010000006783 | 商品id,通过创建接口获取 | | **query_options** | **查询选项** | array | 否 | [1,10] | ["price"] | 查询选项,商户通过上送该参数来定制额外返回的信息字段,数组格式。枚举支持:price(默认价格信息) | 注意:其它参数若有传参需要,请与支付宝技术支持沟通确认 **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "product_id":"202603230010000006783", "query_options":[ "price" ] }' ``` ##### 价格查询 商家可调用 [alipay.trade.price.query(价格查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/price-query.md),查询已创建的价格信息 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **price_id** | **价格id** | String | 是 | [1,32] | 202603240020000001001 | 价格id | | **query_options** | **查询选项** | array | 否 | [1,10] | ["product"] | 查询选项,商户通过上送该参数来定制额外返回的信息字段,数组格式。枚举支持:product(商品信息) | **注意:** 其它参数若有传参需要,请与支付宝技术支持沟通确认 **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "price_id":"202603240020000001001", "query_options":[ "product" ] }' ``` **响应参数说明** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **id** | **价格id** | String | 价格id | | **active** | **是否可用** | Boolean | 该价格实例是否可用 | | **product_id** | **商品id** | String | 关联商品id | | **unit_amount** | **单位金额** | Number | 单位金额,单位:分 | | **type** | **价格类型** | String | 价格类型,枚举值:recurring(订阅)、one_time(单次支付) | | **metadata** | **价格信息元数据** | String | 商户保存在价格模型中的元数据 | | **gmt_create** | **创建时间** | String | 创建时间 | | **product** | **商品信息** | Object | 关联的商品信息(需通过query_options请求) | | **recurring** | **循环计价模型** | Object | 循环计价配置(订阅类型时返回) | #### 购买订阅商品 用户选择订阅商品进行购买,商家将用户购买的商品传给支付宝,将自动生成付款链接或二维码,用户可直跳转至支付宝APP或扫码唤起支付宝APP进行产品订阅的信息确认,完成订阅和支付。 以下图片仅做线上样式参考,实际页面内容以线上为准。 ![](https://mdn.alipayobjects.com/afts/img/A*6hx5RIGleYgAAAAAThAAAAgAeq8wAA/original?bz=openpt_doc&t=D5gSWl5AKH1DoT0JBzV3rawiYH1fobmM5QlAAE7k_z0DAAAAZAAAMK8AAAAA) 商家可按如下指引调用接口,进行**创建客户**、**创建订阅**、**获取订阅消息通知** 等操作。 ```mermaid sequenceDiagram participant 用户 participant 商户 participant 支付宝 用户->>商户: 1: 发起订阅 商户->>支付宝: 1.1: 若未创建过,则先调用api创建客户(alipay.trade.customer.create) 支付宝-->>商户: 1.2: 返回支付宝侧客户id 商户->>支付宝: 1.3: 创建订阅(alipay.trade.subscription.create) 支付宝-->>商户: 1.4: 返回订阅id以及支付链接 商户->>商户: 1.5: 消费支付链接,如果是网页版,展示支付二维码 商户-->>用户: 1.6: 二维码展示 商户->>支付宝: 1.7: 消费支付链接,如果是app端,则唤起支付宝,与二维码选其一对客 用户->>支付宝: 2: 二维码场景:用户扫码进行支付;app端:唤起支付宝进行支付 支付宝-->>商户: 2.1: 支付完成发送订阅生效消息(alipay.trade.subscription.changed) ``` ##### 创建客户 商家可调用 [alipay.trade.customer.create(客户创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/customer-create.md)创建客户,获取 **客户id(****customer_id****)** **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **name** | **客户名称** | String | 是 | [1,64] | 张三 | 客户名称 | | **description** | **客户描述** | String | 否 | [1,255] | 业务客户 | 客户描述 | | **phone** | **客户手机号** | String | 否 | [1,50] | 15011112222 | 客户手机号,和客户邮箱需至少传入1个 | | **email** | **客户邮箱** | String | 否 | [1,255] | email@antgroup.com | 客户邮箱,和客户手机号需至少传入1个 | **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.customer.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "name":"张三", "description":"业务客户", "phone":"15011112222", "email":"email@antgroup.com" }' ``` ##### 创建订阅 商家可调用 [alipay.trade.subscription.create(订阅创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-create.md) ,获取 **订阅id(****subscription_id****)** **注意:** + 创建订阅时,需要在订阅项目信息(items)中,传入用户所购买的商品对应的价格id(price_id),来确定此次订阅购买的商品价格 + 创建订阅后商户将获得适用于跳转支付宝端的长链接*_alipay_jump_schema __**或 适用于生成二维码的短链接**__alipay_schema_*,商户可根据实际场景自主选择使用。 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | | **items** | **订阅项目信息** | String | 是 | | 用于记录核心的订阅项目信息 | | **┗ price_id** | **价格id** | String | 是 | 202603201234567889 | 价格创建接口(alipay.trade.price.create)返回的价格id,代表本次操作的目标价格信息 | | **customer_id** | **客户id** | String | 是 | 208812345678 | 客户id,客户创建接口(alipay.trade.customer.create)返回的客户id | | **metadata** | **订阅信息元数据** | String | 否 | {"key":"value"} | 商户可通过此字段进行订阅信息的自定义传参,订阅生效后不可修改,将在全链路通知或查询中返回 | | **pay_amount** | **支付金额** | String | 否 | 100 | 支付金额,单位分;仅用于商户自定义金额,若传了该值,用户实际支付金额会以该值为准;若不传该金额,则会按照传入的价格id来获取本次应支付的金额 | **注意:** 其它参数若有传参需要,请与支付宝技术支持沟通确认 **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "items":[ { "price_id":"202603201234567889" } ], "subscribe_title":"订阅月会员", "customer_id":"208812345678" }' ``` ##### 获取订阅消息通知 商家通过订阅 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅商品的购买结果 **注意:** + 该接口为支付宝主动向商户发送的消息通知接口,商户需要配置应用网关地址(NOTIFY_URL) + 商户收到消息后需要返回 `success` 表示处理成功,否则返回 `fail`,支付宝会进行重试 + 投递重试策略:25小时内完成8次通知,间隔频率为:2m、10m、10m、1h、2h、6h、15h + 商户获取消息通知后,需要使用支付宝公钥进行验签 + 用户购买成功后,发送的订阅产品商户消息通知中的 **订阅变更类型(change_type)**为 ****订阅已生效****(active)** **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **change_type** | **订阅变更类型** | String | 是 | (32) | active | 订阅变更类型,枚举值: + **active-订阅已生效,用户完成首次支付签约** + period_extend-订阅续费成功,周期性自动扣款成功 + item_update-订阅项目升级成功 + item_downgrade订阅项目降级成功 + cancel-订阅已取消,用户取消订阅或到期未续费 + cancel_at_period_end-订阅将在周期结束取消 + item_cancel_revert-订阅取消后恢复 | | **change_date** | **订阅变更时间** | String | 否 | (32) | 2026-03-22 21:00:00 | 订阅变更时间 | | **trade_no** | **交易号** | String | 否 | (64) | 2026022276001434360514767918 | 支付宝交易号,可根据该交易号调用支付宝交易查询接口(alipay.trade.query)进行支付明细查询 | | **order_no** | **订阅支付单ID** | String | 否 | (64) | 2026042019600065895 | 创建/升级订阅时生成的支付请求单号 | | **pay_amount** | **支付金额** | String | 否 | (16) | 1001 | 当笔订阅的支付金额,单位:分 | | **subscription** | **订阅信息** | String | 否 | (20000) | - | 订阅信息大对象,参考alipay.trade.subscription.query | **通知示例** ```json { "msgApi": "alipay.trade.subscription.changed", "msgOwnerId": null, "bizId": "2026042610000000001", "producerId": "subscribecore", "producerType": "ANT_APP", "consumerId": "2021006141630090", "consumerType": "OPEN_APP", "content": { "order_no": "2026042610000000001", "change_date": "2026-04-26 19:07:38", "pay_amount": 5900, "trade_no": "2026042622001443631123456789", "change_type": "active", "subscription": { "subscription_id": "2026042600000000001", "created": "2026-04-26 19:07:38", "subscription_status": "ACTIVE", "customer_id": "202604260034123456789", "current_period_start": "2026-04-26 19:07:38", "current_period_end": "2026-05-26 23:59:59", "start_date": "2026-04-26 19:07:38", "items": [ { "item_id": "2026042600000000001", "quantity": 1, "created": "2026-04-26 19:07:38", "price": { "id": "202603280020000000001", "product_id": "202603280010000000001", "unit_amount": "10900", "type": "recurring", "active": true, "gmt_create": "2026-03-28 14:54:55", "metadata": "{}", "recurring": { "interval": "MONTH", "interval_count": 1, "usage_type": "licensed" }, "product": { "id": "202603280010000000001", "name": "基础套餐", "description": "性价比高", "active": true, "gmt_create": "2026-03-28 14:54:55", "default_price_id": "202603280020000000001", "metadata": "{\"product_level\":\"2\",\"product_type\":\"2\",\"product_send_score_month\":\"23000\",\"product_label\":\"basic\",\"product_tag\":\"autoclaw\",\"product_order\":\"11\",\"product_price\":\" 10900\",\"product_send_score_day\":\"100\",\"product_send_score_forever\":\"0\",\"product_month_count\":\"1\",\"status\":\"0\",\"product_first_month_discount_price\":\"5900\"}" } } } ] } } } ``` **通知应答** | **响应报文** | **描述** | **是否重试** | **是否区分大小写** | | :--- | :--- | :--- | :--- | | **success** | 消息处理成功 | 否 | 否 | | **fail** | 消息处理失败 | 是 | 否 | **说明:** NOTIFY_URL是开发者在开放平台控制台上设置的应用网关地址 ##### 查询订阅 商家通过订阅 [alipay.trade.subscription.query(订阅查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-query.md)来查询具体的订阅相关信息 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **customer_id** | **支付宝客户id** | String | 是 | [1,64] | 202603210030100000003 | 支付宝客户id | | **subscription_status** | **订阅状态** | String | 否 | [0,64] | ACTIVE | 订阅状态,枚举值:INCOMPLETE(未完成支付)、ACTIVE(活跃)、CANCELED(已取消) | | **subscription_id** | **订阅id** | String | 否 | [0,64] | 20260320123156789 | 订阅id | **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_status":"ACTIVE", "subscription_id":"20260320123156789", "customer_id":"202603210030100000003" }' ``` **响应参数说明** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **subscriptions** | **订阅详情信息** | Array | 订阅详情信息列表 | | **┗ subscription_id** | **订阅id** | String | 订阅id | | **┗ customer_id** | **支付宝客户id** | String | 支付宝客户id | | **┗ subscribe_title** | **订阅标题** | String | 订阅标题 | | **┗ subscription_status** | **订阅状态** | String | 订阅状态,例如INCOMPLETE(未完成)、ACTIVE(活跃)、CANCELED(已取消)等 | | **┗ current_period_start** | **最近一个扣款周期开始时间** | String | 最近一个扣款周期开始时间 | | **┗ current_period_end** | **最近一个扣款周期结束时间** | String | 最近一个扣款周期结束时间 | | **┗ cancel_at_period_end** | **周期结束是否失效** | Boolean | true-周期结束状态生效,false-周期结束依旧生效 | | **┗ start_date** | **订阅开始日期** | String | 订阅开始日期 | | **┗ canceled_date** | **订阅取消时间** | String | 订阅取消时间 | | **┗ created** | **创建时间** | String | 创建时间 | | **┗ metadata** | **订阅元数据** | String | 订阅元数据,订阅创建时传入 | | **┗ items** | **订阅项目信息** | Array | 订阅项目信息列表 | | **┗ pending_items** | **待生效的订阅项** | Array | 待生效的订阅项列表 | | **┗ trial_start** | **试用期开始时间** | String | 试用期开始时间 | | **┗ trial_end** | **试用期结束时间** | String | 试用期结束时间 | #### 订阅续费扣款 当用户订阅的产品到达续费周期后,将自动从用户账户扣款。扣款成功后,支付宝将通过系统消息通知商户继续提供相应产品或服务进行履约。 ```mermaid sequenceDiagram participant 商户 participant 支付宝 支付宝-->>商户: 1: 续费结束后发送订阅续费成功/取消的消息(alipay.trade.subscription.changed) ``` 默认扣款逻辑: + 扣款预通知:在订阅产品到期日前的2天,支付宝会向用户发送扣款预通知,提醒用户即将扣款; + 执行扣款:在订阅产品到期日的前1天,支付宝会对用户进行扣款; + 扣款重试:在订阅产品到期前,支付宝会持续根据算法进行多次扣款,直到扣款成功; + 扣款失败:若订阅产品已到期,支付宝将不再进行扣款,并解约订阅产品。 以下图片仅做线上样式参考,实际页面内容以线上为准。 ![](https://mdn.alipayobjects.com/afts/img/A*7qzTRI3SpM0AAAAAVmAAAAgAeq8wAA/original?bz=openpt_doc&t=CfP9_74k_s2zMo1ktbthxN3K0_Nvy_eY75DZl07ohYIDAAAAZAAAMK8AAAAA) ##### 获取续费结果 商家通过订阅 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅商品的续费结果 **注意:** + 商户获取消息通知后,需要使用支付宝公钥进行验签 + 用户续费成功后,发送的商户消息通知中的 **订阅变更类型(change_type)**为 ****订阅续费成功****(period_extend)** + 到期后仍未扣款成功,发送的商户消息通知中的 **订阅变更类型(change_type)**为 订阅已取消**(cancel) **通知示例** ```json { "msgApi": "alipay.trade.subscription.changed", "msgOwnerId": null, "content": { "order_no": "2026042610000000000", "change_date": "2026-05-25 07:02:06", "pay_amount": 10900, "trade_no": "2026052422001443631123456789", "change_type": "period_extend", "subscription": { "subscription_id": "2026042600000000000", "created": "2026-04-26 19:07:38", "subscription_status": "ACTIVE", "customer_id": "202604260034123456789", "current_period_start": "2026-05-26 23:59:59", "current_period_end": "2026-06-26 23:59:59", "start_date": "2026-04-26 19:47:07", "items": [ { "item_id": "2026042600000000000", "quantity": 1, "created": "2026-04-26 19:07:38", "price": { "id": "202603280020000000000", "product_id": "202603280010000000000", "unit_amount": "10900", "type": "recurring", "active": true, "gmt_create": "2026-03-28 14:54:55", "metadata": "{}", "recurring": { "interval": "MONTH", "interval_count": 1, "usage_type": "licensed" }, "product": { "id": "202603280010000000000", "name": "订阅套餐", "description": "性价比高", "active": true, "gmt_create": "2026-03-28 14:54:55", "default_price_id": "202603280020000000000", "metadata": "{\"product_level\":\"2\",\"product_type\":\"2\",\"product_send_score_month\":\"23000\",\"product_label\":\"basic\",\"product_tag\":\"xxx\",\"product_order\":\"11\",\"product_price\":\"10900 \",\"product_send_score_day\":\"100\",\"product_send_score_forever\":\"0\",\"product_month_count\":\"1\",\"status\":\"0\",\"product_first_month_discount_price\":\"8800\"}" } } } ] } } } ``` #### 订阅升级 当用户需要将现有订阅产品进行升级,支付宝会根据提前约定的方式自动计算价格,用户可通过支付宝扫码进行变更信息的确认,完成支付并更新订阅产品信息。 + 补差价计算规则,支持多种方式: - 按照「会员使用时间」进行价格抵扣的计算 - 商户自主计算价格,通过接口传递给支付宝进行扣款 + 升级方式,也支持多种方式: - 重新计算周期,现有套餐的残值抵扣新周期的支付金额 - 维持原周期不变,仅支付剩余周期的差价 以下图片仅做线上样式参考,实际页面内容以线上为准。 ![](https://mdn.alipayobjects.com/afts/img/A*r2rfQoS-kTcAAAAAVXAAAAgAeq8wAA/original?bz=openpt_doc&t=jfZDHS5qiW2lkeRvWIEoR3tIQxNxPFbEw-p4rs-SrsEDAAAAZAAAMK8AAAAA) 商家可按如下指引调用接口,进行**订阅升级**并**感知升级结果** ```mermaid sequenceDiagram participant 用户 participant 商户 participant 支付宝 用户->>商户: 1: 发起升级 商户->>支付宝: 1.1: 订阅修改(alipay.trade.subscription.modify) 支付宝->>支付宝: 1.1.1: 差价计算,计算用户需要实际支付的金额 支付宝-->>商户: 1.1.2: 返回订阅id以及升级的支付链接 商户->>商户: 1.2: 消费支付链接,如果是网页版,展示支付二维码 商户-->>用户: 1.3: 二维码展示 商户->>支付宝: 1.4: 消费支付链接,如果是app端,则唤起支付宝,与二维码选其一对客 支付宝-->>商户: 1.5: 支付完成后发送订阅更新结果消息(alipay.trade.subscription.changed) ``` ##### 发起订阅升级 商家可通过订阅修改接口 [alipay.trade.subscription.modify(订阅修改接口)](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md) 实现订阅升级功能,引导用户升级到更高级的订阅方案 **注意:** + 订阅升级需要用户确认并完成支付,因此会返回支付宝跳转链接供用户确认 + 升级类型通过 `modify_type` 参数设置为 `UPGRADE` + 可以通过 `preserve_billing_cycle` 参数控制是否保持计费周期不变 + 可以通过 `pay_amount` 参数自定义升级支付金额,如不传则系统自动计算 **订阅升级参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 是 | [1,64] | 20260320123156789 | 需要升级的订阅id | | **modify_type** | **更新类型** | String | 否 | [1,64] | UPGRADE | 固定设置为 `UPGRADE`,表示订阅升级操作。如不传默认为UPGRADE | | **preserve_billing_cycle** | **是否保持计费周期不变** | Boolean | 否 | - | true | 是否保持计费周期不变。`true` - 保持原周期,升级后按原周期计算差价;`false` - 重置周期,升级后按完整新周期计算 | | **pay_amount** | **支付金额** | Number | 否 | [0,1000000000] | 100 | 升级支付金额,单位:分。用于商户自定义升级费用,如不传则系统自动计算升级差价 | | **items** | **订阅项目信息** | Array | 否 | [0,100] | - | 升级后的订阅项目信息 | | **┗ item_id** | **订阅项id** | String | 否 | - | 2026032012314 | 订阅项id | | **┗ price_id** | **价格id** | String | 否 | - | 202603201234567889 | 价格创建接口(alipay.trade.price.create)返回的价格id,代表本次操作的目标价格信息 | | **┗ coupon_id** | **优惠id** | String | 否 | - | 9WJ36SEC | 营销创建接口(alipay.trade.promotion.coupon.create)返回的优惠id,升级时可使用优惠券抵扣 | 注意:其它参数若有传参需要,请与支付宝技术支持沟通确认 **订阅升级请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"UPGRADE", "preserve_billing_cycle":true, "pay_amount":100, "items":[ { "item_id":"2026032012314", "price_id":"202603201234567889", "coupon_id":"9WJ36SEC" } ] }' ``` **订阅升级响应参数** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 订阅id | | **order_no** | **订阅支付单ID** | String | 升级订单的支付单ID | | **pay_amount** | **支付金额** | Number | 实际支付金额,单位:分 | | **alipay_jump_schema** | **支付宝长链跳端schema** | String | 长链,适用于跳转拉起支付宝客户端,用户需通过此链接确认升级并完成支付 | | **alipay_schema** | **支付宝跳转的schema** | String | 短链,适用于生成二维码,用户扫码确认升级并完成支付 | | **promotion_info** | **优惠券信息** | String | 使用的优惠券信息,包含优惠金额等 | **使用支付链接** 升级请求成功后,会返回支付链接: 1. **长链跳转(推荐)**: ```javascript window.location.href = response.alipay_jump_schema; ``` 2. **短链二维码**: ```javascript // 使用短链生成二维码 QRCode.toDataURL(response.alipay_schema, function(error, url) { document.getElementById('qrcode').src = url; }); ``` **升级场景示例** **场景1:基础版升级到高级版,保持计费周期** ```json { "subscription_id":"20260320123156789", "modify_type":"UPGRADE", "preserve_billing_cycle":true, "items":[ { "item_id":"2026032012314", "price_id":"202603201234567889" } ], "description":"升级到高级版" } ``` **场景2:自定义升级费用,不含优惠券** ```json { "subscription_id":"20260320123156789", "modify_type":"UPGRADE", "pay_amount":500, "preserve_billing_cycle":false, "items":[ { "item_id":"2026032012314", "price_id":"202603201234567889" } ], "description":"自定义升级费用5元" } ``` **场景3:使用优惠券升级** ```json { "subscription_id":"20260320123156789", "modify_type":"UPGRADE", "preserve_billing_cycle":true, "items":[ { "item_id":"2026032012314", "price_id":"202603201234567889", "coupon_id":"9WJ36SEC" } ] } ``` **注意事项** 1. **支付确认**:升级操作需要用户在支付宝端确认支付,请务必引导用户完成支付流程 2. **周期控制**:`preserve_billing_cycle` 参数影响计费周期,请根据业务需求选择合适的值 3. **金额计算**:如果不传 `pay_amount`,系统会自动计算升级差价 4. **优惠使用**:升级时可以使用商户配置的优惠抵扣部分费用 5. **结果通知**:升级完成后,支付宝会通过订阅变更通知接口推送结果,请及时处理 ##### 升级结果通知 支付宝通过订阅变更通知接口 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)向商户发送订阅升级结果通知,商户需接收并处理升级结果 **注意:** + 升级结果通知是支付宝主动推送到商户应用网关的异步通知 + 商户需在开放平台配置应用网关地址(NOTIFY_URL) + 商户收到通知后需返回 `success` 表示处理成功,否则返回 `fail` + 投递重试策略:25小时内完成8次通知,间隔频率为:2m、10m、10m、1h、2h、6h、15h **升级通知参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **change_type** | **订阅变更类型** | String | 是 | (32) | item_update | 订阅升级的类型,升级场景为 `item_update` | | **change_date** | **订阅变更时间** | String | 否 | (32) | 2026-03-22 21:00:00 | 升级完成时间 | | **trade_no** | **交易号** | String | 否 | (64) | 2026022276001434360514767918 | 升级支付的交易号,可根据该交易号调用支付宝交易查询接口查询详情 | | **order_no** | **订阅支付单ID** | String | 否 | (64) | 2026042019600065895 | 升级订单的支付单ID | | **pay_amount** | **支付金额** | String | 否 | (16) | 1001 | 升级支付金额,单位:分 | | **subscription** | **订阅信息** | String | 否 | (20000) | - | 升级后的完整订阅信息JSON对象,包含订阅ID、状态、订阅项目等 | **升级通知示例** ```json { "msgApi": "alipay.trade.subscription.changed", "msgOwnerId": null, "bizId": "2026042610000000000", "producerId": "subscribecore", "producerType": "ANT_APP", "consumerId": "2021006141630090", "consumerType": "OPEN_APP", "content": { "order_no": "2026042610000000000", "change_date": "2026-05-25 07:02:06", "pay_amount": 10900, "trade_no": "2026052422001443631123456789", "change_type": "item_update", "subscription": { "subscription_id": "2026042600000000000", "created": "2026-04-26 19:07:38", "subscription_status": "ACTIVE", "customer_id": "202604260034123456789", "current_period_start": "2026-04-26 19:07:38", "current_period_end": "2026-05-26 23:59:59", "start_date": "2026-04-26 19:07:38", "items": [ { "item_id": "2026042600000000000", "quantity": 1, "created": "2026-04-26 19:07:38", "price": { "id": "202603280020000000000", "product_id": "202603280010000000000", "unit_amount": "10900", "type": "recurring", "active": true, "gmt_create": "2026-03-28 14:54:55", "metadata": "{}", "recurring": { "interval": "MONTH", "interval_count": 1, "usage_type": "licensed" }, "product": { "id": "202603280010000000000", "name": "高级套餐", "description": "升级后的高级套餐,包含更多权益", "active": true, "gmt_create": "2026-03-28 14:54:55", "default_price_id": "202603280020000000000", "metadata": "{\"product_level\":\"3\",\"product_type\":\"2\",\"product_send_score_month\":\"50000\",\"product_label\":\"premium\",\"product_tag\":\"upgrade\",\"product_order\":\"20\",\"product_price\":\ "10900\",\"product_send_score_day\":\"200\",\"product_send_score_forever\":\"0\",\"product_month_count\":\"1\",\"status\":\"0\",\"product_first_month_discount_price\":\"8800\"}" } } } ] } } } ``` **subscription对象说明** 升级通知中的 `subscription` 字段包含完整的订阅信息: | **参数** | **名称** | **类型** | **描述** | | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 订阅id | | **customer_id** | **支付宝客户id** | String | 支付宝客户id | | **subscribe_title** | **订阅标题** | String | 升级后的订阅标题 | | **subscription_status** | **订阅状态** | String | 升级后的订阅状态,通常为 `ACTIVE` | | **current_period_start** | **当前周期开始时间** | String | 升级后的计费周期开始时间 | | **current_period_end** | **当前周期结束时间** | String | 升级后的计费周期结束时间 | | **cancel_at_period_end** | **周期结束是否失效** | Boolean | 升级后是否在周期结束时失效 | | **start_date** | **订阅开始日期** | String | 订阅开始日期 | | **created** | **创建时间** | String | 订阅创建时间 | | **metadata** | **订阅元数据** | String | 订阅元数据 | | **items** | **订阅项目信息** | Array | 升级后的订阅项目信息列表 | **通知应答规范** | **响应内容** | **含义** | **支付宝行为** | | :--- | :--- | :--- | | **success** | 处理成功 | 停止投递通知 | | **fail** | 处理失败 | 按照重试策略继续投递 | | **其他** | 未知状态 | 按照重试策略继续投递 | | **无响应/超时** | 处理失败 | 按照重试策略继续投递 | #### 订阅降级 当用户需要将现有订阅产品进行降级,支付宝会根据提前约定的方式自动计算价格,用户可通过支付宝扫码进行变更信息的确认,确认后将更新订阅产品信息。 + 在降级方式上,仅支持一种方式: - 用户的降级在下一周期生效,本周期权益持续用完 以下图片仅做线上样式参考,实际页面内容以线上为准。 ![](https://mdn.alipayobjects.com/afts/img/A*XH8XQ45qyzMAAAAAS8AAAAgAeq8wAA/original?bz=openpt_doc&t=ZsesCFfYA5DrQOV25_PCYpDZWv61MJ5Xl_JQLtkjrIoDAAAAZAAAMK8AAAAA) 商家可按如下指引调用接口,进行**订阅降级**并**感知降级结果** ```mermaid sequenceDiagram participant 用户 participant 商户 participant 支付宝 用户->>商户: 1: 发起降级 商户->>支付宝: 1.1: 订阅修改(alipay.trade.subscription.modify) 支付宝-->>商户: 1.2: 返回订阅id以及降级的链接 商户->>商户: 1.3: 消费降级链接,如果是网页版,展示支付二维码 商户-->>用户: 1.4: 二维码展示 商户->>支付宝: 1.5: 消费降级链接,如果是app端,则唤起支付宝,与二维码选其一对客 支付宝-->>商户: 1.6: 降级完成后发送订阅更新结果消息(alipay.trade.subscription.changed) ``` ##### 发起订阅降级 商家可通过订阅修改接口 [alipay.trade.subscription.modify(订阅修改接口)](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md) 实现订阅降级功能,引导用户降级到低级别的订阅方案,并接收降级结果通知 **注意:** + 订阅降级需要用户确认,因此会返回支付宝跳转链接供用户确认 + 当前降级的模式为:当前订阅仍将使用到周期结束,本周期结束时,若对降级后的价格扣款成功,则降级后的订阅开始生效 + 降级类型通过 `modify_type` 参数设置为 `DOWNGRADE` + 降级结果将通过订阅变更通知接口推送给商户 **降级参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 是 | [1,64] | 20260320123156789 | 需要降级的订阅id | | **modify_type** | **更新类型** | String | 是 | [1,64] | DOWNGRADE | 固定设置为 `DOWNGRADE`,表示订阅降级操作 | | **cancel_at_period_end** | **是否在当前周期结束时降级** | Boolean | 是 | - | true | 降级场景设置为 `true`,在当前计费周期结束时降级 | | **items** | **订阅项目信息** | Array | 否 | [0,100] | - | 需要降级的订阅项目信息 | | **┗ item_id** | **订阅项id** | String | 否 | - | 2026032012314 | 原生效订阅项id | | **┗ price_id** | **价格id** | String | 否 | - | 202603201234567889 | 降级后的目标价格id | **降级请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"DOWNGRADE", "cancel_at_period_end":true, "items":[ { "item_id":"2026032012315", "price_id":"202603201234567890" } ] }' ``` **降级响应参数** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 订阅id | | **alipay_jump_schema** | **支付宝长链跳端schema** | String | 长链,适用于跳转拉起支付宝客户端,用户需通过此链接确认降级 | | **alipay_schema** | **支付宝跳转的schema** | String | 短链,适用于生成二维码,用户扫码确认降级 | **响应示例** ```json { "alipay_trade_subscription_modify_response": { "code": "10000", "msg": "Success", "subscription_id": "20260320123156789", "alipay_jump_schema": "https://render.alipay.com/XXXXXXXXXX", "alipay_schema": "https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ##### 降级结果通知 支付宝通过订阅变更通知接口 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md) 向商户发送订阅降级结果通知 **注意:** + 降级结果通知的 `change_type` 为 `item_downgrade` + 商户需在开放平台配置应用网关地址(NOTIFY_URL) + 商户收到通知后需返回 `success`,否则支付宝会重试通知 **降级通知参数** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **change_type** | **订阅变更类型** | String | 是 | (32) | item_update | `item_downgrade` | | **change_date** | **订阅变更时间** | String | 否 | (32) | 2026-03-22 21:00:00 | 降级完成时间 | | **subscription** | **订阅信息** | String | 否 | (20000) | - | 降级后的完整订阅信息JSON对象 | 注意:其它参数若有传参需要,请与支付宝技术支持沟通确认 **降级通知示例** ```json { "msgApi": "alipay.trade.subscription.changed", "msgOwnerId": null, "bizId": "2026042600000000002", "producerId": "subscribecore", "producerType": "ANT_APP", "consumerId": "2021006141630090", "consumerType": "OPEN_APP", "content": { "change_date": "2026-05-10 15:30:00", "change_type": "item_downgrade", "subscription": { "subscription_id": "2026042600000000001", "created": "2026-04-26 19:07:38", "subscription_status": "ACTIVE", "customer_id": "202604260034123456789", "current_period_start": "2026-04-26 19:07:38", "current_period_end": "2026-05-26 23:59:59", "start_date": "2026-04-26 19:07:38", "items": [ { "item_id": "2026042600000000002", "quantity": 1, "created": "2026-05-10 15:30:00", "price": { "id": "202603280020000000002", "product_id": "202603280010000000002", "unit_amount": "4900", "type": "recurring", "active": true, "gmt_create": "2026-03-28 14:54:55", "metadata": "{}", "recurring": { "interval": "MONTH", "interval_count": 1, "usage_type": "licensed" }, "product": { "id": "202603280010000000002", "name": "入门套餐", "description": "适合轻度使用用户,基础功能满足日常需求", "active": true, "gmt_create": "2026-03-28 14:54:55", "default_price_id": "202603280020000000002", "metadata": "{\"product_level\":\"1\",\"product_type\":\"2\",\"product_send_score_month\":\"10000\",\"product_label\":\"starter\",\"product_tag\":\"downgrade\",\"product_order\":\"5\",\"product_price\": \"4900\",\"product_send_score_day\":\"50\",\"product_send_score_forever\":\"0\",\"product_month_count\":\"1\",\"status\":\"0\",\"product_first_month_discount_price\":\"2900\"}" } } } ] } } } ``` #### 订阅取消 用户可在支付宝随时取消订阅产品的后续扣款。 同时,也支持用户在商家的页面中操作取消后,商家通过调用API接口来进行主动取消。 ##### 发起订阅取消 商家可通过订阅修改接口 [alipay.trade.subscription.modify(订阅修改接口)](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md) 实现订阅取消和取消后恢复功能,并接收相应的通知 **注意:** + 目前取消类型分为两种: - 周期结束后取消:设置 `cancel_at_period_end=true` - 立即取消:设置 `cancel_at_period_end=false` + 立即取消会触发退款,退款金额可自定义退款金额 或 系统自动计算残值,若商户自定义金额为0,即为为立即取消但不退款 + 取消结果将通过订阅变更通知接口推送给商户 **取消参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 是 | [1,64] | 20260320123156789 | 需要取消的订阅id | | **modify_type** | **更新类型** | String | 是 | [1,64] | CANCEL | 固定设置为 `CANCEL`,表示订阅取消操作 | | **cancel_at_period_end** | **是否在当前周期结束时取消订阅** | Boolean | 是 | - | true | true:表示在当前计费周期结束后取消订阅; false:表示立即取消 | | **refund_amount** | **自定义退款金额** | Number | 否 | [0,1000000000] | 100 | 不传:系统按照时间规则计算残值作为退款金额;自定义传入:按商家指定的金额退款,0表示直接取消不退款 | **取消请求示例** **场景1:立即取消,系统自动计算退款** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"CANCEL", "cancel_at_period_end":false }' ``` **场景2:周期结束时取消,不退款** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"CANCEL", "cancel_at_period_end":true }' ``` **场景3:立即取消,自定义退款金额** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"CANCEL", "cancel_at_period_end":false, "refund_amount":200 }' ``` **场景4:立即取消,不退款** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"CANCEL", "cancel_at_period_end":false, "refund_amount":0 }' ``` **取消响应参数** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 订阅id | | **refund_order_id** | **退款业务单号** | String | 退款业务单号(立即取消时返回) | | **refund_amount** | **退款金额** | Number | 退款金额,单位:分(立即取消时返回) | **响应示例** ```json { "alipay_trade_subscription_modify_response": { "code": "10000", "msg": "Success", "subscription_id": "20260320123156789", "refund_order_id": "2026042019600065895", "refund_amount": 150 }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ##### 订阅取消结果通知 支付宝通过订阅变更通知接口 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md) 向商户发送订阅取消结果通知 **注意:** + 取消结果通知的 `change_type` 为订阅状态变更 + 立即取消的通知会包含退款信息(refund_order_id、refund_amount) + 周期结束取消的通知会设置 `cancel_at_period_end=true` + 商户需在开放平台配置应用网关地址(NOTIFY_URL) + 商户收到通知后需返回 `success`,否则支付宝会重试通知 **取消通知参数** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **change_type** | **订阅变更类型** | String | 是 | (32) | - | 立即取消类型为cancel; 周期结束取消类型为cancel_at_period_end | | **change_date** | **订阅变更时间** | String | 否 | (32) | 2026-03-22 21:00:00 | 取消完成时间 | | **trade_no** | **交易号** | String | 否 | (64) | 2026022276001434360514767918 | 关联的交易号 | | **order_no** | **订阅支付单ID** | String | 否 | (64) | 2026042019600065895 | 取消订单ID | | **subscription** | **订阅信息** | String | 否 | (20000) | - | 取消后的完整订阅信息JSON对象 | **取消通知示例:** + **设置周期末取消** ```json { "msgApi": "alipay.trade.subscription.changed", "msgOwnerId": null, "bizId": "2026042600000000001", "producerId": "subscribecore", "producerType": "ANT_APP", "consumerId": "2021006141630090", "consumerType": "OPEN_APP", "content": { "order_no": "2026042600000000001", "change_date": "2026-05-20 10:15:30", "change_type": "cancel_at_period_end", "subscription": { "subscription_id": "2026042600000000001", "created": "2026-04-26 19:07:38", "subscription_status": "ACTIVE", "customer_id": "202604260034123456789", "current_period_start": "2026-04-26 19:07:38", "current_period_end": "2026-05-26 23:59:59", "start_date": "2026-04-26 19:07:38", "canceled_at": "2026-05-20 10:15:30", "cancel_at_period_end": true, "items": [ { "item_id": "2026042600000000001", "quantity": 1, "created": "2026-04-26 19:07:38", "price": { "id": "202603280020000000001", "product_id": "202603280010000000001", "unit_amount": "10900", "type": "recurring", "active": true, "gmt_create": "2026-03-28 14:54:55", "metadata": "{}", "recurring": { "interval": "MONTH", "interval_count": 1, "usage_type": "licensed" }, "product": { "id": "202603280010000000001", "name": "基础套餐", "description": "适合有稳定使用需求的用户,每日可领取积分,使用更持续,整体性价比更高", "active": true, "gmt_create": "2026-03-28 14:54:55", "default_price_id": "202603280020000000001", "metadata": "{\"product_level\":\"2\",\"product_type\":\"2\",\"product_send_score_month\":\"23000\",\"product_label\":\"basic\",\"product_tag\":\"autoclaw\",\"product_order\":\"11\",\"product_price\":\" 10900\",\"product_send_score_day\":\"100\",\"product_send_score_forever\":\"0\",\"product_month_count\":\"1\",\"status\":\"0\",\"product_first_month_discount_price\":\"5900\"}" } } } ] } } } ``` + **立即取消/周期结束时实际取消** ```json { "msgApi": "alipay.trade.subscription.changed", "msgOwnerId": null, "bizId": "2026042600000000001", "producerId": "subscribecore", "producerType": "ANT_APP", "consumerId": "2021006141630090", "consumerType": "OPEN_APP", "content": { "order_no": "2026042600000000001", "change_date": "2026-05-10 14:30:00", "change_type": "cancel", "refund_amount": 8500, "refund_trade_no": "2026051022001443639876543210", "subscription": { "subscription_id": "2026042600000000001", "created": "2026-04-26 19:07:38", "subscription_status": "CANCELED", "customer_id": "202604260034123456789", "current_period_start": "2026-05-01 00:00:00", "current_period_end": "2026-05-26 23:59:59", "start_date": "2026-04-26 19:07:38", "canceled_at": "2026-05-10 14:30:00", "ended_at": "2026-05-10 14:30:00", "items": [ { "item_id": "2026042600000000001", "quantity": 1, "created": "2026-04-26 19:07:38", "price": { "id": "202603280020000000001", "product_id": "202603280010000000001", "unit_amount": "10900", "type": "recurring", "active": true, "gmt_create": "2026-03-28 14:54:55", "metadata": "{}", "recurring": { "interval": "MONTH", "interval_count": 1, "usage_type": "licensed" }, "product": { "id": "202603280010000000001", "name": "基础套餐", "description": "性价比高", "active": true, "gmt_create": "2026-03-28 14:54:55", "default_price_id": "202603280020000000001", "metadata": "{\"product_level\":\"2\",\"product_type\":\"2\",\"product_send_score_month\":\"23000\",\"product_label\":\"basic\",\"product_tag\":\"autoclaw\",\"product_order\":\"11\",\"product_price\":\" 10900\",\"product_send_score_day\":\"100\",\"product_send_score_forever\":\"0\",\"product_month_count\":\"1\",\"status\":\"0\",\"product_first_month_discount_price\":\"5900\"}" } } } ] } } } ``` ##### 取消后恢复 适用于下周期生效的取消方式,如果用户操作取消,但在周期结束前想恢复订阅,可以使用取消后恢复功能 **恢复参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 是 | [1,64] | 20260320123156789 | 需要恢复的订阅id | | **modify_type** | **更新类型** | String | 是 | [1,64] | REVERT_CANCEL | 固定设置为 `REVERT_CANCEL`,表示取消后恢复操作 | | **cancel_at_period_end** | **是否在当前周期结束时取消订阅** | Boolean | 是 | - | false | false:表示操作恢复 | **恢复请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"REVERT_CANCEL" }' ``` **恢复响应参数** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 订阅id | | **alipay_jump_schema** | **支付宝长链跳端schema** | String | 长链,适用于跳转拉起支付宝客户端,用户需通过此链接确认恢复 | | **alipay_schema** | **支付宝跳转的schema** | String | 短链,适用于生成二维码,用户扫码确认恢复 | **恢复结果通知** 恢复成功后,支付宝会发送订阅变更通知: + `subscription_status` 会变为 `ACTIVE` + `cancel_at_period_end` 会变为 `false` + `canceled_date` 会被清除 **恢复通知示例** ```json { "msgApi": "alipay.trade.subscription.changed", "msgOwnerId": null, "bizId": "2026042600000000001", "producerId": "subscribecore", "producerType": "ANT_APP", "consumerId": "2021006141630090", "consumerType": "OPEN_APP", "content": { "order_no": "2026042600000000001", "change_date": "2026-05-22 16:45:00", "pay_amount": 10900, "trade_no": "2026052222001443631123456789", "change_type": "item_cancel_revert", "subscription": { "subscription_id": "2026042600000000001", "created": "2026-04-26 19:07:38", "subscription_status": "ACTIVE", "customer_id": "202604260034123456789", "current_period_start": "2026-04-26 19:07:38", "current_period_end": "2026-05-26 23:59:59", "start_date": "2026-04-26 19:07:38", "canceled_at": null, "cancel_at_period_end": false, "items": [ { "item_id": "2026042600000000001", "quantity": 1, "created": "2026-04-26 19:07:38", "price": { "id": "202603280020000000001", "product_id": "202603280010000000001", "unit_amount": "10900", "type": "recurring", "active": true, "gmt_create": "2026-03-28 14:54:55", "metadata": "{}", "recurring": { "interval": "MONTH", "interval_count": 1, "usage_type": "licensed" }, "product": { "id": "202603280010000000001", "name": "基础套餐", "description": "性价比高", "active": true, "gmt_create": "2026-03-28 14:54:55", "default_price_id": "202603280020000000001", "metadata": "{\"product_level\":\"2\",\"product_type\":\"2\",\"product_send_score_month\":\"23000\",\"product_label\":\"basic\",\"product_tag\":\"autoclaw\",\"product_order\":\"11\",\"product_price\":\" 10900\",\"product_send_score_day\":\"100\",\"product_send_score_forever\":\"0\",\"product_month_count\":\"1\",\"status\":\"0\",\"product_first_month_discount_price\":\"5900\"}" } } } ] } } } ``` --- ### 团体席位订阅 目录路径:Token Pay · AI 连续订阅 > 接入指南 > 团体席位订阅 来源:https://aipay.alipay.com/docs/subscribe/integration-guide/group-seat.md #### 产品特色 团体订阅能力是支付宝专为企业或团体用户订阅模型服务提供的解决方案,支持团体用户购买同一订阅套餐的多个席位。 团体用户在购买订阅产品时,需设置席位数量后通过授权将商户账号和用户支付宝账号进行绑定,借助支付宝账号资金渠道,直接帮助商家完成周期性的自动扣款。后续可将订阅套餐的席位数量进行增减,支付宝侧会同步计算相应差价或设定下周期生效。 ![](https://mdn.alipayobjects.com/afts/img/A*mkd6T4XDf9kAAAAAVlAAAAgAeq8wAA/original?bz=openpt_doc&t=mbjW54E1SMZMs7ELzNr8HXZXXl_HUCm-TgFaMD5_Su8DAAAAZAAAMK8AAAAA) #### 订阅商品与价格管理 提供商品价格管理后台,商家可直接登录支付宝商家平台进行可视化配置,维护自己的商品和服务信息,并关联多种计价模式、设置默认价格等。 支付宝提供商品价格增删改查的全套API接口,支持商家直接调用。此外,支持商家进通过简单配置,通过低代码接入自动生成的商品展示页面与收银台页面。 ![](https://mdn.alipayobjects.com/afts/img/A*2bOoTqxw19kAAAAAVjAAAAgAeq8wAA/original?bz=openpt_doc&t=ZWjuePwJuIByhBMe0OyGk0NL2jtpghW9iksRnnlAy3oDAAAAZAAAMK8AAAAA) 商家可按如下指引调用接口,进行商品管理、价格管理 等操作。 ```mermaid sequenceDiagram participant 商户 participant 支付宝 商户->>支付宝: 1: 管理后台/api创建商品信息(alipay.trade.product.create) 支付宝-->>商户: 1.1: 返回商品id 商户->>支付宝: 2: 管理后台/api创建商户下的价格信息(alipay.trade.price.create),该接口具备同时创建新商品 支付宝-->>商户: 2.1: 返回价格id 商户->>支付宝: 3: 管理后台/api设置商品下默认金额(alipay.trade.product.modify) 支付宝-->>商户: 3.1: 返回设置结果 ``` ##### 商品创建 商家可调用 [alipay.trade.product.create(商品创建接口)](https://opendocs.alipay.com/solution/615bfd8c_alipay.trade.product.create.md),获取 商品id(product_id)。 注意: + 商品名称(name)后续将在用户的签约页面进行展示,请务必保证名称的准确 + 单位别名(unit_label)在团体席位订阅场景下该字段必传,后续在用户的签约页面进行展示,请务必保证名称的准确。 + 商品模型元数据(metadata)支持商户进行自定义传参,用于记录商户需要消费的个性信息。 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | name | 商品名称 | String | 是 | [1,255] | Gold 会员 | 商品名称 | | description | 商品描述 | String | 是 | [1,255] | 基础权益 | 商品描述 | | metadata | 商品模型元数据 | String | 否 | [1,2000] | {"key":"value"} | 商户需要保存在商品模型中的元数据 | | unit_label | 单位别名 | String | 是 | [1,100] | 席位 | 单位别名 | 请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "name":"Gold 会员", "description":"基础权益", "metadata":"{\"key\":\"value\"}", "unit_label":"席位" }' ``` ##### 修改商品 商家可调用 [alipay.trade.product.modify(商品修改接口)](https://opendocs.alipay.com/solution/26d7e027_alipay.trade.product.modify.md),修改商品或设置商品的默认价格(price_id)。 注意:每个商品仅能配置一个价格为默认价格。 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | product_id | 商品id | String | 是 | [1,32] | 20260324001001 | 本次更新的商品id,商品创建接口(alipay.trade.product.create)返回的商品id。 | | name | 商品名称 | String | 否 | [1,255] | Gold 会员 | 商品名称 | | description | 商品描述 | String | 否 | [1,255] | 基础权益 | 商品描述 | | default_price_id | 默认价格id | String | 否 | [1,32] | 20260324001001 | 该商品默认价格id | | metadata | 商品元数据 | String | 否 | [1,1024] | {"key":"value"} | 商品元数据 | 请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "product_id":"20260324001001", "name":"Gold 会员", "description":"基础权益", "default_price_id":"20260324001001", "metadata":"{\"key\":\"value\"}" }' ``` ##### 商品查询 商家可调用 [alipay.trade.product.query(商品查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/product-query.md),查询已创建的商品信息。 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | product_id | 商品id | String | 是 | [1,32] | 202603230010000006783 | 商品创建接口(alipay.trade.product.create)返回的商品id。 | | query_options | 查询选项 | array | 否 | [1,10] | ["price"] | 查询选项,商户通过上送该参数来定制额外返回的信息字段,数组格式。枚举支持:price(默认价格信息) | 请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "product_id":"202603230010000006783", "query_options":[ "price" ] }' ``` ##### 价格创建 商家可调用 [alipay.trade.price.create(价格创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/price-create.md)创建价格信息,获取价格实例id(price_id)。 注意: + 循环计价模型(recurring):订阅类商品(含团体席位订阅商品),必传。 - 计价周期单位(interval):与 interval_count组合使用,支持枚举值为 DAY和MONTH,分别代表周期的单位为「天」或「月」。 - 计价周期间隔(interval_count):计价周期间隔,和 interval 组合使用。例如 interval 为 MONTH,interval_count = 1,则扣款周期为 1 月:系统以首次购买日期为周期起始日,下一周期起始日按设定间隔顺延,若目标日期不存在则自动调整至当月最后一天。例如首次购买日为1月31日,则下一周期起始日为2月28日(或29日),再下一周期起始日恢复为3月31日。实际扣款将在周期起始日前1天发起,确保资金及时到账,服务无缝续期。 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | product_id | 商品id | String | 是 | [1,32] | 202603230010000006783 | 商品创建接口(alipay.trade.product.create)返回的商品id。 | | unit_amount | 单位金额 | Number | 是 | [1,1000000000] | 1000 | 单位金额,单位:分 | | recurring | 循环计价模型 | Object | 是 | - | - | 循环计价配置,用于订阅等场景 | | ┗ interval | 计价周期单位 | String | 是 | [1,32] | MONTH | 计价周期单位,和interval_count组合使用。枚举值:MONTH(月)、DAY(日) | | ┗ interval_count | 计价周期间隔 | Number | 是 | [1,10000] | 1 | 计价周期间隔,和interval组合使用 | | metadata | 价格信息元数据 | String | 否 | [1,2000] | {"key":"value"} | 商户需要保存在价格模型中的元数据 | 请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "unit_amount":1000, "product_id":"202603230010000006783", "recurring":{ "interval_count":1, "interval":"MONTH" }, "metadata":"{\"key\":\"value\"}" }' ``` ##### 价格查询 商家可调用 [alipay.trade.price.query(价格查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/price-query.md),查询已创建的价格信息 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | price_id | 价格id | String | 是 | [1,32] | 202603240020000001001 | 价格id,价格创建接口(alipay.trade.price.create)返回的价格id。 | | query_options | 查询选项 | array | 否 | [1,10] | ["product"] | 查询选项,商户通过上送该参数来定制额外返回的信息字段,数组格式。枚举支持:product(商品信息) | 请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "price_id":"202603240020000001001", "query_options":[ "product" ] }' ``` #### 订阅商品首次购买 企业用户挑选商品、明确席位数量进行购买,商家将用户购买的商品传给支付宝,将自动生成付款链接或二维码,用户可直跳转至支付宝APP或扫码唤起支付宝APP进行产品订阅的信息确认,完成订阅和支付。 ![](https://mdn.alipayobjects.com/afts/img/A*MkApRKes_VgAAAAAUvAAAAgAeq8wAA/original?bz=openpt_doc&t=7WF2bpw3YEzjfHP6gZI3dbbUC4UVmwQ9z8AiXYBksSADAAAAZAAAMK8AAAAA) 商家可按如下指引调用接口,进行客户创建、发起团体席位订阅、获取团体席位订阅消息通知 等操作。 ```mermaid sequenceDiagram participant 用户 participant 商户 participant 支付宝 用户->>商户: 1: 发起订阅 商户->>支付宝: 1.1: 若未创建过,则先调用api创建客户(alipay.trade.customer.create) 支付宝-->>商户: 1.2: 返回支付宝侧客户id 商户->>支付宝: 1.3: 创建订阅(alipay.trade.subscription.create) 支付宝-->>商户: 1.4: 返回订阅id以及支付链接 商户->>商户: 1.5: 消费支付链接,如果是网页版,展示支付二维码 商户-->>用户: 1.6: 二维码展示 商户->>支付宝: 1.7: 消费支付链接,如果是app端,则唤起支付宝,与二维码选其一对客 用户->>支付宝: 2: 二维码场景:用户扫码进行支付;app端:唤起支付宝进行支付 支付宝-->>商户: 2.1: 支付完成发送订阅生效消息(alipay.trade.subscription.changed) ``` ##### 创建客户 商家可调用 [alipay.trade.customer.create(客户创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/customer-create.md)创建客户,获取客户id(customer_id),后续与支付宝侧交互时用户身份使用该customer_id进行用户标识。 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | name | 客户名称 | String | 是 | [1,64] | 张三 | 客户名称 | | description | 客户描述 | String | 否 | [1,255] | 业务客户 | 客户描述 | | phone | 客户手机号 | String | 否 | [1,50] | 15011112222 | 客户手机号,和客户邮箱需至少传入1个 | | email | 客户邮箱 | String | 否 | [1,255] | email@antgroup.com | 客户邮箱,和客户手机号需至少传入1个 | 请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.customer.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "name":"张三", "description":"业务客户", "phone":"15011112222", "email":"email@antgroup.com" }' ``` ##### 发起订阅 商家可调用 [alipay.trade.subscription.create(订阅创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-create.md),获取订阅id(subscription_id)和对应的支付链接。 注意: + 发起团体席位订阅时,需要在订阅项目信息(items)中,传入用户所购买的商品对应的价格id(price_id)和团体席位的数量quantity,来确定此次订阅购买的商品单价(单个席位的价格)和数量。 + 发起订阅后商户将获得适用于跳转支付宝端的长链接alipay_jump_schema或适用于生成二维码的短链接alipay_schema,商户可根据实际场景自主选择使用。 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | items | 订阅项目信息 | String | 是 | | | 订阅项目信息。 | | ┗ price_id | 价格id | String | 是 | [1,64] | 202603201234567889 | 价格创建接口(alipay.trade.price.create)返回的价格id,代表本次操作的目标价格信息。 | | ┗ quantity | 数量 | String | 是 | [1,8] | 10 | 购买的团体席位数量。 | | customer_id | 支付宝客户id | String | 是 | [1,64] | 208812345678 | 客户id,客户创建接口(alipay.trade.customer.create)返回的客户id。 | 注意:其它参数若有传参需要,请与支付宝技术支持沟通确认 请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "items":[ { "price_id":"202603201234567889", "quantity":"10" } ], "customer_id":"208812345678" }' ``` ##### 获取订阅消息通知 商家通过订阅 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅商品的购买结果。 注意: + 该接口为支付宝主动向商户发送的消息通知接口,商户需要配置应用网关地址以及订阅消息服务,详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md) + 商户收到消息后需要返回success表示处理成功,否则返回fail,支付宝会进行重试。 + 投递重试策略:25小时内完成8次通知,间隔频率为:2m、10m、10m、1h、2h、6h、15h。 + 商户获取消息通知后,需要使用支付宝公钥进行验签。 + 用户购买成功后,发送的订阅产品商户消息通知中的 订阅变更类型(change_type)为 订阅已生效(active)。 + 生效周期字段:subscription中的current_period_start和current_period_end代表本次订阅支付对应的生效周期的起止时间。 重要参数说明 | 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 | | --- | --- | --- | --- | --- | --- | | change_type | string | 必选 | 32 | active | 订阅变更类型,枚举值:active-团体席位订阅已生效,用户完成首次支付签约;period_extend-订阅续费成功,周期性自动扣款成功;item_update-订阅项目席位数量扩容成功;item_downgrade-订阅项目席位数量缩容成功;cancel-订阅已取消,用户取消订阅或到期未续费;cancel_at_period_end-订阅将在周期结束取消 | | change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 | | trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 | | pay_amount | string | 可选 | 16 | 1001 | 当前订阅的支付金额,单位分 | | subscription | string | 可选 | 20000 | 参考:alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 | 通知示例 ```json curl -X POST 'NOTIFY_URL' \ --header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'biz_content={ "change_type":"active", "change_date":"2026-03-22 21:00:00", "trade_no":"2026022276001434360514767918", "order_no":"2026042019600065895", "pay_amount":"1001", "subscription":"订阅信息大对象,参考alipay.trade.subscription.query" }' \ --data-urlencode 'utc_timestamp=${now}' \ --data-urlencode 'sign=${sign}' \ --data-urlencode 'app_id=${appid}' \ --data-urlencode 'version=1.1' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode 'notify_id=${notify_id}' \ --data-urlencode 'msg_method=alipay.trade.subscription.changed' ``` 通知应答 | 响应报文 | 描述 | 是否重试 | 是否区分大小写 | | :--- | :--- | :--- | :--- | | success | 消息处理成功 | 否 | 否 | | fail | 消息处理失败 | 是 | 否 | ##### 查询订阅 商家通过[alipay.trade.subscription.query(订阅查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-query.md) 来查询具体的订阅相关信息。 注意: + 入参推荐按照subscription_id精准查询,传参只传入subscription_id即可。 + 返回结果中subscription_status代表对应订阅id的状态,调用方可以根据当前状态做相关的业务逻辑处理。 + 返回结果中current_period_start和current_period_end代表截止到查询时刻,最近的一次订阅支付(用户首次订阅支付或周期扣款支付)对应的生效周期的起止时间。 + 返回结果中start_date代表订阅首次支付成功对应的生效开始时间。 + 返回结果中cancel_at_period_end代表当前订阅是否会在周期结束后取消。当订阅取消时(商户调取消接口取消/用户主动在支付宝端内取消),订阅并不会立即失效,而是会已生效的周期结束后才真正取消,商户可以基于查询到的该字段来确认是否会在周期结束后取消。 + 返回结果中的items和pending_items,当用户执行席位数量缩减操作时,已完成扣款的计费周期内,席位数量保持缩减前的原数量不变,待计费周期结束后,系统自动将席位数量更新为缩减后的数量。 - items:当前周期内生效的订阅项信息,含席位数量quantity(缩减前的原数量)。 - pending_items:待生效周期的订阅项信息,含席位数量quantity(缩减后的新数量)。 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | customer_id | 支付宝客户id | String | 是 | [1,64] | 202603210030100000003 | 支付宝客户id | | subscription_status | 订阅状态 | String | 否 | [0,64] | ACTIVE | 订阅状态,枚举值:INCOMPLETE(未完成支付)、ACTIVE(活跃)、CANCELED(已取消) | | subscription_id | 订阅id | String | 否 | [0,64] | 20260320123156789 | 订阅id | 请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_status":"ACTIVE", "subscription_id":"20260320123156789", "customer_id":"202603210030100000003" }' ``` 响应参数说明 | 参数 | 名称 | 参数类型 | 描述 | | :--- | :--- | :--- | :--- | | subscriptions | 订阅详情信息 | Array | 订阅详情信息列表 | | ┗ subscription_id | 订阅id | String | 订阅id | | ┗ customer_id | 客户id | String | 客户id | | ┗ subscribe_title | 订阅标题 | String | 订阅标题 | | ┗ subscription_status | 订阅状态 | String | 订阅状态:INCOMPLETE(未完成)、ACTIVE(活跃)、INCOMPLETE_EXPIRED(未完成已过期)、CANCELED(已取消) | | ┗ current_period_start | 最近一个扣款周期开始时间 | String | 最近一个扣款周期开始时间 | | ┗ current_period_end | 最近一个扣款周期结束时间 | String | 最近一个扣款周期结束时间 | | ┗ cancel_at_period_end | 周期结束是否失效 | Boolean | true-周期结束状态生效;false-周期结束依旧生效 | | ┗ start_date | 订阅开始日期 | String | 订阅开始日期 | | ┗ canceled_date | 订阅取消时间 | String | 订阅取消时间 | | ┗ created | 创建时间 | String | 创建时间 | | ┗ metadata | 订阅元数据 | String | 订阅元数据,订阅创建时传入 | | ┗ items | 订阅项目信息 | Array | 订阅项目信息列表,详见 [alipay.trade.subscription.query(订阅查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-query.md) | | ┗ pending_items | 待生效的订阅项 | Array | 待生效的订阅项列表,详见 [alipay.trade.subscription.query(订阅查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-query.md) | #### 订阅续费扣款 ##### 自动续费 当用户订阅的产品到达续费周期后,将自动从用户账户扣款。扣款成功后,支付宝将通过系统消息通知商户继续提供相应产品或服务进行履约。 默认扣款逻辑: + 扣款预通知:在订阅产品到期日前的2天,支付宝会向用户发送扣款预通知,提醒用户即将扣款; + 执行扣款:在订阅产品到期日的前1天,支付宝会对用户进行扣款; + 扣款重试:如果扣款失败,在订阅产品到期前,支付宝会持续根据算法进行多次扣款,直到扣款成功; + 扣款失败:若订阅产品已到期,支付宝将不再进行扣款,并解约订阅产品,将用户订阅状态置为失效。 获取续费结果: 商家通过调用 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅的续费结果。 注意: + 该接口为支付宝主动向商户发送的消息通知接口,商户需要配置应用网关地址以及订阅消息服务,详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md) + 商户收到消息后需要返回success表示处理成功,否则返回fail,支付宝会进行重试。 + 投递重试策略:25小时内完成8次通知,间隔频率为:2m、10m、10m、1h、2h、6h、15h。 + 商户获取消息通知后,需要使用支付宝公钥进行验签。 + 用户续费成功后,发送的商户消息通知中的 订阅变更类型(change_type)为 订阅续费成功(period_extend)。 + 生效周期字段:subscription中的current_period_start和current_period_end代表本次订阅支付对应的生效周期的起止时间。 + 到期后仍未扣款成功,发送的商户消息通知中的 订阅变更类型(change_type)为 订阅已取消(cancel)。 | 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 | | --- | --- | --- | --- | --- | --- | | change_type | string | 必选 | 32 | period_extend或cancel | 订阅变更类型,枚举值:active-团体席位订阅已生效,用户完成首次支付签约;period_extend-订阅续费成功,周期性自动扣款成功;item_update-订阅项目席位数量扩容成功;item_downgrade-订阅项目席位数量缩容成功;cancel-订阅已取消,用户取消订阅或到期未续费;cancel_at_period_end-订阅将在周期结束取消 | | change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 | | trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 | | pay_amount | string | 可选 | 16 | 1001 | 当前订阅的支付金额,单位分 | | subscription | string | 可选 | 20000 | 参考:alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 | 通知示例 ```json curl -X POST 'NOTIFY_URL' \ --header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'biz_content={ "change_type":"period_extend", "change_date":"2026-03-22 21:00:00", "trade_no":"2026022276001434360514767918", "pay_amount":"1001", "subscription":"订阅信息大对象,参考alipay.trade.subscription.query" }' \ --data-urlencode 'utc_timestamp=${now}' \ --data-urlencode 'sign=${sign}' \ --data-urlencode 'app_id=${appid}' \ --data-urlencode 'version=1.1' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode 'notify_id=${notify_id}' \ --data-urlencode 'msg_method=alipay.trade.subscription.changed' ``` ##### 主动续费 团体订阅场景除了支持自动续费外,还支持主动续费能力。当扣款失败后,支付宝侧会提供主动支付的能力,向用户的支付宝账户维护的邮箱或手机推送待支付链接,由用户点击后唤起支付宝收银台,进行主动支付。 #### 订阅席位数量增加 针对已生效的团体订阅指定需要增加的席位数量,支付宝侧会按照最新的席位数量根据已发生扣款的周期(首次支付和周期扣款)计算出用户补贴价的金额,生成对应的支付链接,来让用户进行差价支付,支付成功后,订阅的席位数量会立即更新。 ![](https://mdn.alipayobjects.com/afts/img/A*i5m-S4QP9SQAAAAASiAAAAgAeq8wAA/original?bz=openpt_doc&t=3e_FAO3yqBnCL4HQlJsqGrXjdkhs5OoxqiMy-veA7eUDAAAAZAAAMK8AAAAA) 商家可按如下指引调用接口,进行团体商品席位数量的增加并感知席位增加的结果。 ```mermaid sequenceDiagram participant 用户 participant 商户 participant 支付宝 用户->>商户: 1: 发起升级 商户->>支付宝: 1.1: 订阅修改(alipay.trade.subscription.modify) 支付宝->>支付宝: 1.1.1: 差价计算,计算用户需要实际支付的金额 支付宝-->>商户: 1.1.2: 返回订阅id以及升级的支付链接 商户->>商户: 1.2: 消费支付链接,如果是网页版,展示支付二维码 商户-->>用户: 1.3: 二维码展示 商户->>支付宝: 1.4: 消费支付链接,如果是app端,则唤起支付宝,与二维码选其一对客 支付宝-->>商户: 1.5: 支付完成后发送订阅更新结果消息(alipay.trade.subscription.changed) ``` ##### 发起订阅商品席位数量增加 商家可通过订阅修改接口 [alipay.trade.subscription.modify(订阅修改接口)](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md)实现席位增加的申请请求,引导用户确认支付后生效。 注意: + 席位增加需要用户确认并完成支付后才会增加席位数量,该接口会返回支付宝的支付链接供用户确认支付。 + modify_type设置为INCREASE_QUANTITY代表本次操作为团体席位数量增加。 + 通过preserve_billing_cycle参数控制是否保持计费周期不变。preserve_billing_cycle的传参会影响席位增加后的订阅周期的时间变化和当前用户针对席位增加操作需要支付的金额。 - 订阅周期的时间:例如用户已生效周期为2026050120260531,如果用户在20260515操作席位数量增加,preserve_billing_cycle=true代表席位增加后,生效时间依旧是2026050120260531。 - 支付金额:preserve_billing_cycle=true会按照当前周期剩余时间的比例(单位天)按比例支付增加的数量对应的差价。 + item_id代表已生效的订阅项id,通过订阅查询接口alipay.trade.subscription.query或通知接口alipay.trade.subscription.changed中返回的item_id。注意,每次团体席位的扩容成功或者缩容成功,item_id都会发生变化,调用方需要拿最新生效的item_id作为入参进行席位的数量调整请求的入参。 订阅席位增加参数说明 | 参数名 | 必选 | 类型 | 长度/范围 | 示例值 | 描述 | | :--- | --- | --- | --- | --- | --- | | subscription_id | 必选 | string | [1,64] | 20260320123156789 | 订阅 ID | | modify_type | 必选 | string | [1,64] | INCREASE_QUANTITY | 更新类型,枚举值:INCREASE_QUANTITY-坐席扩容 | | preserve_billing_cycle | 必选 | boolean | - | true | 是否保持计费周期不变,订阅扩容场景下仅支持true | | items | 必选 | array | [0,100] | - | 订阅项目信息 | | ┗ item_id | 必选 | string | [1,64] | 2026032012314 | 升级的源订阅项id,用户支付成功后,通过alipay.trade.subscription.query或通知接口alipay.trade.subscription.changed中返回的item_id。 | | ┗ source_quantity | 必选 | string | [1,8] | 80 | 订阅的原始坐席数量 | | ┗ target_quantity | 必选 | string | [1,8] | 100 | 订阅的目标坐席数量 | 席位增加请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"INCREASE_QUANTITY", "preserve_billing_cycle":true, "items":[ { "item_id":"2026032012314", "source_quantity":"10", "target_quantity":"20" } ] }' ``` ##### 获取订阅席位增加成功消息通知 商家通过订阅 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅商品的购买结果。 注意: + 该接口为支付宝主动向商户发送的消息通知接口,商户需要配置应用网关地址以及订阅消息服务,详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md) + 商户收到消息后需要返回success表示处理成功,否则返回fail,支付宝会进行重试。 + 投递重试策略:25小时内完成8次通知,间隔频率为:2m、10m、10m、1h、2h、6h、15h。 + 商户获取消息通知后,需要使用支付宝公钥进行验签。 + 用户购买成功后,发送的订阅产品商户消息通知中的 订阅变更类型(change_type)为 订阅已生效(item_update)。 + 生效周期字段:subscription中的current_period_start和current_period_end代表本次订阅支付对应的生效周期的起止时间。 + 席位数量字段:在subscription中的items中的quantity代表扩容后的席位数量。 | 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 | | --- | --- | --- | --- | --- | --- | | change_type | string | 必选 | 32 | item_update | 订阅变更类型,枚举值:active-团体席位订阅已生效,用户完成首次支付签约;period_extend-订阅续费成功,周期性自动扣款成功;item_update-订阅项目席位数量扩容成功;item_downgrade-订阅项目席位数量缩容成功;cancel-订阅已取消,用户取消订阅或到期未续费;cancel_at_period_end-订阅将在周期结束取消 | | change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 | | trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 | | pay_amount | string | 可选 | 16 | 1001 | 当前订阅的支付金额,单位分 | | subscription | string | 可选 | 20000 | 参考:alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 | 通知示例 ```json curl -X POST 'NOTIFY_URL' \ --header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'biz_content={ "change_type":"item_update", "change_date":"2026-03-22 21:00:00", "trade_no":"2026022276001434360514767918", "pay_amount":"1001", "subscription":"订阅信息大对象,参考alipay.trade.subscription.query" }' \ --data-urlencode 'utc_timestamp=${now}' \ --data-urlencode 'sign=${sign}' \ --data-urlencode 'app_id=${appid}' \ --data-urlencode 'version=1.1' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode 'notify_id=${notify_id}' \ --data-urlencode 'msg_method=alipay.trade.subscription.changed' ``` #### 订阅席位数量减少 针对已生效的团体订阅可以指定需要减少的席位数量,支付宝侧会返回席位数量缩减后的签约链接,让用户重新确认并签约后续的扣款协议。 注意: + 针对已按照缩容前的席位数量发生了扣款的订阅周期依旧保持缩容前的席位数量,在周期结束后,才会按照缩减后的席位数量进行扣款收费。 ![](https://mdn.alipayobjects.com/afts/img/A*WYilRa3BaD0AAAAASyAAAAgAeq8wAA/original?bz=openpt_doc&t=mQJcLYbUyZJ_V_VNRqYnNKXNd6qbB3bT5J2KWYEXjR4DAAAAZAAAMK8AAAAA) 商家可按如下指引调用接口,进行订阅席位数量减少并感知降级结果: ```mermaid sequenceDiagram participant 用户 participant 商户 participant 支付宝 用户->>商户: 1: 发起降级 商户->>支付宝: 1.1: 订阅修改(alipay.trade.subscription.modify) 支付宝-->>商户: 1.2: 返回订阅id以及降级的链接 商户->>商户: 1.3: 消费降级链接,如果是网页版,展示支付二维码 商户-->>用户: 1.4: 二维码展示 商户->>支付宝: 1.5: 消费降级链接,如果是app端,则唤起支付宝,与二维码选其一对客 支付宝-->>商户: 1.6: 降级完成后发送订阅更新结果消息(alipay.trade.subscription.changed) ``` ##### 发起订阅席位数量减少 商家可通过订阅修改接口 [alipay.trade.subscription.modify(订阅修改接口)](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md)实现席位缩减的申请请求,引导用户在支付宝端内确认并成功签署协议后才会生效。 注意: + 针对已按照缩容前的席位数量发生了扣款的订阅周期依旧保持缩容前的席位数量,在周期结束后,才会按照缩减后的席位数量进行扣款收费。 + 席位减少需要用户确认并完成支付,因此该接口会返回支付宝的协议确认链接供用户确认。 + modify_type设置为DECREASE_QUANTITY代表席位数量减少操作。 + item_id代表已生效的订阅项id,通过订阅查询接口alipay.trade.subscription.query或通知接口alipay.trade.subscription.changed中返回的item_id。注意,每次团体席位的扩容成功或者缩容成功,item_id都会发生变化,调用方需要拿最新生效的item_id作为入参进行席位的数量调整请求的入参。 订阅席位减少参数说明 | 参数名 | 必选 | 类型 | 长度/范围 | 示例值 | 描述 | | --- | --- | --- | --- | --- | --- | | subscription_id | 必选 | string | [1,64] | 20260320123156789 | 订阅 ID | | modify_type | 必选 | string | [1,64] | DECREASE_QUANTITY | 更新类型,枚举值:DECREASE_QUANTITY-坐席缩容减少 | | items | 必选 | array | [0,100] | - | 订阅项目信息 | | ┗ item_id | 必选 | string | [1,64] | 2026032012314 | 升级的源订阅项id,用户支付成功后,通过alipay.trade.subscription.query或通知接口alipay.trade.subscription.changed中返回的item_id | | ┗ source_quantity | 必选 | string | [1,8] | 100 | 订阅的原始坐席数量 | | ┗ target_quantity | 必选 | string | [1,8] | 80 | 订阅的目标坐席数量 | 订阅升级请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"DECREASE_QUANTITY", "items":[ { "item_id":"2026032012314", "source_quantity":"100", "target_quantity":"80" } ] }' ``` ##### 获取订阅席位减少成功消息通知 商家通过订阅 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)来获取订阅席位减少成功的结果。 注意: + 该接口为支付宝主动向商户发送的消息通知接口,商户需要配置应用网关地址以及订阅消息服务,详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md) + 商户收到消息后需要返回success表示处理成功,否则返回fail,支付宝会进行重试。 + 投递重试策略:25小时内完成8次通知,间隔频率为:2m、10m、10m、1h、2h、6h、15h。 + 商户获取消息通知后,需要使用支付宝公钥进行验签。 + 用户购买成功后,发送的订阅产品商户消息通知中的 订阅变更类型(change_type)为 订阅已生效(item_downgrade)。 + 席位数量字段:在subscription中的items中的quantity代表扩容后的席位数量。 | 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 | | --- | --- | --- | --- | --- | --- | | change_type | string | 必选 | 32 | item_downgrade | 订阅变更类型,枚举值:active-团体席位订阅已生效,用户完成首次支付签约;period_extend-订阅续费成功,周期性自动扣款成功;item_update-订阅项目席位数量扩容成功;item_downgrade-订阅项目席位数量缩容成功;cancel-订阅已取消,用户取消订阅或到期未续费;cancel_at_period_end-订阅将在周期结束取消 | | change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 | | trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 | | subscription | string | 可选 | 20000 | 参考:alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 | 通知示例 ```json curl -X POST 'NOTIFY_URL' \ --header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'biz_content={ "change_type":"item_update", "change_date":"2026-03-22 21:00:00", "trade_no":"2026022276001434360514767918", "subscription":"订阅信息大对象,参考alipay.trade.subscription.query" }' \ --data-urlencode 'utc_timestamp=${now}' \ --data-urlencode 'sign=${sign}' \ --data-urlencode 'app_id=${appid}' \ --data-urlencode 'version=1.1' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode 'notify_id=${notify_id}' \ --data-urlencode 'msg_method=alipay.trade.subscription.changed' ``` #### 订阅取消 针对团体席位的订阅,可以通过两种形式进行取消: + 周期结束后取消:设置 `cancel_at_period_end=true` + 立即取消:设置 `cancel_at_period_end=false` 立即取消会触发退款,退款金额可自定义退款金额 或 系统自动计算残值,若商户自定义金额为0,即为立即取消但不退款 取消结果将通过订阅变更通知接口推送给商户 ##### 发起订阅取消 商家可通过订阅修改接口 [alipay.trade.subscription.modify(订阅修改接口)](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md)实现订阅取消和取消后恢复功能,并接收相应的通知 重要参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | :--- | --- | --- | --- | --- | --- | --- | | subscription_id | 订阅id | String | 是 | [1,64] | 20260320123156789 | 需要取消的订阅id | | modify_type | 更新类型 | String | 是 | [1,64] | CANCEL | 固定设置为 `CANCEL`,表示订阅取消操作 | | cancel_at_period_end | 是否在当前周期结束时取消订阅 | Boolean | 是 | - | true | true:表示在当前计费周期结束后取消订阅; false:表示立即取消 | | refund_amount | 自定义退款金额 | Number | 否 | [0,1000000000] | 100 | 不传:系统按照时间规则计算残值作为退款金额;自定义传入:按商家指定的金额退款,0表示直接取消不退款 | ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"CANCEL", "cancel_at_period_end":true }' ``` ##### 订阅取消结果通知 支付宝通过订阅变更通知接口 [alipay.trade.subscription.changed(订阅产品商户消息通知接口)](https://opendocs.alipay.com/solution/0a3d608d_alipay.trade.subscription.changed.md)向商户发送订阅取消结果通知 注意: + 该接口为支付宝主动向商户发送的消息通知接口,商户需要配置应用网关地址以及订阅消息服务,详情查看[接入准备](https://opendocs.alipay.com/solution/repo-046zj4.md) + 商户收到消息后需要返回success表示处理成功,否则返回fail,支付宝会进行重试。 + 投递重试策略:25小时内完成8次通知,间隔频率为:2m、10m、10m、1h、2h、6h、15h。 + 商户获取消息通知后,需要使用支付宝公钥进行验签。 + 取消成功后,立即会通知change_type=cancel_at_period_end的消息;在用户已生效的订阅周期结束后会再次通知change_type=cancel的消息。 + 周期结束取消的通知会设置subscription中的cancel_at_period_end=true,代表周期结束后取消。 + 商户收到通知后需返回success,否则支付宝会重试通知。 取消通知参数 | 参数名 | 类型 | 必选 | 最大长度 | 示例值 | 描述 | | --- | --- | --- | --- | --- | --- | | change_type | string | 必选 | 32 | cancel_at_period_end或cancel | 订阅变更类型,枚举值:active-团体席位订阅已生效,用户完成首次支付签约;period_extend-订阅续费成功,周期性自动扣款成功;item_update-订阅项目席位数量扩容成功;item_downgrade-订阅项目席位数量缩容成功;cancel_at_period_end-订阅会在周期结束后取消;cancel-订阅已取消,用户取消订阅或到期未续费 | | change_date | string | 可选 | 32 | 2026-03-22 21:00:00 | 订阅变更时间 | | trade_no | string | 可选 | 64 | 2026022276001434360514767918 | 支付宝交易号 | | subscription | string | 可选 | 20000 | 参考:alipay.trade.subscription.query接口返回的字段 | 订阅信息大对象 | 通知示例 ```json curl -X POST 'NOTIFY_URL' \ --header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'biz_content={ "change_type":"item_update", "change_date":"2026-03-22 21:00:00", "trade_no":"2026022276001434360514767918", "subscription":"订阅信息大对象,参考alipay.trade.subscription.query" }' \ --data-urlencode 'utc_timestamp=${now}' \ --data-urlencode 'sign=${sign}' \ --data-urlencode 'app_id=${appid}' \ --data-urlencode 'version=1.1' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode 'notify_id=${notify_id}' \ --data-urlencode 'msg_method=alipay.trade.subscription.changed' ``` ##### 取消后恢复 如果用户在周期结束前想恢复订阅,可以使用取消后恢复功能 恢复参数说明 | 参数 | 名称 | 参数类型 | 是否必填 | 最大长度 | 示例值 | 描述 | | --- | :---: | :---: | :---: | :---: | :---: | --- | | subscription_id | 订阅id | String | 是 | [1,64] | 20260320123156789 | 需要恢复的订阅id | | modify_type | 更新类型 | String | 是 | [1,64] | REVERT_CANCEL | 固定设置为 `REVERT_CANCEL`,表示取消后恢复操作 | | description | 恢复描述 | String | 否 | [0,256] | 恢复订阅 | 恢复描述,记录恢复原因或备注 | 恢复请求示例 ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"REVERT_CANCEL", "description":"用户申请恢复订阅" }' ``` 恢复响应参数 | 参数 | 名称 | 参数类型 | 描述 | | --- | :---: | :---: | --- | | subscription_id | 订阅id | String | 订阅id | | alipay_jump_schema | 支付宝长链跳端schema | String | 长链,适用于跳转拉起支付宝客户端,用户需通过此链接确认恢复 | | alipay_schema | 支付宝跳转的schema | String | 短链,适用于生成二维码,用户扫码确认恢复 | 恢复结果通知 恢复成功后,支付宝会发送订阅变更通知: + `subscription_status` 会变为 `ACTIVE` + `cancel_at_period_end` 会变为 `false` + `canceled_date` 会被清除 --- ### 营销工具包 目录路径:Token Pay · AI 连续订阅 > 接入指南 > 营销工具包 来源:https://aipay.alipay.com/docs/subscribe/integration-guide/marketing-toolkit.md #### 产品特色 **营销工具包** 为AI商户打造一站式营销解决方案。 优惠 支持「百分比折扣」和「固定金额减免」两种模式,并可设置折扣持续时间、特定人群方案,覆盖首购优惠、长期会员折扣、教育优惠等多元营销场景。此外,支付宝提供「先体验后付费」的订阅模式。 | **营销策略** | **场景案例** | | :---: | :---: | | 用户拉新 | 5元试用7天,后续订阅48元/月。 | | 老客留存 | 连续按月订阅享受8折优惠 | | 人群优惠 | 通过学生认证后,享受5折优惠 | 为保障支付宝用户的权益,当前 营销工具包 使用存在部分限制,具体如下: 1. 试用期能力:仅对部分特邀商户开放; 2. 优惠能力:优惠后的金额不得低于正价的1/3。若首次实际支付金额低于正价的1/3,会导致用户在续费时扣款失败。 以下图片仅做线上样式参考,实际页面内容以线上为准。 ![](https://mdn.alipayobjects.com/afts/img/A*XB47SrjdmcAAAAAAXhAAAAgAeq8wAA/original?bz=openpt_doc&t=6R-v-QIpn-RChbjp0xY6NL5pvYdV7_cSQLsI3cSOgK4DAAAAZAAAMK8AAAAA) #### 试用期订阅 试用期 为用户提供「先体验后付费」的订阅模式,支持免费试用。试用结束后,系统自动按原价续费,用户感知平滑,无需重新订阅,帮助 AI 商户快速获客并提升转化率。 | **场景** | **典型策略** | | :---: | :---: | | 新用户体验 | 提供3天免费试用,降低首购决策门槛 | | 新产品体验 | 针对特定项目设置试用,引导用户体验新产品 | + 试用期时长:仅传入天数,建议试用期设置在3-7天。 + 试用期金额:支持灵活设定 以下图片仅做线上样式参考,实际页面内容以线上为准。 ![](https://mdn.alipayobjects.com/afts/img/A*OTUDQ47RodAAAAAATpAAAAgAeq8wAA/original?bz=openpt_doc&t=VDLBpWqjyWI_-_GonHcDM0bYj13IaA-GsTBgeZzqigsDAAAAZAAAMK8AAAAA) ##### 创建试用期 在[alipay.trade.subscription.create(订阅创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-create.md) 接口下,支持试用期的核心参数: + **trial_period_days**:试用期天数 + **trial_desc**:试用期描述 商家通过** trial_period_days **设置试用期天数,通过** pay_amount **控制试用期价格:若试用期无需支付(即免费试用),则 **pay_amount** 无需进行传参;若需付费试用,传入大于 0 的金额。试用期结束后,系统自动按照 **price_id** 配置的周期价格进行续费扣款。 **完整参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | --- | --- | --- | :--- | :--- | :--- | :--- | | items | 订阅项目信息 | Array | 是 | - | - | 订阅项目信息列表 | | ┗ price_id | 价格 id | String | 是 | [1,32] | 202603201234567889 | 价格创建接口(alipay.trade.price.create)返回的价格id,代表本次操作的目标价格信息 | | customer_id | 支付宝客户 id | String | 是 | [1,64] | 208812345678 | 客户id,客户创建接口(alipay.trade.customer.create)返回的客户id | | trial_period_days | 试用期天数 | Number | 否 | [1,360] | 7 | 试用期天数:试用期天数设置为正整数,通常建议试用期天数3-7天 | | trial_desc | 试用期描述 | String | 否 | [1,256] | 免费试用7天 | 用于签约页展示,若不传该字段,则展示默认文案。 低价试用场景文案:"{pay_amount}元试用{trial_period_days}天";免费试用场景文案:"免费试用{trial_period_days}天 | | metadata | 订阅信息元数据 | String | 否 | [1,2000] | {"key":"value"} | 商户自定义元数据,将在全链路通知中返回 | | pay_amount | 支付金额 | Number | 否 | [1,1000000000] | 100 | 支付金额,单位分; 仅用于商户自定义金额,若传了该值,用户实际支付金额会以该值为准 | **请求示例(带试用期)** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "items":[ { "price_id":"202603201234567889" } ], "customer_id":"208812345678", "trial_period_days":7, "trial_desc":"新用户 7 天免费试用", "metadata":"{\"channel\":\"app_store\"}" }' ``` **响应参数说明** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅 id** | String | 创建的订阅 ID | | **order_no** | **订阅支付单 ID** | String | 订阅支付单号 | | **trial_start** | **试用期开始时间** | String | 试用期开始时间,格式:yyyy-MM-dd HH:mm:ss | | **trial_end** | **试用期结束时间** | String | 试用期结束时间,格式:yyyy-MM-dd HH:mm:ss | | **alipay_jump_schema** | **支付宝长链跳端 schema** | String | 长链,适用于跳转拉起支付宝客户端 | | **alipay_schema** | **支付宝跳转的 schema** | String | 短链,适用于生成二维码 | | **pay_amount** | **支付金额** | Number | 实际支付金额,单位:分(试用期通常为 0) | **响应示例** ```json { "alipay_trade_subscription_create_response": { "code": "10000", "msg": "Success", "subscription_id": "SUB20260522002", "order_no": "2026052219600065896", "trial_start": "2026-05-22 10:00:00", "trial_end": "2026-05-29 10:00:00", "pay_amount": 0, "alipay_jump_schema": "https://render.alipay.com/p/XXXXXXXXXX", "alipay_schema": "https://qr.alipay.com/XXXXXXXXXX" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` **试用期说明** | **项目** | **说明** | | :---: | :---: | | 试用期时长 | 推荐 3-7 天,商户可自定义 | | 试用期费用 | 0 元,用户无需付费 | | 自动续费 | 试用期结束后,系统自动按原价续费 | | 取消政策 | 用户可在试用期内随时取消订阅,不产生费用 | | 通知时机 | 试用开始、试用结束、续费成功均会发送通知 | ##### 试用期扣款策略 试用期期间扣款默认逻辑如下: + 扣款预通知:在试用期到期的前1天,支付宝会向用户发送扣款预通知,提醒用户即将扣款; + 执行扣款:在试用期到期的当天,支付宝会对用户进行扣款; + 扣款重试:在试用期到期前,支付宝会持续根据算法进行多次扣款,直到扣款成功; + 扣款失败:若试用期已到期仍未扣款成功,支付宝将不再进行扣款,并解约订阅产品。 ##### 查询试用期 商家可调用[alipay.trade.subscription.query(订阅查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-query.md)查询试用期的状态和信息。 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅 id** | String | 是 | [1,64] | 2026050800300499484 | 订阅 ID | | **customer_id** | **支付宝客户 id** | String | 是 | [1,64] | 202605080030600439037 | 支付宝客户 ID | **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"2026050800300499484", "customer_id":"202605080030600439037" }' ``` **响应参数说明(试用期相关)** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **trial_start** | **试用期开始时间** | String | 试用期开始时间 | | **trial_end** | **试用期结束时间** | String | 试用期结束时间 | **响应示例(试用期信息)** ```json { "alipay_trade_subscription_query_response": { "msg": "Success", "subscriptions": [ { "subscription_id": "2026050800300499484", "subscribe_title": "试用测试", "created": "2026-05-08 10:43:31", "subscription_status": "TRIALING", "trial_start": "2026-05-08 10:43:31", "trial_end": "2026-06-07 23:59:59", "current_period_end": "2026-06-07 23:59:59", "customer_id": "202605080030600439037", "items": [ { "quantity": 1, "item_id": "2026050800300546321", "created": "2026-05-08 10:43:31", "price": { "gmt_create": "2026-05-08 10:43:27", "product": { "gmt_create": "2026-05-08 10:43:27", "metadata": "{\"level\":\"annual\",\"category\":\"membership\"}", "name": "年度会员服务", "description": "年度会员订阅服务", "active": true, "id": "202605080010000151803" }, "metadata": "{\"promotion\":\"new_year_discount\"}", "recurring": { "interval_count": 1, "usage_type": "licensed", "interval": "MONTH" }, "product_id": "202605080010000151803", "active": true, "id": "202605080020000166958", "unit_amount": "1", "type": "recurring" } } ], "current_period_start": "2026-05-08 10:43:31", "start_date": "2026-05-08 10:43:31" } ], "code": "10000" }, "sign": "kYtrT6y/bnv5JfbRlhsaWaZPirazVKUDOuCH2GhYxps3hVi9GnZ9Rnu9g2gzydGXHhUZGPl8Sg/dUegtgOywJ5vilvFY1JLYVW/fLHaykhGpxWF3QqWrlrsWeRACYjXqyqzD+88l9Mjsn2aFGcXbZkwUohIwgeFBzmY2Qv8qDgo4lh79Qa7PehHQgrHcNy88mVo8MbMncGa+wLku5ZbEISd6dMQzW+Dcf7BCqfEum5A9U7dYEZsGsJW1gImNxX3iTff1bCS34wbcCfuecxxRTCOFInqOnWHtKzKh6qgzO05QPL6BUR2YI4E6zZ6CSOX9U2OUv4waVWbbCVLyMdXjpA==" } ``` #### 优惠 优惠 为AI商户提供灵活的折扣策略,支持百分比折扣和固定金额减免,并可设置折扣持续时间,满足从首购优惠到长期会员折扣的各种营销需求。 优惠可配置两种折扣类型: | **类型** | **说明** | **适用场景** | | :--- | :--- | :--- | | percent_off | 百分比折扣 | 8 折优惠、9 折优惠等 | | amount_off | 固定金额折扣 | 满 100 减 20、立减 5 元等 | 优惠可配置三种持续时间: | **类型** | **说明** | **适用场景** | | :--- | :--- | :--- | | once | 仅使用一次 | 首购优惠、一次性折扣 | | repeating | 前X个周期有效 | 新用户前 3 个周期享 5 折 | | forever | 永久有效 | 高级会员终身享 9 折 | ##### 创建优惠 商家可调用 [alipay.trade.promotion.coupon.create(订阅营销优惠创建接口)](https://opendocs.alipay.com/solution/a6ea4c48_alipay.trade.promotion.coupon.create.md)创建灵活的折扣策略,支持百分比折扣和固定金额减免,并可设置折扣持续时间。 **注意:** + 优惠创建时需要指定折扣类型:百分比折扣(percent_off)或固定金额折扣(amount_off) + 支持设置优惠的有效期(redeem_by) **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **name** | **优惠名称** | String | 是 | [1,64] | 新客 5 折优惠 | 优惠名称,用于展示 | | **percent_off** | **百分比折扣** | Number | 条件必填 | [1,100] | 10 | 百分比折扣,单位:百分比,例如 10 表示 10% OFF。与 amount_off 二选一 | | **amount_off** | **固定折扣金额** | Number | 条件必填 | [1,1000000000] | 2000 | 固定折扣金额,单位:分。与 percent_off 二选一 | | **duration** | **持续时间类型** | String | 是 | [1,32] | once | 持续时间类型:once(仅一次)、repeating(前 X 周期)、forever(永久) | | **duration_in_iterations** | **持续周期数** | Number | 否 | [1,1000] | 3 | 当 duration_type 为 repeating 时必填,表示前 3 个周期有效 | | **redeem_by** | **优惠过期时间** | String | 否 | [1,32] | 2026-12-31T23:59:59Z | 优惠领取截止时间,过期后新订阅不可用 | | **metadata** | **优惠元数据** | String | 否 | [1,2000] | {"key":"value"} | 商户自定义元数据 | **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.promotion.coupon.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "request_info":{ "duration":"repeating", "redeem_by":"2026-02-20 14:10:00", "coupon_id":"5JXR5XXW", "name":"新用户10元立减", "percent_off":10, "amount_off":1000, "duration_in_iterations":"3" } }' ``` **响应参数说明** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **coupon_id** | **优惠 id** | String | 创建的优惠 ID | | **name** | **优惠名称** | String | 优惠名称 | | **percent_off** | **百分比折扣** | Number | 百分比折扣,单位:百分比 | | **amount_off** | **固定折扣金额** | Number | 固定折扣金额,单位:分 | | **duration** | **持续时间类型** | String | once/repeating/forever | | **duration_in_iterations** | **持续周期数** | Number | 持续周期数 | | **redeem_by** | **优惠过期时间** | String | 领取截止时间 | | **active** | **是否可用** | Boolean | 优惠是否可用 | | **created** | **创建时间** | String | 创建时间 | **响应示例** ```json { "alipay_trade_promotion_coupon_create_response":{ "code":"10000", "msg":"Success", "coupon_info":{ "coupon_id":"5JXR5XXW", "name":"新用户10元立减", "amount_off":1000, "percent_off":10, "duration":"repeating", "duration_in_iterations":"3", "redeem_by":"2026-02-20 14:10:00" } }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ##### 使用优惠 优惠可以在用户订阅购买和升级时使用。**注意:**优惠仅适用于「个人订阅」。 订阅创建时,可通过调用[alipay.trade.subscription.create(订阅创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-create.md)使用优惠 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | | **items** | **订阅项目信息** | String | 是 | | 用于记录核心的订阅项目信息 | | **┗ price_id** | **价格id** | String | 是 | 202603201234567889 | 价格创建接口(alipay.trade.price.create)返回的价格id,代表本次操作的目标价格信息 | | **┗ coupon_id** | **优惠id** | String | 否 | 9WJ36SEC | 营销创建接口(alipay.trade.promotion.coupon.create)返回的优惠id,升级时可使用优惠券抵扣 | | **customer_id** | **客户id** | String | 是 | 208812345678 | 客户id,客户创建接口(alipay.trade.customer.create)返回的客户id | | **metadata** | **订阅信息元数据** | String | 否 | {"key":"value"} | 商户可通过此字段进行订阅信息的自定义传参,订阅生效后不可修改,将在全链路通知或查询中返回 | | **pay_amount** | **支付金额** | String | 否 | 100 | 支付金额,单位分;仅用于商户自定义金额,若传了该值,用户实际支付金额会以该值为准;若不传该金额,则会按照传入的价格id来获取本次应支付的金额 | 注意:其它参数若有传参需要,请与支付宝技术支持沟通确认 **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "customer_id": "202603291031500001001", "items": [ { "price_id": "202604130020000046658", "coupon_id": "5JXR5XXE" } ] }' ``` --- **响应示例** ```json { "alipay_trade_subscription_create_response": { "order_no": "2026052210001802785", "subscription_id": "2026052200001052354", "msg": "Success", "code": "10000", "alipay_schema": "https://u.alipay.cn/xxxxxx", "pay_amount": 4, "promotion_info": "[{\"couponId\":\"5JXR5XXE\",\"discountAmount\":0,\"originAmount\":4,\"percentOff\":\"10\"}]", "alipay_jump_schema": "alipays://platformapi/startApp?xxxxxxxxxx" }, "sign": "xxxxxxOWg==" } ``` 订阅升级时,可通过调用[alipay.trade.subscription.modify(订阅修改接口)](https://opendocs.alipay.com/solution/6cd02c10_alipay.trade.subscription.modify.md)使用优惠 **订阅升级参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **subscription_id** | **订阅id** | String | 是 | [1,64] | 20260320123156789 | 需要升级的订阅id | | **modify_type** | **更新类型** | String | 否 | [1,64] | UPGRADE | 固定设置为 `UPGRADE`,表示订阅升级操作。如不传默认为UPGRADE | | **preserve_billing_cycle** | **是否保持计费周期不变** | Boolean | 否 | - | true | 是否保持计费周期不变。`true` - 保持原周期,升级后按原周期计算差价;`false` - 重置周期,升级后按完整新周期计算 | | **pay_amount** | **支付金额** | Number | 否 | [0,1000000000] | 100 | 升级支付金额,单位:分。用于商户自定义升级费用,如不传则系统自动计算升级差价 | | **items** | **订阅项目信息** | Array | 否 | [0,100] | - | 升级后的订阅项目信息 | | **┗ item_id** | **订阅项id** | String | 否 | - | 2026032012314 | 订阅项id | | **┗ price_id** | **价格id** | String | 否 | - | 202603201234567889 | 价格创建接口(alipay.trade.price.create)返回的价格id,代表本次操作的目标价格信息 | | **┗ coupon_id** | **优惠id** | String | 否 | - | 9WJ36SEC | 营销创建接口(alipay.trade.promotion.coupon.create)返回的优惠id,升级时可使用优惠券抵扣 | 注意:其它参数若有传参需要,请与支付宝技术支持沟通确认 **升级请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_id":"20260320123156789", "modify_type":"UPGRADE", "preserve_billing_cycle":true, "pay_amount":100, "items":[ { "item_id":"2026032012314", "price_id":"202603201234567889", "coupon_id":"9WJ36SEC" } ] }' ``` --- **响应示例** ```json { "alipay_trade_subscription_create_response": { "order_no": "2026052210001802785", "subscription_id": "2026052200001052354", "msg": "Success", "code": "10000", "alipay_schema": "https://u.alipay.cn/xxxxxx", "pay_amount": 4, "promotion_info": "[{\"couponId\":\"5JXR5XXE\",\"discountAmount\":0,\"originAmount\":4,\"percentOff\":\"10\"}]", "alipay_jump_schema": "alipays://platformapi/startApp?xxxxxxxxxx" }, "sign": "xxxxxxOWg==" } ``` ##### 查询优惠 商家可调用[alipay.trade.promotion.coupon.query(订阅营销券查询接口)](https://opendocs.alipay.com/solution/4bae3c76_alipay.trade.promotion.coupon.query.md)查询已创建的优惠信息。 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **示例值** | **描述** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **coupon_id** | **优惠 id** | String | 否 | [1,64] | Z83YJJAR | 优惠 ID,不传时返回所有优惠列表 | **请求示例(查询单个优惠)** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.promotion.coupon.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "coupon_id":"29XGG87G" }' ``` **请求示例(查询所有优惠)** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.coupon.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ }' ``` **响应参数说明** | **参数** | **名称** | **参数类型** | **描述** | | :--- | :--- | :--- | :--- | | **coupon_list** | **优惠列表** | Array | 优惠详情列表 | | **┗ coupon_id** | **优惠 id** | String | 优惠 ID | | **┗ name** | **优惠名称** | String | 优惠名称 | | **┗ percent_off** | **百分比折扣** | Number | 百分比折扣,单位:百分比 | | **┗ amount_off** | **固定折扣金额** | Number | 固定折扣金额,单位:分 | | **┗ duration** | **持续时间类型** | String | once/repeating/forever | | **┗ duration_months** | **持续周期数** | Number | 持续周期数 | | **┗ redeem_by** | **优惠过期时间** | String | 领取截止时间 | | **┗ active** | **是否可用** | Boolean | 优惠是否可用 | | **┗ metadata** | **优惠元数据** | String | 商户自定义元数据 | | **┗ created** | **创建时间** | String | 创建时间 | **响应示例(查询单个优惠)** ```json { "alipay_trade_promotion_coupon_query_response":{ "code":"10000", "msg":"Success", "coupon_list":[ { "coupon_id":"5JXR5XXW", "name":"新用户10元立减", "amount_off":1000, "percent_off":10, "duration":"repeating", "duration_in_iterations":"3", "redeem_by":"2026-02-20 14:10:00" } ] }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` **响应示例(查询优惠列表)** ```json { "alipay_trade_promotion_coupon_query_response": { "code": "10000", "msg": "Success", "coupon_list": [ { "coupon_id": "Z83YJJAR", "name": "新客 5 折优惠", "percent_off": 50, "duration_type": "once", "active": true, "created": "2026-05-22T10:00:00Z" }, { "coupon_id": "Z83YJJAR", "name": "老客 8 折优惠", "percent_off": 20, "duration_type": "forever", "active": true, "created": "2026-05-20T10:00:00Z" } ], "total": 2 }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` #### 人群优惠 基于身份识别技术,为 AI 商户提供精准的人群分层定价能力。通过 IIFAA 多因子认证组件,快速验证学生等特定身份,用户无需复杂操作即可享受专属优惠价。 商户可自主配置学生优惠等身份标签,并可设置优惠价格的有效期与使用限制。AI 产品客单价较高,通过身份优惠降低学生等价格敏感群体的使用门槛,提前培育用户心智、扩大品牌覆盖,同时实现精细化用户分层运营。 ![](https://mdn.alipayobjects.com/afts/img/A*bdjvQ6IGrzMAAAAASBAAAAgAeq8wAA/original?bz=openpt_doc&t=dJcHaIw-rxJ-bnU7G2lt6uRVoXoScSPo-Lzi5LIi-PcDAAAAZAAAMK8AAAAA) 在完成商品创建后,创建价格时,可以指定该价格需要的准入身份和有效时间,支付宝侧会在用户购买时,核验对应的用户身份,只有满足身份的用户才可以购买;同时,在有效期结束后,自动为用户取消订阅。 ##### 价格创建 商家可调用 [alipay.trade.price.create(价格创建接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/price-create.md)创建指定身份的价格,获取价格实例id(price_id)。 **注意:** + **eligibility_type:** 代表该价格购买时,需要的用户身份类型,具体的值可与支付宝侧确认后传入。 + **eligibility_expire_time:** 代表用户购买后的有效期,在有效期内,支付宝侧会按照recurring进行周期扣款付费;到期后,支付宝侧会取消订阅,停止对后续的周期扣款续费。 + **循环计价模型(recurring)**:订阅类商品(含团体席位订阅商品),必传。 - **计价周期单位(interval):**与 interval_count组合使用,支持枚举值为 DAY和MONTH,分别代表周期的单位为「天」或「月」。 - **计价周期间隔(interval_count):**计价周期间隔,和 **interval** 组合使用。例如 **interval **为 MONTH,**interval_count** = 1,则扣款周期为 1 月:系统以首次购买日期为周期起始日,下一周期起始日按设定间隔顺延,若目标日期不存在则自动调整至当月最后一天。例如首次购买日为1月31日,则下一周期起始日为2月28日(或29日),再下一周期起始日恢复为3月31日。实际扣款将在周期起始日前1天发起,确保资金及时到账,服务无缝续期。 **重要参数说明** | **参数** | **名称** | **参数类型** | **是否必填** | **最大长度** | **描述** | **示例值** | | :--- | :--- | :--- | :--- | :--- | :--- | :--- | | **product_id** | **商品id** | String | 是 | [1,32] | 商品创建接口(alipay.trade.product.create)返回的商品id。 | 202603230010000006783 | | **unit_amount** | **单位金额** | Number | 是 | [1,1000000000] | 单位金额,单位:分 | 1000 | | **eligibility_type** | **价格限定购买的身份类型** | String | 是 | [1,32] | 只有满足该类型的身份才可以购买。具体的枚举值待支付宝侧分配。 | STUDENT | | **eligibility_expire_time** | **指定身份购买后的时效时间** | String | 是 | [1,32] | 满足了eligibility_type的身份购买后,失效的时间。如3d = 3天, 3m = 3月 | 3m | | **recurring** | **循环计价模型** | Object | 是 | - | 循环计价配置,用于订阅等场景 | - | | **┗ interval** | **计价周期单位** | String | 是 | [1,32] | 计价周期单位,和interval_count组合使用。枚举值: + MONTH(月) + DAY(日) | MONTH | | **┗ interval_count** | **计价周期间隔** | Number | 是 | [1,10000] | 计价周期间隔,和interval组合使用 | 1 | | **metadata** | **价格信息元数据** | String | 否 | [1,2000] | 商户需要保存在价格模型中的元数据 | {"key":"value"} | **请求示例** ```json curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "unit_amount":1000, "product_id":"202603230010000006783", "eligibility_type": "STUDENT", "eligibility_expire_time":"3m", "recurring":{ "interval_count":1, "interval":"MONTH" }, "metadata":"{\"key\":\"value\"}" }' ``` ##### 价格查询 商家可调用 [alipay.trade.price.query(价格查询接口)](https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/price-query.md),查询已创建的价格信息 重要参数说明: + **出参:** - **eligibility_type:** 代表该价格购买时,需要的用户身份类型,具体的值可与支付宝侧确认后传入。 - **eligibility_expire_time: **代表用户购买后的有效期,在有效期内,支付宝侧会按照recurring进行周期扣款付费;到期后,支付宝侧会取消订阅,停止对后续的周期扣款续费。 --- ### 商品查询接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 商品查询接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/product-query.md 商品查询接口,用于查询单个或多个商品信息。 #### 接口说明 接口名称:`alipay.trade.product.query` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 ##### 适用场景 商品查询接口,用于查询单个或多个商品信息。 ##### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.product.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递 | - | ##### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `product_id` | String | 可选 | 32 | 商品 ID,通过创建接口获取 | - | `202603230010000006783` | | `query_options` | String | 可选 | 255 | 查询选项,商户通过上送该参数来定制额外返回的信息字段,数组格式 | `price`:默认价格信息 | `["price"]` | ##### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeProductQueryModel; import com.alipay.api.request.AlipayTradeProductQueryRequest; import com.alipay.api.response.AlipayTradeProductQueryResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeProductQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeProductQueryRequest request = new AlipayTradeProductQueryRequest(); AlipayTradeProductQueryModel model = new AlipayTradeProductQueryModel(); // 设置商品id model.setProductId("202603230010000006783"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("price"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeProductQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeProductQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeProductQueryRequest request = new AlipayTradeProductQueryRequest(); AlipayTradeProductQueryModel model = new AlipayTradeProductQueryModel(); // 设置商品id model.ProductId = "202603230010000006783"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("price"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeProductQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "product_id":"202603230010000006783", "query_options":[ "price" ] }' ``` ::: :::: ##### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | ##### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `product_list` | NexusPayProduct | 必选 | - | 商品信息列表 | - | - | | `product_list.id` | String | 必选 | 32 | 商品 ID | - | `20260324001001` | | `product_list.name` | String | 必选 | 255 | 商品名称 | - | `Gold 会员` | | `product_list.description` | String | 必选 | 255 | 商品描述 | - | `基础权益` | | `product_list.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `product_list.default_price_id` | String | 可选 | 32 | 商品的默认价格 ID | - | `20260324001001` | | `product_list.default_price` | NexusSimplePrice | 可选 | - | 默认价格信息 | - | - | | `product_list.default_price.id` | String | 必选 | 32 | 价格 ID | - | `20260324001001` | | `product_list.default_price.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `product_list.default_price.type` | String | 必选 | 32 | 价格类型 | `recurring`:订阅;`one_time`:单次支付 | `recurring` | | `product_list.default_price.unit_amount` | Number | 必选 | 32 | 单位金额,单位为分 | - | `1000` | | `product_list.default_price.recurring` | Recurring | 必选 | - | 订阅周期信息 | - | - | | `product_list.default_price.recurring.interval` | String | 可选 | 16 | 订阅周期类型,目前支持 `DAY` 和 `MONTH` | `MONTH`:月;`DAY`:天 | `MONTH` | | `product_list.default_price.recurring.interval_count` | Number | 可选 | 32 | 订阅周期数量,目前周期单位只支持月或日 | - | `1` | | `product_list.default_price.recurring.usage_type` | String | 可选 | 16 | 计费模式 | `licensed`:固定计费;`metered`:按量计费 | `licensed` | | `product_list.default_price.recurring.trial_period_days` | Number | 可选 | 32 | 试用期天数 | - | `10` | | `product_list.default_price.metadata` | String | 可选 | 2000 | 价格信息元数据 | - | `{"key":"value"}` | | `product_list.default_price.custom_unit_amount` | CustomUnitAmount | 可选 | - | 自定义单价 | 当 `unit_amount` 为空时必选 | - | | `product_list.default_price.custom_unit_amount.enable` | Boolean | 必选 | 10 | 是否启用灵活定价,启用后可设置 `preset`、`maximum`、`minimum` 字段 | - | `true` | | `product_list.default_price.custom_unit_amount.preset` | Number | 可选 | 32 | 预设的自定义价格,单位为分 | 灵活定价开启后可设置 | `88888` | | `product_list.default_price.custom_unit_amount.maximum` | Number | 可选 | 32 | 可自定义的最大金额,单位为分 | 灵活定价开启后可设置 | `1000000000` | | `product_list.default_price.custom_unit_amount.minimum` | Number | 可选 | 32 | 可自定义的最小金额,单位为分 | 灵活定价开启后可设置 | `100` | | `product_list.metadata` | String | 可选 | 2000 | 商品信息元数据,通过商品创建接口传入 | - | `{"key":"value"}` | | `product_list.gmt_create` | String | 必选 | 64 | 创建时间 | - | `2026-03-24 18:00:00` | ##### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_product_query_response": { "code": "10000", "msg": "Success", "product_list": [ { "id": "20260324001001", "name": "Gold 会员", "description": "基础权益", "active": true, "default_price_id": "20260324001001", "default_price": { "id": "20260324001001", "active": true, "type": "recurring", "unit_amount": 1000, "recurring": { "interval": "MONTH", "interval_count": 1, "usage_type": "licensed", "trial_period_days": 10 }, "metadata": "{\"key\":\"value\"}", "custom_unit_amount": { "enable": true, "preset": 88888, "maximum": 1000000000, "minimum": 100 } }, "metadata": "{\"key\":\"value\"}", "gmt_create": "2026-03-24 18:00:00" } ] }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_product_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: ##### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常。可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `APP_ID_NOT_MATCH` | 应用 ID 与商品所属应用不匹配 | 请检查传入的商品 ID 是否正确 | | `PRODUCT_NOT_EXIST` | 商品不存在 | 请检查 `product_id` 是否正确,或检查账号下是否有商品存在 | --- ### 商品创建接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 商品创建接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/product-create.md 商品创建接口 #### 接口说明 接口名称:`alipay.trade.product.create` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 适用场景 商品创建接口。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.product.create` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `name` | String | 必选 | 255 | 商品名称 | - | `Gold 会员` | | `description` | String | 必选 | 255 | 商品描述 | - | `基础权益` | | `metadata` | String | 可选 | 2000 | 商户需要保存在商品模型中的元数据 | - | `{"key":"value"}` | | `images` | String | 可选 | 4000 | 图片地址 | 支持传入不超过 5 个地址 | `["https://antgroup.com"]` | | `marketing_features` | String | 可选 | 4000 | 营销信息 | 支持传入不超过 5 个营销信息 | `["16000积分"]` | | `unit_label` | String | 可选 | 100 | 单位别名 | - | `积分` | | `url` | String | 可选 | 500 | 可用于跳转商户网址地址 | - | `https://antgroup.com` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.response.AlipayTradeProductCreateResponse; import com.alipay.api.domain.AlipayTradeProductCreateModel; import com.alipay.api.request.AlipayTradeProductCreateRequest; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeProductCreate { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeProductCreateRequest request = new AlipayTradeProductCreateRequest(); AlipayTradeProductCreateModel model = new AlipayTradeProductCreateModel(); // 设置商品名称 model.setName("Gold 会员"); // 设置商品描述 model.setDescription("基础权益"); // 设置商品模型元数据 model.setMetadata("{\"key\":\"value\"}"); // 设置图片地址 model.setImages("[\"https://antgroup.com\"]"); // 设置营销信息 model.setMarketingFeatures("[\"16000积分\"]"); // 设置单位别名 model.setUnitLabel("积分"); // 设置跳转地址 model.setUrl("https://antgroup.com"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeProductCreateResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeProductCreate { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeProductCreateRequest request = new AlipayTradeProductCreateRequest(); AlipayTradeProductCreateModel model = new AlipayTradeProductCreateModel(); // 设置商品名称 model.Name = "Gold 会员"; // 设置商品描述 model.Description = "基础权益"; // 设置商品模型元数据 model.Metadata = "{\"key\":\"value\"}"; // 设置图片地址 model.Images = "[\"https://antgroup.com\"]"; // 设置营销信息 model.MarketingFeatures = "[\"16000积分\"]"; // 设置单位别名 model.UnitLabel = "积分"; // 设置跳转地址 model.Url = "https://antgroup.com"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeProductCreateResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "name":"Gold 会员", "description":"基础权益", "metadata":"{\"key\":\"value\"}", "images":"[\"https://antgroup.com\"]", "marketing_features":"[\"16000积分\"]", "unit_label":"积分", "url":"https://antgroup.com" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `product_id` | String | 必选 | 32 | 商品 ID | - | `202603230010000000000` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_product_create_response": { "code": "10000", "msg": "Success", "product_id": "202603230010000000000" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_product_create_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常。可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | --- ### 商品修改接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 商品修改接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/merchant-modify.md 商品修改 #### 接口说明 接口名称:`alipay.trade.product.modify` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 通用场景 商品修改。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.product.modify` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `product_id` | String | 必选 | 32 | 本次更新的商品 ID | - | `20260324001001` | | `name` | String | 可选 | 255 | 商品名称 | - | `Gold 会员` | | `description` | String | 可选 | 255 | 商品描述 | - | `基础权益` | | `default_price_id` | String | 可选 | 32 | 该商品默认价格 ID | - | `20260324001001` | | `metadata` | String | 可选 | 1024 | 商品元数据 | - | `{"key":"value"}` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeProductModifyRequest; import com.alipay.api.domain.AlipayTradeProductModifyModel; import com.alipay.api.response.AlipayTradeProductModifyResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeProductModify { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeProductModifyRequest request = new AlipayTradeProductModifyRequest(); AlipayTradeProductModifyModel model = new AlipayTradeProductModifyModel(); // 设置商品id model.setProductId("20260324001001"); // 设置商品名称 model.setName("Gold 会员"); // 设置商品描述 model.setDescription("基础权益"); // 设置默认价格id model.setDefaultPriceId("20260324001001"); // 设置商品元数据 model.setMetadata("{\"key\":\"value\"}"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeProductModifyResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeProductModify { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeProductModifyRequest request = new AlipayTradeProductModifyRequest(); AlipayTradeProductModifyModel model = new AlipayTradeProductModifyModel(); // 设置商品id model.ProductId = "20260324001001"; // 设置商品名称 model.Name = "Gold 会员"; // 设置商品描述 model.Description = "基础权益"; // 设置默认价格id model.DefaultPriceId = "20260324001001"; // 设置商品元数据 model.Metadata = "{\"key\":\"value\"}"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeProductModifyResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.product.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "product_id":"20260324001001", "name":"Gold 会员", "description":"基础权益", "default_price_id":"20260324001001", "metadata":"{\"key\":\"value\"}" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `product_id` | String | 必选 | 32 | 商品 ID | - | `20260324001001` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_product_modify_response": { "code": "10000", "msg": "Success", "product_id": "20260324001001" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_product_modify_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常。可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `APP_ID_NOT_MATCH` | 应用 ID 与商品所属应用不匹配 | 请检查传入的商品 ID 是否正确 | | `PRICE_NOT_EXIST` | 价格不存在 | 请检查传入的价格 ID 是否正确 | | `PRODUCT_NOT_EXIST` | 商品不存在 | 请检查传入的商品 ID 是否正确 | --- ### 价格创建接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 价格创建接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/price-create.md 价格创建 #### 接口说明 接口名称:`alipay.trade.price.create` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 通用场景 价格创建接口。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.price.create` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `unit_amount` | Number | 特殊可选 | 1000000000 | 单位金额,单位:分 | 当 custom_unit_amount 为空时必选 | `1000` | | `custom_unit_amount` | CustomUnitAmount | 特殊可选 | - | 自定义单价,当 unit_amount 为空时必选 | 当 unit_amount 为空时必选 | - | | `custom_unit_amount.enable` | Boolean | 必选 | 10 | 是否启用灵活定价,启用后可设置 preset、maximum、minimum 字段 | - | `true` | | `custom_unit_amount.preset` | Number | 可选 | 32 | 预设的自定义价格(单位:分),灵活定价开启后可设置 | - | `88888` | | `custom_unit_amount.maximum` | Number | 可选 | 32 | 可自定义的最大金额(单位:分),灵活定价开启后可设置 | - | `1000000000` | | `custom_unit_amount.minimum` | Number | 可选 | 32 | 可自定义的最小金额(单位:分),灵活定价开启后可设置 | - | `100` | | `product_id` | String | 特殊可选 | 32 | 商品 ID,通过商品创建接口获取;和product_data二选其一 | 当未传入product_data时必选 | `202603230010000006783` | | `product_data` | ProductData | 特殊可选 | - | 商品模型,可以通过该参数一并创建商品信息 | 当未传入product_id时必选 | - | | `product_data.name` | String | 必选 | 255 | 商品名称 | - | `Gold 会员` | | `product_data.description` | String | 必选 | 255 | 商品描述 | - | `基础权益` | | `product_data.metadata` | String | 可选 | 2000 | 商户需要保存在商品模型中的元数据 | - | `{"key":"value"}` | | `recurring` | RecurringConfig | 可选 | - | 循环计价配置,用于订阅等场景 | - | - | | `recurring.interval` | String | 必选 | 32 | 计价周期单位,和interval_count组合使用 | 月:`MONTH` 年:`YEAR` 日:`DAY` | `MONTH` | | `recurring.interval_count` | Number | 必选 | 32 | 计价周期间隔,和interval组合使用 | - | `1` | | `eligibility_type` | String | 可选 | 32 | 只有满足该类型的身份才可以购买。具体的枚举值待支付宝侧分配 | - | `"student"` | | `eligibility_expire_time` | String | 可选 | 32 | 满足了eligibility_type的身份购买后,失效的时间。如3d = 3天, 3m = 3月 | - | `"3d"` | | `metadata` | String | 可选 | 2000 | 商户需要保存在价格模型中的元数据 | - | `{"key":"value"}` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.ProductData; import com.alipay.api.domain.RecurringConfig; import com.alipay.api.domain.CustomUnitAmount; import com.alipay.api.request.AlipayTradePriceCreateRequest; import com.alipay.api.response.AlipayTradePriceCreateResponse; import com.alipay.api.domain.AlipayTradePriceCreateModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradePriceCreate { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePriceCreateRequest request = new AlipayTradePriceCreateRequest(); AlipayTradePriceCreateModel model = new AlipayTradePriceCreateModel(); // 设置单位金额 model.setUnitAmount(1000L); // 设置自定义单价 CustomUnitAmount customUnitAmount = new CustomUnitAmount(); customUnitAmount.setEnable(true); customUnitAmount.setMaximum(1000000000L); customUnitAmount.setPreset(88888L); customUnitAmount.setMinimum(100L); model.setCustomUnitAmount(customUnitAmount); // 设置商品id model.setProductId("202603230010000006783"); // 设置商品信息 ProductData productData = new ProductData(); productData.setMetadata("{\"key\":\"value\"}"); productData.setName("Gold 会员"); productData.setDescription("基础权益"); model.setProductData(productData); // 设置循环计价模型 RecurringConfig recurring = new RecurringConfig(); recurring.setIntervalCount(1L); recurring.setInterval("MONTH"); model.setRecurring(recurring); // 设置价格限定购买的身份类型 model.setEligibilityType("\"student\""); // 设置指定身份购买后的时效时间 model.setEligibilityExpireTime("\"3d\""); // 设置价格信息元数据 model.setMetadata("{\"key\":\"value\"}"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePriceCreateResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradePriceCreate { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePriceCreateRequest request = new AlipayTradePriceCreateRequest(); AlipayTradePriceCreateModel model = new AlipayTradePriceCreateModel(); // 设置单位金额 model.UnitAmount = 1000; // 设置自定义单价 CustomUnitAmount customUnitAmount = new CustomUnitAmount(); customUnitAmount.Enable = true; customUnitAmount.Maximum = 1000000000; customUnitAmount.Preset = 88888; customUnitAmount.Minimum = 100; model.CustomUnitAmount = customUnitAmount; // 设置商品id model.ProductId = "202603230010000006783"; // 设置商品信息 ProductData productData = new ProductData(); productData.Metadata = "{\"key\":\"value\"}"; productData.Name = "Gold 会员"; productData.Description = "基础权益"; model.ProductData = productData; // 设置循环计价模型 RecurringConfig recurring = new RecurringConfig(); recurring.IntervalCount = 1; recurring.Interval = "MONTH"; model.Recurring = recurring; // 设置价格限定购买的身份类型 model.EligibilityType = "\"student\""; // 设置指定身份购买后的时效时间 model.EligibilityExpireTime = "\"3d\""; // 设置价格信息元数据 model.Metadata = "{\"key\":\"value\"}"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePriceCreateResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "unit_amount":1000, "custom_unit_amount":{ "enable":true, "maximum":1000000000, "preset":88888, "minimum":100 }, "product_id":"202603230010000006783", "product_data":{ "metadata":"{\"key\":\"value\"}", "name":"Gold 会员", "description":"基础权益" }, "recurring":{ "interval_count":1, "interval":"MONTH" }, "eligibility_type":"\"student\"", "eligibility_expire_time":"\"3d\"", "metadata":"{\"key\":\"value\"}" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `price_id` | String | 必选 | 32 | 价格实例id | - | `202603230010000006783` | | `product_id` | String | 必选 | 32 | 本次创建的商品或请求关联的商品 ID | - | `202603230010000006783` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_price_create_response":{ "code":"10000", "msg":"Success", "price_id":"202603230010000006783", "product_id":"202603230010000006783" }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_trade_price_create_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | --- ### 价格查询接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 价格查询接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/price-query.md 价格查询 #### 接口说明 接口名称:`alipay.trade.price.query` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 适用场景 价格查询接口。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.price.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `price_id` | String | 必选 | 32 | 价格 ID | - | `202603240020000001001` | | `query_options` | String | 可选 | 32 | 查询选项,商户通过上送该参数来定制额外返回的信息字段,数组格式。枚举支持: product:商品信息 | - | `["product"]` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.response.AlipayTradePriceQueryResponse; import com.alipay.api.request.AlipayTradePriceQueryRequest; import com.alipay.api.domain.AlipayTradePriceQueryModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradePriceQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePriceQueryRequest request = new AlipayTradePriceQueryRequest(); AlipayTradePriceQueryModel model = new AlipayTradePriceQueryModel(); // 设置价格id model.setPriceId("202603240020000001001"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("product"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePriceQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradePriceQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePriceQueryRequest request = new AlipayTradePriceQueryRequest(); AlipayTradePriceQueryModel model = new AlipayTradePriceQueryModel(); // 设置价格id model.PriceId = "202603240020000001001"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("product"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePriceQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.price.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "price_id":"202603240020000001001", "query_options":[ "product" ] }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `id` | String | 必选 | 32 | 价格 ID | - | `202603240020000001001` | | `active` | Boolean | 必选 | 10 | 该价格实例是否可用 | - | `true` | | `product_id` | String | 必选 | 32 | 关联商品 ID | - | `202603240020000001001` | | `unit_amount` | Number | 特殊可选 | 100000000 | 单位金额,单位:分,当 custom_unit_amount 为空时必选 | 当 custom_unit_amount 为空时必选 | `1000` | | `custom_unit_amount` | CustomUnitAmount | 特殊可选 | - | 自定义单价,当 unit_amount 为空时必选 | 当 unit_amount 为空时必选 | - | | `custom_unit_amount.enable` | Boolean | 必选 | 10 | 是否启用灵活定价,启用后可设置 preset、maximum、minimum 字段 | - | `true` | | `custom_unit_amount.preset` | Number | 可选 | 32 | 预设的自定义价格(单位:分),灵活定价开启后可设置 | - | `88888` | | `custom_unit_amount.maximum` | Number | 可选 | 32 | 可自定义的最大金额(单位:分),灵活定价开启后可设置 | - | `1000000000` | | `custom_unit_amount.minimum` | Number | 可选 | 32 | 可自定义的最小金额(单位:分),灵活定价开启后可设置 | - | `100` | | `product` | NexusPayProduct | 可选 | - | 关联的商品信息 | - | - | | `product.id` | String | 必选 | 32 | 商品 ID | - | `20260324001001` | | `product.name` | String | 必选 | 255 | 商品名称 | - | `Gold 会员` | | `product.description` | String | 必选 | 255 | 商品描述 | - | `基础权益` | | `product.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `product.default_price_id` | String | 可选 | 32 | 商品的默认价格 ID | - | `20260324001001` | | `product.default_price` | NexusSimplePrice | 可选 | - | 默认价格信息 | - | - | | `product.default_price.id` | String | 必选 | 32 | 价格 ID | - | `20260324001001` | | `product.default_price.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `product.default_price.type` | String | 必选 | 32 | 价格类型 | 订阅:`recurring` 单次支付:`one_time` | `recurring` | | `product.default_price.unit_amount` | Number | 必选 | 32 | 单位金额,单位:分 | - | `1000` | | `product.default_price.recurring` | Recurring | 必选 | - | 订阅周期信息 | - | - | | `product.default_price.recurring.interval` | String | 可选 | 16 | 订阅周期类型,目前支持DAY跟MONTH | 月:`MONTH` 天:`DAY` | `MONTH` | | `product.default_price.recurring.interval_count` | Number | 可选 | 32 | 订阅周期数量,目前周期单位只支持月或日 | - | `1` | | `product.default_price.recurring.usage_type` | String | 可选 | 16 | 计费模式 | 固定计费:`licensed` 按量计费:`metered` | `licensed` | | `product.default_price.recurring.trial_period_days` | Number | 可选 | 32 | 试用期天数 | - | `10` | | `product.default_price.metadata` | String | 可选 | 2000 | 价格信息元数据 | - | `{"key":"value"}` | | `product.default_price.custom_unit_amount` | CustomUnitAmount | 可选 | - | 自定义单价,当 unit_amount 为空时必选 | - | - | | `product.default_price.custom_unit_amount.enable` | Boolean | 必选 | 10 | 是否启用灵活定价,启用后可设置 preset、maximum、minimum 字段 | - | `true` | | `product.default_price.custom_unit_amount.preset` | Number | 可选 | 32 | 预设的自定义价格(单位:分),灵活定价开启后可设置 | - | `88888` | | `product.default_price.custom_unit_amount.maximum` | Number | 可选 | 32 | 可自定义的最大金额(单位:分),灵活定价开启后可设置 | - | `1000000000` | | `product.default_price.custom_unit_amount.minimum` | Number | 可选 | 32 | 可自定义的最小金额(单位:分),灵活定价开启后可设置 | - | `100` | | `product.metadata` | String | 可选 | 2000 | 商品信息元数据,通过商品创建接口传入 | - | `{"key":"value"}` | | `product.gmt_create` | String | 必选 | 64 | 创建时间 | - | `2026-03-24 18:00:00` | | `type` | String | 必选 | 32 | 价格类型 | 订阅:`recurring` 单次支付:`one_time` | `recurring` | | `recurring` | RecurringConfig | 可选 | - | 循环计价配置,用于订阅等场景 | - | - | | `recurring.interval` | String | 必选 | 32 | 计价周期单位,和interval_count组合使用 | 月:`MONTH` 年:`YEAR` 日:`DAY` | `MONTH` | | `recurring.interval_count` | Number | 必选 | 32 | 计价周期间隔,和interval组合使用 | - | `1` | | `eligibility_type` | String | 可选 | 32 | 只有满足该类型的身份才可以购买。具体的枚举值待支付宝侧分配 | - | `"student"` | | `eligibility_expire_time` | String | 可选 | 32 | 满足了eligibility_type的身份购买后,失效的时间。如3d = 3天, 3m = 3月 | - | `"3d"` | | `metadata` | String | 必选 | 2000 | 商户需要保存在价格模型中的元数据 | - | `{"key":"value"}` | | `gmt_create` | String | 必选 | 64 | 创建时间 | - | `2026-03-24` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_price_query_response":{ "code":"10000", "msg":"Success", "id":"202603240020000001001", "active":true, "product_id":"202603240020000001001", "unit_amount":1000, "custom_unit_amount":{ "enable":true, "preset":88888, "maximum":1000000000, "minimum":100 }, "product":{ "id":"20260324001001", "name":"Gold 会员", "description":"基础权益", "active":true, "default_price_id":"20260324001001", "default_price":{ "id":"20260324001001", "active":true, "type":"recurring", "unit_amount":1000, "recurring":{ "interval":"MONTH", "interval_count":1, "usage_type":"licensed", "trial_period_days":10 }, "metadata":"{\"key\":\"value\"}", "custom_unit_amount":{ "enable":true, "preset":88888, "maximum":1000000000, "minimum":100 } }, "metadata":"{\"key\":\"value\"}", "gmt_create":"2026-03-24 18:00:00" }, "type":"recurring", "recurring":{ "interval":"MONTH", "interval_count":1 }, "eligibility_type":"\"student\"", "eligibility_expire_time":"\"3d\"", "metadata":"{\"key\":\"value\"}", "gmt_create":"2026-03-24" }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_trade_price_query_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `APP_ID_NOT_MATCH` | 应用 ID与价格所属应用不匹配 | 应用 ID与价格所属应用不匹配,请检查传入的价格ID是否正确 | | `PRICE_NOT_EXIST` | 价格不存在 | 请检查传入的价格ID是否正确 | --- ### 客户创建接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 客户创建接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/customer-create.md 客户创建接口,用于创建商户侧客户信息 #### 接口说明 接口名称:`alipay.trade.customer.create` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 适用场景 客户创建接口,用于创建商户侧客户信息。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.customer.create` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `name` | String | 必选 | 64 | 客户名称 | - | `张三` | | `description` | String | 可选 | 255 | 客户描述 | - | `业务客户` | | `phone` | String | 可选 | 50 | 客户手机号,和客户邮箱需至少传入1个 | - | `15011112222` | | `email` | String | 可选 | 255 | 客户邮箱,和客户手机号需至少传入1个 | - | `email@antgroup.com` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeCustomerCreateRequest; import com.alipay.api.response.AlipayTradeCustomerCreateResponse; import com.alipay.api.domain.AlipayTradeCustomerCreateModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeCustomerCreate { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCustomerCreateRequest request = new AlipayTradeCustomerCreateRequest(); AlipayTradeCustomerCreateModel model = new AlipayTradeCustomerCreateModel(); // 设置客户名称 model.setName("张三"); // 设置客户描述 model.setDescription("业务客户"); // 设置客户手机号 model.setPhone("15011112222"); // 设置客户邮箱 model.setEmail("email@antgroup.com"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCustomerCreateResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeCustomerCreate { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCustomerCreateRequest request = new AlipayTradeCustomerCreateRequest(); AlipayTradeCustomerCreateModel model = new AlipayTradeCustomerCreateModel(); // 设置客户名称 model.Name = "张三"; // 设置客户描述 model.Description = "业务客户"; // 设置客户手机号 model.Phone = "15011112222"; // 设置客户邮箱 model.Email = "email@antgroup.com"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCustomerCreateResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.customer.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "name":"张三", "description":"业务客户", "phone":"15011112222", "email":"email@antgroup.com" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `customer_id` | String | 必选 | 32 | 客户id | - | `202603230010000006783` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_customer_create_response":{ "code":"10000", "msg":"Success", "customer_id":"202603230010000006783" }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_trade_customer_create_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | --- ### 订阅创建接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 订阅创建接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-create.md 订阅场景对商户提供的创建接口 #### 接口说明 接口名称:`alipay.trade.subscription.create` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 适用场景 订阅场景对商户提供的创建接口。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.subscription.create` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trial_desc` | String | 可选 | 12 | 用于签约页展示,若不传该字段,则展示默认文案。 低价试用场景文案:"{pay_amount}元试用{trial_period_days}天";免费试用场景文案:"免费试用{trial_period_days}天 | - | `新用户免费试用` | | `trial_period_days` | Number | 可选 | 365 | 试用期天数:试用期天数设置为正整数,通常建议试用期天数3-7天 | - | `7` | | `metadata` | String | 可选 | 512 | 商户可通过此字段进行订阅信息的自定义传参,订阅生效后不可修改,将在全链路通知或查询中返回 | - | `{"key":"value"}` | | `pay_amount` | Number | 可选 | 1000000000 | 支付金额,单位分; 仅用于商户自定义金额,若传了该值,用户实际支付金额会以该值为准 | - | `100` | | `items` | SubscriptionItem | 可选 | - | 订阅项目信息 | - | - | | `items.item_id` | String | 可选 | 64 | 订阅生效后,查询接口(alipay.trade.subscription.query)或通知接口(alipay.trade.subscription.changed)返回的item_id,使用方式详见具体场景接入指南。 | - | `2026032012314` | | `items.price_id` | String | 可选 | 64 | 价格创建接口(alipay.trade.price.create)返回的价格 ID,代表本次操作的目标价格信息,使用方式详见具体场景接入指南。 | - | `202603201234567889` | | `items.quantity` | String | 可选 | 8 | 购买的商品数量,目前仅在席位商品的订阅创建(alipay.trade.subscription.create)场景按需传入该参数,使用方式详见具体场景接入指南。 | - | `10` | | `items.source_quantity` | String | 可选 | 8 | 目前仅用于席位商品的订阅修改(alipay.trade.subscription.modify)场景下指定当前已生效的订阅项中商品的数量,使用方式详见具体场景接入指南。 | - | `10` | | `items.target_quantity` | String | 可选 | 8 | 目前仅用于席位商品的订阅修改(alipay.trade.subscription.modify)场景下指定订阅项的目标商品数量,使用方式详见具体场景接入指南。 | - | `100` | | `items.coupon_id` | String | 可选 | 40 | 营销创建接口(alipay.trade.promotion.coupon.create)返回的优惠id,使用方式详见具体场景接入指南 | - | `9WJ36SEC` | | `subscribe_title` | String | 可选 | 256 | 订单标题,若无特殊需求,无需使用该字段,默认使用商品名称 | - | `订阅月会员` | | `customer_id` | String | 必选 | 64 | 客户id,客户创建接口(alipay.trade.customer.create)返回的客户id | - | `208812345678` | | `deduct_type` | String | 可选 | 32 | 有限枚举,托管扣款类型,默认为SUBSCRIBE_DEDUCT。1.SUBSCRIBE_DEDUCT:托管模式(支付宝自动扣款,默认);2.MERCHANT_DEDUCT:非托管模式(商户自助扣款) | SUBSCRIBE_DEDUCT:`SUBSCRIBE_DEDUCT` MERCHANT_DEDUCT:`MERCHANT_DEDUCT` | `SUBSCRIBE_DEDUCT` | | `extend_params` | String | 可选 | 512 | 扩展参数,用于订阅特殊能力的传参,使用方式详见具体场景接入指南 | - | `{"key":"value"}` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.SubscriptionItem; import com.alipay.api.domain.AlipayTradeSubscriptionCreateModel; import com.alipay.api.response.AlipayTradeSubscriptionCreateResponse; import com.alipay.api.request.AlipayTradeSubscriptionCreateRequest; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeSubscriptionCreate { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeSubscriptionCreateRequest request = new AlipayTradeSubscriptionCreateRequest(); AlipayTradeSubscriptionCreateModel model = new AlipayTradeSubscriptionCreateModel(); // 设置试用期描述 model.setTrialDesc("新用户免费试用"); // 设置试用期天数 model.setTrialPeriodDays(7L); // 设置订阅信息元数据 model.setMetadata("{\"key\":\"value\"}"); // 设置支付金额 model.setPayAmount(100L); // 设置订阅项目信息 List items = new ArrayList(); SubscriptionItem items0 = new SubscriptionItem(); items0.setQuantity("10"); items0.setCouponId("9WJ36SEC"); items0.setItemId("2026032012314"); items0.setPriceId("202603201234567889"); items0.setSourceQuantity("10"); items0.setTargetQuantity("100"); items.add(items0); model.setItems(items); // 设置订单标题 model.setSubscribeTitle("订阅月会员"); // 设置支付宝客户id model.setCustomerId("208812345678"); // 设置托管扣款类型 model.setDeductType("SUBSCRIBE_DEDUCT"); // 设置扩展参数 model.setExtendParams("{\"key\":\"value\"}"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeSubscriptionCreateResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeSubscriptionCreate { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeSubscriptionCreateRequest request = new AlipayTradeSubscriptionCreateRequest(); AlipayTradeSubscriptionCreateModel model = new AlipayTradeSubscriptionCreateModel(); // 设置试用期描述 model.TrialDesc = "新用户免费试用"; // 设置试用期天数 model.TrialPeriodDays = 7; // 设置订阅信息元数据 model.Metadata = "{\"key\":\"value\"}"; // 设置支付金额 model.PayAmount = 100; // 设置订阅项目信息 List items = new List(); SubscriptionItem items0 = new SubscriptionItem(); items0.Quantity = "10"; items0.CouponId = "9WJ36SEC"; items0.ItemId = "2026032012314"; items0.PriceId = "202603201234567889"; items0.SourceQuantity = "10"; items0.TargetQuantity = "100"; items.Add(items0); model.Items = items; // 设置订单标题 model.SubscribeTitle = "订阅月会员"; // 设置支付宝客户id model.CustomerId = "208812345678"; // 设置托管扣款类型 model.DeductType = "SUBSCRIBE_DEDUCT"; // 设置扩展参数 model.ExtendParams = "{\"key\":\"value\"}"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeSubscriptionCreateResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "trial_desc":"新用户免费试用", "trial_period_days":7, "metadata":"{\"key\":\"value\"}", "pay_amount":100, "items":[ { "quantity":"10", "coupon_id":"9WJ36SEC", "item_id":"2026032012314", "price_id":"202603201234567889", "source_quantity":"10", "target_quantity":"100" } ], "subscribe_title":"订阅月会员", "customer_id":"208812345678", "deduct_type":"SUBSCRIBE_DEDUCT", "extend_params":"{\"key\":\"value\"}" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `promotion_info` | String | 可选 | 1000 | 订阅创建生成的优惠信息 | - | `{"originAmount":"30.00","2026042802400000001":"{\"couponName\":\"新用户立减10元-前三次\",\"amountOff\":\"10.00\",\"couponId\":\"9WJ36SEC\"}","discountAmount":"10.00"}` | | `trial_end` | String | 可选 | 32 | 试用期结束时间,格式 yyyy-MM-dd HH:mm:ss | - | `2026-04-22 14:10:00` | | `trial_start` | String | 可选 | 32 | 试用期开始时间,格式 yyyy-MM-dd HH:mm:ss | - | `2026-04-22 14:10:00` | | `order_no` | String | 可选 | 32 | 创建订阅时生成的支付请求单号 | - | `123456789` | | `pay_amount` | Number | 可选 | 1000000000 | 支付金额,单位分 | - | `100` | | `alipay_jump_schema` | String | 可选 | 4096 | 长链,适用于跳转拉起支付宝端 | - | `alipays://platformapi/startApp?appId=60000157&orderStr=XXXXXXXXXX` | | `alipay_schema` | String | 可选 | 4096 | 短链,适用于生成二维码 | - | `[https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ](https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ)` | | `subscription_id` | String | 可选 | 64 | 订阅id,本次订阅操作生成的唯一标识 | - | `20260320123156789` | | `schema_effective_end` | String | 可选 | 32 | 签约链接有效期截止时间,格式 yyyy-MM-dd HH:mm:ss | - | `2026-05-28 16:10:00` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_subscription_create_response":{ "code":"10000", "msg":"Success", "promotion_info":"{\\\"originAmount\\\":\\\"30.00\\\",\\\"2026042802400000001\\\":\\\"{\\\\\\\"couponName\\\\\\\":\\\\\\\"新用户立减10元-前三次\\\\\\\",\\\\\\\"amountOff\\\\\\\":\\\\\\\"10.00\\\\\\\",\\\\\\\"couponId\\\\\\\":\\\\\\\"9WJ36SEC\\\\\\\"}\\\",\\\"discountAmount\\\":\\\"10.00\\\"}", "trial_end":"2026-04-22 14:10:00", "trial_start":"2026-04-22 14:10:00", "order_no":"123456789", "pay_amount":100, "alipay_jump_schema":"alipays://platformapi/startApp?appId=60000157&orderStr=XXXXXXXXXX", "alipay_schema":"https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ", "subscription_id":"20260320123156789", "schema_effective_end":"2026-05-28 16:10:00" }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_trade_subscription_create_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | --- ### 订阅查询接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 订阅查询接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-query.md 订阅场景对商户提供的查询接口 #### 接口说明 接口名称:`alipay.trade.subscription.query` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 适用场景 订阅场景对商户提供的查询接口。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.subscription.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `subscription_status` | String | 可选 | 64 | 枚举值: 未完成:INCOMPLETE 活跃:ACTIVE 未完成已过期:INCOMPLETE_EXPIRED 已取消:CANCELED | - | `ACTIVE` | | `subscription_id` | String | 可选 | 64 | 订阅id | - | `20260320123156789` | | `customer_id` | String | 必选 | 64 | 支付宝客户id | - | `202603210030100000003` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeSubscriptionQueryRequest; import com.alipay.api.response.AlipayTradeSubscriptionQueryResponse; import com.alipay.api.domain.AlipayTradeSubscriptionQueryModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeSubscriptionQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeSubscriptionQueryRequest request = new AlipayTradeSubscriptionQueryRequest(); AlipayTradeSubscriptionQueryModel model = new AlipayTradeSubscriptionQueryModel(); // 设置订阅状态 model.setSubscriptionStatus("ACTIVE"); // 设置订阅id model.setSubscriptionId("20260320123156789"); // 设置支付宝客户id model.setCustomerId("202603210030100000003"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeSubscriptionQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeSubscriptionQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeSubscriptionQueryRequest request = new AlipayTradeSubscriptionQueryRequest(); AlipayTradeSubscriptionQueryModel model = new AlipayTradeSubscriptionQueryModel(); // 设置订阅状态 model.SubscriptionStatus = "ACTIVE"; // 设置订阅id model.SubscriptionId = "20260320123156789"; // 设置支付宝客户id model.CustomerId = "202603210030100000003"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeSubscriptionQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "subscription_status":"ACTIVE", "subscription_id":"20260320123156789", "customer_id":"202603210030100000003" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `subscriptions` | Subscription | 可选 | - | 订阅详情信息 | - | - | | `subscriptions.subscription_id` | String | 可选 | 64 | 订阅id | - | `20260320123156789` | | `subscriptions.customer_id` | String | 可选 | 64 | 支付宝客户id | - | `208812345678` | | `subscriptions.subscribe_title` | String | 可选 | 256 | 订阅标题 | - | `订阅月会员` | | `subscriptions.subscription_status` | String | 可选 | 64 | 订阅状态,例如INCOMPLETE(未完成),ACTIVE(活跃),INCOMPLETE_EXPIRED(未完成已过期),CANCELED(已取消)等 | 未完成:`INCOMPLETE` 活跃:`ACTIVE` 未完成已过期:`INCOMPLETE_EXPIRED` 已取消:`CANCELED` | `ACTIVE` | | `subscriptions.current_period_start` | String | 可选 | 32 | 最近一个扣款周期开始时间 | - | `2026-02-20 14:10:00` | | `subscriptions.current_period_end` | String | 可选 | 32 | 最近一个扣款周期结束时间 | - | `2026-03-20 14:10:00` | | `subscriptions.cancel_at_period_end` | Boolean | 可选 | 10 | true - 周期结束状态生效 false - 周期结束依旧生效 | - | `true` | | `subscriptions.start_date` | String | 可选 | 32 | 订阅开始日期 | - | `2026-03-22 14:00:00` | | `subscriptions.canceled_date` | String | 可选 | 32 | 订阅取消时间 | - | `2026-03-22 14:00:00` | | `subscriptions.created` | String | 可选 | 32 | 创建时间 | - | `2026-03-20 14:10:00` | | `subscriptions.metadata` | String | 可选 | 512 | 订阅元数据,订阅创建时传入 | - | `{"key":"value"}` | | `subscriptions.items` | SubscriptionQueryItem | 可选 | - | 订阅项目信息 | - | - | | `subscriptions.items.item_id` | String | 可选 | 64 | 订阅id | - | `2026032012314` | | `subscriptions.items.quantity` | Number | 可选 | 32 | 订阅价格项目数量,单位个 | - | `1` | | `subscriptions.items.created` | String | 可选 | 32 | 创建时间 | - | `2026-03-20 14:10:00` | | `subscriptions.items.price` | NexusPayPrice | 可选 | - | 商品价格模型 | - | - | | `subscriptions.items.price.id` | String | 必选 | 32 | 价格 ID | - | `20260324001001` | | `subscriptions.items.price.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `subscriptions.items.price.type` | String | 必选 | 32 | 价格类型 | 订阅:`recurring` 单次支付:`one_time` | `recurring` | | `subscriptions.items.price.unit_amount` | String | 必选 | 16 | 单位金额,单位:分 | - | `1000` | | `subscriptions.items.price.product_id` | String | 必选 | 32 | 商品 ID | - | `202603240020000001001` | | `subscriptions.items.price.product` | NexusPayProduct | 可选 | - | 价格归属的商品模型信息 | - | - | | `subscriptions.items.price.product.id` | String | 必选 | 32 | 商品 ID | - | `20260324001001` | | `subscriptions.items.price.product.name` | String | 必选 | 255 | 商品名称 | - | `Gold 会员` | | `subscriptions.items.price.product.description` | String | 必选 | 255 | 商品描述 | - | `基础权益` | | `subscriptions.items.price.product.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `subscriptions.items.price.product.default_price_id` | String | 可选 | 32 | 商品的默认价格 ID | - | `20260324001001` | | `subscriptions.items.price.product.default_price` | NexusSimplePrice | 可选 | - | 默认价格信息 | - | - | | `subscriptions.items.price.product.default_price.id` | String | 必选 | 32 | 价格 ID | - | `20260324001001` | | `subscriptions.items.price.product.default_price.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `subscriptions.items.price.product.default_price.type` | String | 必选 | 32 | 价格类型 | 订阅:`recurring` 单次支付:`one_time` | `recurring` | | `subscriptions.items.price.product.default_price.unit_amount` | Number | 必选 | 32 | 单位金额,单位:分 | - | `1000` | | `subscriptions.items.price.product.default_price.recurring` | Recurring | 必选 | - | 订阅周期信息 | - | - | | `subscriptions.items.price.product.default_price.recurring.interval` | String | 可选 | 16 | 订阅周期类型,目前支持DAY跟MONTH | 月:`MONTH` 天:`DAY` | `MONTH` | | `subscriptions.items.price.product.default_price.recurring.interval_count` | Number | 可选 | 32 | 订阅周期数量,目前周期单位只支持月或日 | - | `1` | | `subscriptions.items.price.product.default_price.recurring.usage_type` | String | 可选 | 16 | 计费模式 | 固定计费:`licensed` 按量计费:`metered` | `licensed` | | `subscriptions.items.price.product.default_price.recurring.trial_period_days` | Number | 可选 | 32 | 试用期天数 | - | `10` | | `subscriptions.items.price.product.default_price.metadata` | String | 可选 | 2000 | 价格信息元数据 | - | `{"key":"value"}` | | `subscriptions.items.price.product.default_price.custom_unit_amount` | CustomUnitAmount | 可选 | - | 自定义单价,当 unit_amount 为空时必选 | - | - | | `subscriptions.items.price.product.default_price.custom_unit_amount.enable` | Boolean | 必选 | 10 | 是否启用灵活定价,启用后可设置 preset、maximum、minimum 字段 | - | `true` | | `subscriptions.items.price.product.default_price.custom_unit_amount.preset` | Number | 可选 | 32 | 预设的自定义价格(单位:分),灵活定价开启后可设置 | - | `88888` | | `subscriptions.items.price.product.default_price.custom_unit_amount.maximum` | Number | 可选 | 32 | 可自定义的最大金额(单位:分),灵活定价开启后可设置 | - | `1000000000` | | `subscriptions.items.price.product.default_price.custom_unit_amount.minimum` | Number | 可选 | 32 | 可自定义的最小金额(单位:分),灵活定价开启后可设置 | - | `100` | | `subscriptions.items.price.product.metadata` | String | 可选 | 2000 | 商品信息元数据,通过商品创建接口传入 | - | `{"key":"value"}` | | `subscriptions.items.price.product.gmt_create` | String | 必选 | 64 | 创建时间 | - | `2026-03-24 18:00:00` | | `subscriptions.items.price.recurring` | Recurring | 可选 | - | 仅当type=recurring时必选 | - | - | | `subscriptions.items.price.recurring.interval` | String | 可选 | 16 | 订阅周期类型,目前支持DAY跟MONTH | 月:`MONTH` 天:`DAY` | `MONTH` | | `subscriptions.items.price.recurring.interval_count` | Number | 可选 | 32 | 订阅周期数量,目前周期单位只支持月或日 | - | `1` | | `subscriptions.items.price.recurring.usage_type` | String | 可选 | 16 | 计费模式 | 固定计费:`licensed` 按量计费:`metered` | `licensed` | | `subscriptions.items.price.recurring.trial_period_days` | Number | 可选 | 32 | 试用期天数 | - | `10` | | `subscriptions.items.price.metadata` | String | 可选 | 2000 | 价格信息元数据,通过价格创建接口传入 | - | `{"key":"value"}` | | `subscriptions.items.price.gmt_create` | String | 必选 | 32 | 创建时间 | - | `1774501132425` | | `subscriptions.items.coupon_id` | String | 可选 | 40 | 优惠编码 | - | `FB28ET2Z` | | `subscriptions.items.discount_amount` | String | 可选 | 16 | 折扣优惠金额,单位分 | - | `100` | | `subscriptions.pending_items` | SubscriptionQueryPendingItem | 可选 | - | 待生效的订阅项 | - | - | | `subscriptions.pending_items.item_id` | String | 必选 | 64 | 订阅项id | - | `2026032012314` | | `subscriptions.pending_items.quantity` | String | 必选 | 8 | 订阅价格项目数量 | - | `10` | | `subscriptions.pending_items.created` | String | 必选 | 32 | 创建时间 | - | `2026-03-20 14:10:00` | | `subscriptions.pending_items.status` | String | 可选 | 64 | 订阅项状态 | 待生效:`PENDING` | `PENDING` | | `subscriptions.pending_items.period_start` | String | 必选 | 32 | 订阅项周期开始时间 | - | `2026-03-20 14:10:00` | | `subscriptions.pending_items.period_end` | String | 必选 | 32 | 订阅项周期截止时间 | - | `2026-03-20 14:10:00` | | `subscriptions.pending_items.price` | NexusPayPrice | 必选 | - | 商品价格模型 | - | - | | `subscriptions.pending_items.price.id` | String | 必选 | 32 | 价格 ID | - | `20260324001001` | | `subscriptions.pending_items.price.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `subscriptions.pending_items.price.type` | String | 必选 | 32 | 价格类型 | 订阅:`recurring` 单次支付:`one_time` | `recurring` | | `subscriptions.pending_items.price.unit_amount` | String | 必选 | 16 | 单位金额,单位:分 | - | `1000` | | `subscriptions.pending_items.price.product_id` | String | 必选 | 32 | 商品 ID | - | `202603240020000001001` | | `subscriptions.pending_items.price.product` | NexusPayProduct | 可选 | - | 价格归属的商品模型信息 | - | - | | `subscriptions.pending_items.price.product.id` | String | 必选 | 32 | 商品 ID | - | `20260324001001` | | `subscriptions.pending_items.price.product.name` | String | 必选 | 255 | 商品名称 | - | `Gold 会员` | | `subscriptions.pending_items.price.product.description` | String | 必选 | 255 | 商品描述 | - | `基础权益` | | `subscriptions.pending_items.price.product.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `subscriptions.pending_items.price.product.default_price_id` | String | 可选 | 32 | 商品的默认价格 ID | - | `20260324001001` | | `subscriptions.pending_items.price.product.default_price` | NexusSimplePrice | 可选 | - | 默认价格信息 | - | - | | `subscriptions.pending_items.price.product.default_price.id` | String | 必选 | 32 | 价格 ID | - | `20260324001001` | | `subscriptions.pending_items.price.product.default_price.active` | Boolean | 必选 | 10 | 是否可用 | - | `true` | | `subscriptions.pending_items.price.product.default_price.type` | String | 必选 | 32 | 价格类型 | 订阅:`recurring` 单次支付:`one_time` | `recurring` | | `subscriptions.pending_items.price.product.default_price.unit_amount` | Number | 必选 | 32 | 单位金额,单位:分 | - | `1000` | | `subscriptions.pending_items.price.product.default_price.recurring` | Recurring | 必选 | - | 订阅周期信息 | - | - | | `subscriptions.pending_items.price.product.default_price.recurring.interval` | String | 可选 | 16 | 订阅周期类型,目前支持DAY跟MONTH | 月:`MONTH` 天:`DAY` | `MONTH` | | `subscriptions.pending_items.price.product.default_price.recurring.interval_count` | Number | 可选 | 32 | 订阅周期数量,目前周期单位只支持月或日 | - | `1` | | `subscriptions.pending_items.price.product.default_price.recurring.usage_type` | String | 可选 | 16 | 计费模式 | 固定计费:`licensed` 按量计费:`metered` | `licensed` | | `subscriptions.pending_items.price.product.default_price.recurring.trial_period_days` | Number | 可选 | 32 | 试用期天数 | - | `10` | | `subscriptions.pending_items.price.product.default_price.metadata` | String | 可选 | 2000 | 价格信息元数据 | - | `{"key":"value"}` | | `subscriptions.pending_items.price.product.default_price.custom_unit_amount` | CustomUnitAmount | 可选 | - | 自定义单价,当 unit_amount 为空时必选 | - | - | | `subscriptions.pending_items.price.product.default_price.custom_unit_amount.enable` | Boolean | 必选 | 10 | 是否启用灵活定价,启用后可设置 preset、maximum、minimum 字段 | - | `true` | | `subscriptions.pending_items.price.product.default_price.custom_unit_amount.preset` | Number | 可选 | 32 | 预设的自定义价格(单位:分),灵活定价开启后可设置 | - | `88888` | | `subscriptions.pending_items.price.product.default_price.custom_unit_amount.maximum` | Number | 可选 | 32 | 可自定义的最大金额(单位:分),灵活定价开启后可设置 | - | `1000000000` | | `subscriptions.pending_items.price.product.default_price.custom_unit_amount.minimum` | Number | 可选 | 32 | 可自定义的最小金额(单位:分),灵活定价开启后可设置 | - | `100` | | `subscriptions.pending_items.price.product.metadata` | String | 可选 | 2000 | 商品信息元数据,通过商品创建接口传入 | - | `{"key":"value"}` | | `subscriptions.pending_items.price.product.gmt_create` | String | 必选 | 64 | 创建时间 | - | `2026-03-24 18:00:00` | | `subscriptions.pending_items.price.recurring` | Recurring | 可选 | - | 仅当type=recurring时必选 | - | - | | `subscriptions.pending_items.price.recurring.interval` | String | 可选 | 16 | 订阅周期类型,目前支持DAY跟MONTH | 月:`MONTH` 天:`DAY` | `MONTH` | | `subscriptions.pending_items.price.recurring.interval_count` | Number | 可选 | 32 | 订阅周期数量,目前周期单位只支持月或日 | - | `1` | | `subscriptions.pending_items.price.recurring.usage_type` | String | 可选 | 16 | 计费模式 | 固定计费:`licensed` 按量计费:`metered` | `licensed` | | `subscriptions.pending_items.price.recurring.trial_period_days` | Number | 可选 | 32 | 试用期天数 | - | `10` | | `subscriptions.pending_items.price.metadata` | String | 可选 | 2000 | 价格信息元数据,通过价格创建接口传入 | - | `{"key":"value"}` | | `subscriptions.pending_items.price.gmt_create` | String | 必选 | 32 | 创建时间 | - | `1774501132425` | | `subscriptions.trial_start` | String | 可选 | 32 | 试用期开始时间 | - | `2026-02-20 14:10:00` | | `subscriptions.trial_end` | String | 可选 | 32 | 试用期结束时间 | - | `2026-02-27 23:59:59` | | `subscriptions.deduct_type` | String | 可选 | 32 | 有限枚举,托管扣款类型。1.SUBSCRIBE_DEDUCT:托管模式(支付宝自动扣款,默认);2.MERCHANT_DEDUCT:非托管模式(商户自助扣款) | SUBSCRIBE_DEDUCT:`SUBSCRIBE_DEDUCT` MERCHANT_DEDUCT:`MERCHANT_DEDUCT` | `SUBSCRIBE_DEDUCT` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_subscription_query_response":{ "code":"10000", "msg":"Success", "subscriptions":[ { "subscription_id":"20260320123156789", "customer_id":"208812345678", "subscribe_title":"订阅月会员", "subscription_status":"ACTIVE", "current_period_start":"2026-02-20 14:10:00", "current_period_end":"2026-03-20 14:10:00", "cancel_at_period_end":true, "start_date":"2026-03-22 14:00:00", "canceled_date":"2026-03-22 14:00:00", "created":"2026-03-20 14:10:00", "metadata":"{\"key\":\"value\"}", "items":[ { "item_id":"2026032012314", "quantity":1, "created":"2026-03-20 14:10:00", "price":{ "id":"20260324001001", "active":true, "type":"recurring", "unit_amount":"1000", "product_id":"202603240020000001001", "product":{ "id":"20260324001001", "name":"Gold 会员", "description":"基础权益", "active":true, "default_price_id":"20260324001001", "default_price":{ "id":"20260324001001", "active":true, "type":"recurring", "unit_amount":1000, "recurring":{ "interval":"MONTH", "interval_count":1, "usage_type":"licensed", "trial_period_days":10 }, "metadata":"{\"key\":\"value\"}", "custom_unit_amount":{ "enable":true, "preset":88888, "maximum":1000000000, "minimum":100 } }, "metadata":"{\"key\":\"value\"}", "gmt_create":"2026-03-24 18:00:00" }, "recurring":{ "interval":"MONTH", "interval_count":1, "usage_type":"licensed", "trial_period_days":10 }, "metadata":"{\"key\":\"value\"}", "gmt_create":"1774501132425" }, "coupon_id":"FB28ET2Z", "discount_amount":"100" } ], "pending_items":[ { "item_id":"2026032012314", "quantity":"10", "created":"2026-03-20 14:10:00", "status":"PENDING", "period_start":"2026-03-20 14:10:00", "period_end":"2026-03-20 14:10:00", "price":{ "id":"20260324001001", "active":true, "type":"recurring", "unit_amount":"1000", "product_id":"202603240020000001001", "product":{ "id":"20260324001001", "name":"Gold 会员", "description":"基础权益", "active":true, "default_price_id":"20260324001001", "default_price":{ "id":"20260324001001", "active":true, "type":"recurring", "unit_amount":1000, "recurring":{ "interval":"MONTH", "interval_count":1, "usage_type":"licensed", "trial_period_days":10 }, "metadata":"{\"key\":\"value\"}", "custom_unit_amount":{ "enable":true, "preset":88888, "maximum":1000000000, "minimum":100 } }, "metadata":"{\"key\":\"value\"}", "gmt_create":"2026-03-24 18:00:00" }, "recurring":{ "interval":"MONTH", "interval_count":1, "usage_type":"licensed", "trial_period_days":10 }, "metadata":"{\"key\":\"value\"}", "gmt_create":"1774501132425" } } ], "trial_start":"2026-02-20 14:10:00", "trial_end":"2026-02-27 23:59:59", "deduct_type":"SUBSCRIBE_DEDUCT" } ] }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_trade_subscription_query_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | --- ### 订阅修改接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 订阅修改接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-modify.md 提供商户修改订阅信息的能力。 #### 接口说明 接口名称:`alipay.trade.subscription.modify` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 适用场景 提供商户修改订阅信息的能力。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.subscription.modify` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `extend_params` | String | 可选 | 512 | 扩展参数,用于订阅特殊能力的传参,使用方式详见具体场景接入指南 | - | `{"key":"value"}` | | `refund_amount` | Number | 可选 | 1000000000 | 取消并退款场景下使用: 不传: 系统按照时间规则计算残值作为退款金额; 自定义传入: 按商家指定的金额退款,0表示直接取消不退款; | - | `100` | | `modify_type` | String | 可选 | 64 | UPGRADE:升级,DOWNGRADE:降级, 取消:CANCEL, 取消后恢复:REVERT_CANCEL,INCREASE_QUANTITY-席位商品数量扩容,DECREASE_QUANTITY-席位商品数量缩容,如若不传则视为UPGRADE,具体使用方式详见接入指南。 | - | `UPGRADE` | | `preserve_billing_cycle` | Boolean | 可选 | 10 | 是否保持计费周期不变,当前仅用于升级场景 true:周期不变 false:重置周期,具体使用方式详见接入指南。 | - | `true` | | `pay_amount` | Number | 可选 | 1000000000 | 支付金额,单位分; 仅用于商户自定义金额,若传了该值,用户实际支付金额会以该值为准,目前仅用于普通订阅升级场景,具体使用方式详见接入指南。 | - | `100` | | `items` | SubscriptionItem | 可选 | - | 订阅项目信息 | - | - | | `items.item_id` | String | 可选 | 64 | 订阅生效后,查询接口(alipay.trade.subscription.query)或通知接口(alipay.trade.subscription.changed)返回的item_id,使用方式详见具体场景接入指南。 | - | `2026032012314` | | `items.price_id` | String | 可选 | 64 | 价格创建接口(alipay.trade.price.create)返回的价格 ID,代表本次操作的目标价格信息,使用方式详见具体场景接入指南。 | - | `202603201234567889` | | `items.quantity` | String | 可选 | 8 | 购买的商品数量,目前仅在席位商品的订阅创建(alipay.trade.subscription.create)场景按需传入该参数,使用方式详见具体场景接入指南。 | - | `10` | | `items.source_quantity` | String | 可选 | 8 | 目前仅用于席位商品的订阅修改(alipay.trade.subscription.modify)场景下指定当前已生效的订阅项中商品的数量,使用方式详见具体场景接入指南。 | - | `10` | | `items.target_quantity` | String | 可选 | 8 | 目前仅用于席位商品的订阅修改(alipay.trade.subscription.modify)场景下指定订阅项的目标商品数量,使用方式详见具体场景接入指南。 | - | `100` | | `items.coupon_id` | String | 可选 | 40 | 营销创建接口(alipay.trade.promotion.coupon.create)返回的优惠id,使用方式详见具体场景接入指南 | - | `9WJ36SEC` | | `cancel_at_period_end` | Boolean | 可选 | 10 | 是否在周期结束时取消,仅用于取消/取消后恢复订阅,其他场景无需使用。 true:CANCEL场景下传true表示在当前计费周期结束后取消订阅; false:CANCEL场景传false表示立即取消并发起退款,REVERT_CANCEL场景下需传false;具体使用方式详见接入指南。 | - | `true` | | `description` | String | 可选 | 256 | 更新描述,若无特殊需求,无需使用该字段 | - | `升级订阅` | | `subscribe_title` | String | 可选 | 256 | 订单标题,若无特殊需求,无需使用该字段,默认使用商品名称 | - | `订阅月会员` | | `subscription_id` | String | 必选 | 64 | 订阅id,订阅唯一标识 | - | `20260320123156789` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.SubscriptionItem; import com.alipay.api.response.AlipayTradeSubscriptionModifyResponse; import com.alipay.api.domain.AlipayTradeSubscriptionModifyModel; import com.alipay.api.request.AlipayTradeSubscriptionModifyRequest; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeSubscriptionModify { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeSubscriptionModifyRequest request = new AlipayTradeSubscriptionModifyRequest(); AlipayTradeSubscriptionModifyModel model = new AlipayTradeSubscriptionModifyModel(); // 设置扩展参数 model.setExtendParams("{\"key\":\"value\"}"); // 设置自定义退款金额(单位:分) model.setRefundAmount(100L); // 设置更新类型 model.setModifyType("UPGRADE"); // 设置是否保持计费周期不变 model.setPreserveBillingCycle(true); // 设置支付金额 model.setPayAmount(100L); // 设置订阅项目信息 List items = new ArrayList(); SubscriptionItem items0 = new SubscriptionItem(); items0.setQuantity("10"); items0.setCouponId("9WJ36SEC"); items0.setItemId("2026032012314"); items0.setPriceId("202603201234567889"); items0.setSourceQuantity("10"); items0.setTargetQuantity("100"); items.add(items0); model.setItems(items); // 设置是否在当前周期结束时取消订阅 model.setCancelAtPeriodEnd(true); // 设置更新描述 model.setDescription("升级订阅"); // 设置订阅标题 model.setSubscribeTitle("订阅月会员"); // 设置订阅id model.setSubscriptionId("20260320123156789"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeSubscriptionModifyResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeSubscriptionModify { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeSubscriptionModifyRequest request = new AlipayTradeSubscriptionModifyRequest(); AlipayTradeSubscriptionModifyModel model = new AlipayTradeSubscriptionModifyModel(); // 设置扩展参数 model.ExtendParams = "{\"key\":\"value\"}"; // 设置自定义退款金额(单位:分) model.RefundAmount = 100; // 设置更新类型 model.ModifyType = "UPGRADE"; // 设置是否保持计费周期不变 model.PreserveBillingCycle = true; // 设置支付金额 model.PayAmount = 100; // 设置订阅项目信息 List items = new List(); SubscriptionItem items0 = new SubscriptionItem(); items0.Quantity = "10"; items0.CouponId = "9WJ36SEC"; items0.ItemId = "2026032012314"; items0.PriceId = "202603201234567889"; items0.SourceQuantity = "10"; items0.TargetQuantity = "100"; items.Add(items0); model.Items = items; // 设置是否在当前周期结束时取消订阅 model.CancelAtPeriodEnd = true; // 设置更新描述 model.Description = "升级订阅"; // 设置订阅标题 model.SubscribeTitle = "订阅月会员"; // 设置订阅id model.SubscriptionId = "20260320123156789"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeSubscriptionModifyResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.subscription.modify&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "extend_params":"{\"key\":\"value\"}", "refund_amount":100, "modify_type":"UPGRADE", "preserve_billing_cycle":true, "pay_amount":100, "items":[ { "quantity":"10", "coupon_id":"9WJ36SEC", "item_id":"2026032012314", "price_id":"202603201234567889", "source_quantity":"10", "target_quantity":"100" } ], "cancel_at_period_end":true, "description":"升级订阅", "subscribe_title":"订阅月会员", "subscription_id":"20260320123156789" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `promotion_info` | String | 可选 | 1000 | 订阅修改时若传入优惠,生成的优惠信息 | - | `{"originAmount":"30.00","2026042802400000001":"{\"couponName\":\"新用户立减10元-前三次\",\"amountOff\":\"10.00\",\"couponId\":\"9WJ36SEC\"}","discountAmount":"10.00"}` | | `order_no` | String | 可选 | 32 | 升级订阅时生成的支付请求单号 | - | `123456789` | | `alipay_jump_schema` | String | 可选 | 4096 | 长链,适用于跳转拉起支付宝端,升级/降级/取消后撤销场景会返回 | - | `升级:alipays://platformapi/startApp?appId=60000157&orderStr=XXXXXXXXXX;降级/取消后撤销:[https://render.alipay.com/XXXXXXXXXX](https://render.alipay.com/XXXXXXXXXX)` | | `pay_amount` | Number | 可选 | 1000000000 | 支付金额,单位分 | - | `100` | | `subscription_id` | String | 可选 | 64 | 订阅id,订阅唯一标识 | - | `20260320123156789` | | `alipay_schema` | String | 可选 | 4096 | 短链,适用于生成二维码 升级/降级/取消后撤销场景会返回 | - | `[https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ](https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ)` | | `refund_order_id` | String | 可选 | 64 | 退款业务单号,取消并退款场景下生成 | - | `123456789` | | `refund_amount` | Number | 可选 | 1000000000 | 退款金额,单位分,取消并退款场景下生成 | - | `100` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_subscription_modify_response":{ "code":"10000", "msg":"Success", "promotion_info":"{\\\"originAmount\\\":\\\"30.00\\\",\\\"2026042802400000001\\\":\\\"{\\\\\\\"couponName\\\\\\\":\\\\\\\"新用户立减10元-前三次\\\\\\\",\\\\\\\"amountOff\\\\\\\":\\\\\\\"10.00\\\\\\\",\\\\\\\"couponId\\\\\\\":\\\\\\\"9WJ36SEC\\\\\\\"}\\\",\\\"discountAmount\\\":\\\"10.00\\\"}", "order_no":"123456789", "alipay_jump_schema":"升级:alipays://platformapi/startApp?appId=60000157&orderStr=XXXXXXXXXX;降级/取消后撤销:https://render.alipay.com/XXXXXXXXXX", "pay_amount":100, "subscription_id":"20260320123156789", "alipay_schema":"https://basementurl.test.alipay.net/_1bQzQBRlIPjfo4eyx5SlMJ", "refund_order_id":"123456789", "refund_amount":100 }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_trade_subscription_modify_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | --- ### 订阅产品商户消息通知 目录路径:Token Pay · AI 连续订阅 > API列表 > 个体/席位订阅 > 订阅产品商户消息通知 来源:https://aipay.alipay.com/docs/subscribe/api-list/individual-group-seat/subscription-changed.md 订阅产品商户消息通知 #### 接口说明 消息名称:`alipay.trade.subscription.changed` #### 适用场景 订阅产品商户消息通知。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `notify_id` | String | 必选 | 50 | 通知ID | `5608cccc09ddb39d41c2e3c06e3d9fejh2` | | `utc_timestamp` | String | 必选 | 13 | 消息发送时的服务端时间 | `1514210452731` | | `msg_method` | String | 必选 | 100 | 消息接口名称 | `alipay.trade.subscription.changed` | | `app_id` | String | 必选 | 20 | 消息接受方的应用id | `2014060600164699` | | `version` | String | 必选 | 5 | 版本号(1.1版本为标准消息) | `1.0或者1.1` | | `biz_content` | String | 必选 | - | 消息报文 | `参见消息属性` | | `sign` | String | 必选 | 344 | 签名 | `WcO+t3D8Kg71dTlKwN7r9Pz...` | | `sign_type` | String | 必选 | 10 | 签名类型 | `RSA2` | | `charset` | String | 必选 | 10 | 编码集,该字符集为验签和解密所需要的字符集 | `UTF-8` | #### 消息属性 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `change_type` | String | 必选 | 32 | 订阅变更类型 | 订阅已生效:`active` 订阅续费成功:`period_extend` 订阅项目升级成功/商品数量扩容成功:`item_update` 订阅已取消:`cancel` 订阅降级成功/商品数量缩容成功:`item_downgrade` 订阅取消后恢复:`item_cancel_revert` 订阅将在周期结束取消:`cancel_at_period_end` 试用期生效:`trialing` | `active` | | `change_date` | String | 可选 | 32 | 订阅变更时间 | - | `2026-03-22 21:00:00` | | `trade_no` | String | 可选 | 64 | 支付宝交易号,可根据该交易号调用支付宝交易查询接口(alipay.trade.query)进行支付明细查询 | - | `2026022276001434360514767918` | | `order_no` | String | 可选 | 64 | 创建/升级订阅时生成的支付请求单号 | - | `2026042019600065895` | | `out_trade_no` | String | 可选 | 64 | 商户侧外部单号 | - | `OUT042019600065895` | | `pay_amount` | String | 可选 | 16 | 当笔订阅的支付金额,单位分 | - | `1001` | | `subscription` | String | 可选 | 20000 | { "subscription_id":"20134141341", "subscribe_title":"", "cancel_at_period_end":true, "created":"2026-03-20 14:10:00", "subscription_status":"ACTIVE", "customer_id":"", "current_period_end":"2026-03-20 14:10:00", "canceled_date":"2026-03-22 14:00:00", "items":[ { "quantity":1, "item_id":"2026032012314", "created":"2026-03-20 14:10:00", "price":{ "gmt_create":"2026-03-26 12:58:52", "product":{ "gmt_create":"2026-03-24 18:00:00", "metadata":"{"key":"value"}", "name":"Gold ", "description":"基础", "active":true, "id":"20260", "default_price_id":"202603240" }, "metadata":"{"key":"value"}", "recurring":{ "interval_count":1, "usage_type":"licensed", "interval":"MONTH", "trial_period_days":10 }, "product_id":"202603240020000001001", "active":true, "id":"", "unit_amount":"", "type":"recurring" } } ], "current_period_start":"2026-02-20 14:10:00", "start_date":"2026-03-22 14:00:00" } | - | `订阅信息大对象,参考alipay.trade.subscription.query` | #### 触发通知示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl -X POST 'NOTIFY_URL' \ --header 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \ --data-urlencode 'charset=UTF-8' \ --data-urlencode 'biz_content={ "change_type":"active", "change_date":"2026-03-22 21:00:00", "trade_no":"2026022276001434360514767918", "order_no":"2026042019600065895", "out_trade_no":"OUT042019600065895", "pay_amount":"1001", "subscription":"订阅信息大对象,参考alipay.trade.subscription.query" }' \ --data-urlencode 'utc_timestamp=${now}' \ --data-urlencode 'sign=${sign}' \ --data-urlencode 'app_id=${appid}' \ --data-urlencode 'version=1.1' \ --data-urlencode 'sign_type=RSA2' \ --data-urlencode 'notify_id=${notify_id}' \ --data-urlencode 'msg_method=alipay.trade.subscription.changed' ``` ::: :::: #### 通知应答 | 响应报文 | 描述 | 是否重试 | 是否区分大小写 | | --- | --- | --- | --- | | success | 消息处理成功 | 否 | 否 | | fail | 消息处理失败 | 是 | 否 | #### 说明 消息服务会根据响应报文判断商户系统是否已经成功处理消息。如果HTTP同步响应报文返回 success 字符串,消息服务则认为消息已经处理成功,停止投递,如果返回 fail ,表示消息获取失败,支付宝会根据投递重试策略重新发送消息到应用网关地址; #### 投递重试策略 一般情况下,25 小时以内完成 8 次通知,除了第一次是实时投递外,后续的每次重试都会间隔一段时间,间隔频率一般是:2m、10m、10m、1h、2h、6h、15h(第二次消息投递是在第一次投递失败后的 2 分钟;第三次投递是在第二次投递失败后的 10 分钟,以此类推) --- ### 订阅营销优惠创建 目录路径:Token Pay · AI 连续订阅 > API列表 > 营销工具包 > 订阅营销优惠创建 来源:https://aipay.alipay.com/docs/subscribe/api-list/marketing-toolkit/promotion-coupon-create.md 订阅营销优惠创建 #### 接口说明 接口名称:`alipay.trade.promotion.coupon.create` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 适用场景 订阅营销优惠创建。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.promotion.coupon.create` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `request_info` | PromotionCoupon | 必选 | - | 优惠信息 | - | - | | `request_info.coupon_id` | String | 可选 | 40 | 优惠编码 | - | `5JXR5XXW` | | `request_info.name` | String | 必选 | 12 | 优惠名称 | - | `新用户10元立减` | | `request_info.amount_off` | Number | 可选 | 32 | 折扣10元金额 单位分 | - | `1000` | | `request_info.percent_off` | Number | 可选 | 32 | 折扣比例,百分比,10%含义为9折 | - | `10` | | `request_info.duration` | String | 必选 | 20 | 周期性重复类型 支持 forever(永久)、once(一次性)、repeating(重复)模式 | - | `repeating` | | `request_info.duration_in_iterations` | String | 可选 | 10 | 在接下来的3个计费周期可重复使用该优惠 | - | `3` | | `request_info.redeem_by` | String | 必选 | 32 | 优惠到期时间 | - | `2026-02-20 14:10:00` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.PromotionCoupon; import com.alipay.api.response.AlipayTradePromotionCouponCreateResponse; import com.alipay.api.request.AlipayTradePromotionCouponCreateRequest; import com.alipay.api.domain.AlipayTradePromotionCouponCreateModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradePromotionCouponCreate { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePromotionCouponCreateRequest request = new AlipayTradePromotionCouponCreateRequest(); AlipayTradePromotionCouponCreateModel model = new AlipayTradePromotionCouponCreateModel(); // 设置优惠信息 PromotionCoupon requestInfo = new PromotionCoupon(); requestInfo.setDuration("repeating"); requestInfo.setRedeemBy("2026-02-20 14:10:00"); requestInfo.setCouponId("5JXR5XXW"); requestInfo.setName("新用户10元立减"); requestInfo.setPercentOff(10L); requestInfo.setAmountOff(1000L); requestInfo.setDurationInIterations("3"); model.setRequestInfo(requestInfo); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePromotionCouponCreateResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradePromotionCouponCreate { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePromotionCouponCreateRequest request = new AlipayTradePromotionCouponCreateRequest(); AlipayTradePromotionCouponCreateModel model = new AlipayTradePromotionCouponCreateModel(); // 设置优惠信息 PromotionCoupon requestInfo = new PromotionCoupon(); requestInfo.Duration = "repeating"; requestInfo.RedeemBy = "2026-02-20 14:10:00"; requestInfo.CouponId = "5JXR5XXW"; requestInfo.Name = "新用户10元立减"; requestInfo.PercentOff = 10; requestInfo.AmountOff = 1000; requestInfo.DurationInIterations = "3"; model.RequestInfo = requestInfo; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePromotionCouponCreateResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.promotion.coupon.create&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "request_info":{ "duration":"repeating", "redeem_by":"2026-02-20 14:10:00", "coupon_id":"5JXR5XXW", "name":"新用户10元立减", "percent_off":10, "amount_off":1000, "duration_in_iterations":"3" } }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `coupon_info` | PromotionCoupon | 必选 | - | 优惠信息 | - | - | | `coupon_info.coupon_id` | String | 必选 | 40 | 优惠编码 | - | `5JXR5XXW` | | `coupon_info.name` | String | 必选 | 12 | 优惠名称 | - | `新用户10元立减` | | `coupon_info.amount_off` | Number | 可选 | 32 | 折扣10元金额 单位分 | - | `1000` | | `coupon_info.percent_off` | Number | 可选 | 32 | 折扣比例,百分比,10%含义为9折 | - | `10` | | `coupon_info.duration` | String | 必选 | 20 | 周期性重复类型 支持 forever(永久)、once(一次性)、repeating(重复)模式 | - | `repeating` | | `coupon_info.duration_in_iterations` | String | 可选 | 10 | 在接下来的3个计费周期可重复使用该优惠 | - | `3` | | `coupon_info.redeem_by` | String | 必选 | 32 | 优惠到期时间 | - | `2026-02-20 14:10:00` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_promotion_coupon_create_response":{ "code":"10000", "msg":"Success", "coupon_info":{ "coupon_id":"5JXR5XXW", "name":"新用户10元立减", "amount_off":1000, "percent_off":10, "duration":"repeating", "duration_in_iterations":"3", "redeem_by":"2026-02-20 14:10:00" } }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_trade_promotion_coupon_create_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | | `COUPON_EXIST_ALREADY` | 优惠已经存在 | 当前CouponId已经存在,请更换 | --- ### 订阅营销优惠查询 目录路径:Token Pay · AI 连续订阅 > API列表 > 营销工具包 > 订阅营销优惠查询 来源:https://aipay.alipay.com/docs/subscribe/api-list/marketing-toolkit/promotion-coupon-query.md 订阅营销优惠查询 #### 接口说明 接口名称:`alipay.trade.promotion.coupon.query` 支持第三方代理调用:本接口支持第三方开发者代用户发起调用。 #### 适用场景 订阅营销优惠查询。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.promotion.coupon.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://opendocs.alipay.com/common/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://opendocs.alipay.com/isv/10467/xldcyq) | - | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `coupon_id` | String | 可选 | 40 | 优惠编码 | - | `29XGG87G` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="cURL"} :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradePromotionCouponQueryRequest; import com.alipay.api.domain.AlipayTradePromotionCouponQueryModel; import com.alipay.api.response.AlipayTradePromotionCouponQueryResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradePromotionCouponQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePromotionCouponQueryRequest request = new AlipayTradePromotionCouponQueryRequest(); AlipayTradePromotionCouponQueryModel model = new AlipayTradePromotionCouponQueryModel(); // 设置优惠编码 model.setCouponId("29XGG87G"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePromotionCouponQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradePromotionCouponQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradePromotionCouponQueryRequest request = new AlipayTradePromotionCouponQueryRequest(); AlipayTradePromotionCouponQueryModel model = new AlipayTradePromotionCouponQueryModel(); // 设置优惠编码 model.CouponId = "29XGG87G"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradePromotionCouponQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.promotion.coupon.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "coupon_id":"29XGG87G" }' ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | - | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | - | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `coupon_list` | PromotionCoupon | 必选 | - | 优惠列表 | - | - | | `coupon_list.coupon_id` | String | 必选 | 40 | 优惠编码 | - | `5JXR5XXW` | | `coupon_list.name` | String | 必选 | 12 | 优惠名称 | - | `新用户10元立减` | | `coupon_list.amount_off` | Number | 可选 | 32 | 折扣10元金额 单位分 | - | `1000` | | `coupon_list.percent_off` | Number | 可选 | 32 | 折扣比例,百分比,10%含义为9折 | - | `10` | | `coupon_list.duration` | String | 必选 | 20 | 周期性重复类型 支持 forever(永久)、once(一次性)、repeating(重复)模式 | - | `repeating` | | `coupon_list.duration_in_iterations` | String | 可选 | 10 | 在接下来的3个计费周期可重复使用该优惠 | - | `3` | | `coupon_list.redeem_by` | String | 必选 | 32 | 优惠到期时间 | - | `2026-02-20 14:10:00` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_promotion_coupon_query_response":{ "code":"10000", "msg":"Success", "coupon_list":[ { "coupon_id":"5JXR5XXW", "name":"新用户10元立减", "amount_off":1000, "percent_off":10, "duration":"repeating", "duration_in_iterations":"3", "redeem_by":"2026-02-20 14:10:00" } ] }, "sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json {"alipay_trade_promotion_coupon_query_response":{"code":"20000","msg":"Service Currently Unavailable","sub_code":"isp.unknow-error","sub_msg":"系统繁忙"},"sign":"ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE"} ``` ::: :::: #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `SYSTEM_ERROR` | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | `INVALID_PARAMETER` | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | --- ### 统一收单交易查询接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 营销工具包 > 统一收单交易查询接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/marketing-toolkit/alipay-trade-query.md 该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态,并据此完成下一步业务逻辑 #### 接口说明 接口名称:`alipay.trade.query` 该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态,并据此完成下一步业务逻辑。 #### 适用场景 需要调用查询接口的常见情况: - 商户后台、网络、服务器等出现异常,商户系统最终未接收到支付通知。 - 调用支付接口后,返回系统错误或未知交易状态。 - 调用 `alipay.trade.cancel` 前,需要先确认支付状态。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `out_trade_no` 与 `trade_no` 二选一传入,不能同时为空。若 `trade_no` 与 `out_trade_no` 同时存在,优先使用 `trade_no` 查询。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 枚举值/说明 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_trade_no` | string | 二选一 | 64 | 订单支付时传入的商户订单号,和支付宝交易号不能同时为空 | 若与 `trade_no` 同时存在,优先取 `trade_no` | `20150320010101001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号,和商户订单号不能同时为空 | 若与 `out_trade_no` 同时存在,优先取 `trade_no` | `2014112611001004680 073956707` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "out_trade_no":"20150320010101001", "trade_no":"2014112611001004680 073956707", "query_options":[ "trade_settle_info" ] }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.response.AlipayTradeQueryResponse; import com.alipay.api.request.AlipayTradeQueryRequest; import com.alipay.api.domain.AlipayTradeQueryModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680 073956707"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("trade_settle_info"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.OutTradeNo = "20150320010101001"; // 设置支付宝交易号 model.TradeNo = "2014112611001004680 073956707"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("trade_settle_info"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.exec("alipay.trade.query", { bizContent: { out_trade_no: "20150320010101001", trade_no: "2014112611001004680+073956707", query_options: ["trade_settle_info"], }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE3w1J+POiPh...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 必选 | 64 | 支付宝交易号 | 在未生成真实交易时不返回,需要商户多次调用该接口或等待支付通知,获取最终的交易号 | `2013112011001004330000121536` | | `out_trade_no` | string | 必选 | 64 | 商家订单号 | - | `6823789339978248` | | `trade_status` | string | 必选 | 32 | 交易状态 | `WAIT_BUYER_PAY`:交易创建,等待买家付款
`TRADE_CLOSED`:未付款交易超时关闭,或支付完成后全额退款
`TRADE_SUCCESS`:交易支付成功
`TRADE_FINISHED`:交易结束,不可退款 | `TRADE_CLOSED` | | `total_amount` | price | 必选 | 11 | 交易的订单金额,单位为元,两位小数 | 该参数的值为支付时传入的 `total_amount` | `88.88` | | `buyer_user_id` | string | 必选 | 16 | 买家在支付宝的用户 ID | 新商户建议使用 `buyer_open_id` 替代该字段。对于新商户,`buyer_user_id` 字段未来计划逐步回收,存量商户可继续使用。若使用 `buyer_open_id`,请确认“应用 - 开发配置 - openid 配置管理”已启用;无该配置项时,可查看 [openid 配置申请](https://ideservice.alipay.com/cms/site/0ai9ok?pathHash=de631c06) | `2088101117955611` | | `send_pay_date` | date | 特殊可选 | 32 | 本次交易打款给卖家的时间 | - | `2014-11-27 15:45:57` | | `receipt_amount` | string | 特殊可选 | 11 | 实收金额,单位为元,两位小数 | 该金额为本笔交易中商户账户能够实际收到的金额 | `15.25` | | `buyer_open_id` | string | 特殊可选 | 128 | 买家支付宝用户唯一标识 | 详情可查看 [openid 简介](https://ideservice.alipay.com/cms/site/0ai2i6?pathHash=13dd5946) | `01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0` | | `buyer_logon_id` | string | 可选 | 100 | 买家支付宝账号 | 在未生成真实交易时不返回,需要商户多次调用该接口或等待支付通知,获取最终的用户信息 | `159****5620` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_query_response": { "code": "10000", "msg": "Success", "trade_no": "2013112011001004330000121536", "out_trade_no": "6823789339978248", "buyer_logon_id": "159****5620", "trade_status": "TRADE_CLOSED", "total_amount": "88.88", "send_pay_date": "2014-11-27 15:45:57", "buyer_pay_amount": "8.88", "invoice_amount": "12.11", "point_amount": "10", "receipt_amount": "15.25", "store_id": "NJ_S_001", "terminal_id": "NJ_T_001", "fund_bill_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21" } ], "store_name": "证大五道口店", "buyer_open_id": "01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0", "buyer_user_id": "2088101117955611", "discount_amount": "88.88", "ext_infos": "{\"action\":\"cancel\"}", "buyer_user_type": "PRIVATE", "mdiscount_amount": "88.88" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.INVALID_PARAMETER` | 参数无效 | 检查请求参数,修改后重新发起请求 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 查询的交易不存在 | 检查传入的交易号是否正确,修改后重新发起请求 | --- ### 统一收单交易查询接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 其他基础接口 > 统一收单交易查询接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/other-basic-interfaces/alipay-trade-query.md 该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态,并据此完成下一步业务逻辑 #### 接口说明 接口名称:`alipay.trade.query` 该接口提供所有支付宝支付订单的查询。商户可以通过该接口主动查询订单状态,并据此完成下一步业务逻辑。 #### 适用场景 需要调用查询接口的常见情况: - 商户后台、网络、服务器等出现异常,商户系统最终未接收到支付通知。 - 调用支付接口后,返回系统错误或未知交易状态。 - 调用 `alipay.trade.cancel` 前,需要先确认支付状态。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `out_trade_no` 与 `trade_no` 二选一传入,不能同时为空。若 `trade_no` 与 `out_trade_no` 同时存在,优先使用 `trade_no` 查询。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 枚举值/说明 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_trade_no` | string | 二选一 | 64 | 订单支付时传入的商户订单号,和支付宝交易号不能同时为空 | 若与 `trade_no` 同时存在,优先取 `trade_no` | `20150320010101001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号,和商户订单号不能同时为空 | 若与 `out_trade_no` 同时存在,优先取 `trade_no` | `2014112611001004680 073956707` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "out_trade_no":"20150320010101001", "trade_no":"2014112611001004680 073956707", "query_options":[ "trade_settle_info" ] }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.response.AlipayTradeQueryResponse; import com.alipay.api.request.AlipayTradeQueryRequest; import com.alipay.api.domain.AlipayTradeQueryModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680 073956707"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("trade_settle_info"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeQueryRequest request = new AlipayTradeQueryRequest(); AlipayTradeQueryModel model = new AlipayTradeQueryModel(); // 设置订单支付时传入的商户订单号 model.OutTradeNo = "20150320010101001"; // 设置支付宝交易号 model.TradeNo = "2014112611001004680 073956707"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("trade_settle_info"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.exec("alipay.trade.query", { bizContent: { out_trade_no: "20150320010101001", trade_no: "2014112611001004680+073956707", query_options: ["trade_settle_info"], }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE3w1J+POiPh...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 必选 | 64 | 支付宝交易号 | 在未生成真实交易时不返回,需要商户多次调用该接口或等待支付通知,获取最终的交易号 | `2013112011001004330000121536` | | `out_trade_no` | string | 必选 | 64 | 商家订单号 | - | `6823789339978248` | | `trade_status` | string | 必选 | 32 | 交易状态 | `WAIT_BUYER_PAY`:交易创建,等待买家付款
`TRADE_CLOSED`:未付款交易超时关闭,或支付完成后全额退款
`TRADE_SUCCESS`:交易支付成功
`TRADE_FINISHED`:交易结束,不可退款 | `TRADE_CLOSED` | | `total_amount` | price | 必选 | 11 | 交易的订单金额,单位为元,两位小数 | 该参数的值为支付时传入的 `total_amount` | `88.88` | | `buyer_user_id` | string | 必选 | 16 | 买家在支付宝的用户 ID | 新商户建议使用 `buyer_open_id` 替代该字段。对于新商户,`buyer_user_id` 字段未来计划逐步回收,存量商户可继续使用。若使用 `buyer_open_id`,请确认“应用 - 开发配置 - openid 配置管理”已启用;无该配置项时,可查看 [openid 配置申请](https://ideservice.alipay.com/cms/site/0ai9ok?pathHash=de631c06) | `2088101117955611` | | `send_pay_date` | date | 特殊可选 | 32 | 本次交易打款给卖家的时间 | - | `2014-11-27 15:45:57` | | `receipt_amount` | string | 特殊可选 | 11 | 实收金额,单位为元,两位小数 | 该金额为本笔交易中商户账户能够实际收到的金额 | `15.25` | | `buyer_open_id` | string | 特殊可选 | 128 | 买家支付宝用户唯一标识 | 详情可查看 [openid 简介](https://ideservice.alipay.com/cms/site/0ai2i6?pathHash=13dd5946) | `01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0` | | `buyer_logon_id` | string | 可选 | 100 | 买家支付宝账号 | 在未生成真实交易时不返回,需要商户多次调用该接口或等待支付通知,获取最终的用户信息 | `159****5620` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_query_response": { "code": "10000", "msg": "Success", "trade_no": "2013112011001004330000121536", "out_trade_no": "6823789339978248", "buyer_logon_id": "159****5620", "trade_status": "TRADE_CLOSED", "total_amount": "88.88", "send_pay_date": "2014-11-27 15:45:57", "buyer_pay_amount": "8.88", "invoice_amount": "12.11", "point_amount": "10", "receipt_amount": "15.25", "store_id": "NJ_S_001", "terminal_id": "NJ_T_001", "fund_bill_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21" } ], "store_name": "证大五道口店", "buyer_open_id": "01501o8f93I3nJAGB1jG4ONxtxV25DCN3Gec3uggnC4CJU0", "buyer_user_id": "2088101117955611", "discount_amount": "88.88", "ext_infos": "{\"action\":\"cancel\"}", "buyer_user_type": "PRIVATE", "mdiscount_amount": "88.88" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.INVALID_PARAMETER` | 参数无效 | 检查请求参数,修改后重新发起请求 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 查询的交易不存在 | 检查传入的交易号是否正确,修改后重新发起请求 | --- ### 统一收单交易退款接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 其他基础接口 > 统一收单交易退款接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/other-basic-interfaces/alipay-trade-refund.md 卖家可以通过退款接口将支付款退还给买家 #### 接口说明 接口名称:`alipay.trade.refund` 当交易发生之后一段时间内,由于买家或卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家。支付宝在收到退款请求并验证成功后,会按照退款规则将支付款按原路退回买家账号。 交易超过约定时间(签约时设置的可退款时间)的订单无法进行退款。 支付宝退款支持单笔交易分多次退款,多次退款需要提交原支付订单的订单号,并设置不同的退款请求号。一笔退款失败后重新提交时,必须保证退款请求号不变,防止重复退款。同一笔交易累计提交的退款金额不能超过原始交易总金额。 #### 注意事项 1. 同一笔交易的退款至少间隔 3 秒后发起。 2. 请严格按照接口文档中的参数接入。若传入非当前接口文档中的参数,可能造成退款失败或重复退款。 3. 该接口不可与其他退款产品混用。若商户侧同一笔退款请求已使用当前接口退款,再使用其他退款产品退款,可能造成重复退款。 4. 退款成功判断:接口返回 `fund_change=Y` 表示退款成功;`fund_change=N` 或无此字段返回时,需要通过退款查询接口进一步确认退款状态。详见[退款成功判断指导](https://ideservice.alipay.com/cms/site/01rawa)。接口中 `code=10000` 仅代表本次退款请求成功,不代表退款成功。 5. 若退款原订单涉及分账,在发起退款前,需要分账接收方在[支付宝商家平台](https://b.alipay.com/page/portal/home) > 资金管理 > 资金服务 > 分账接收设置中开启分账回退授权后,才可以正常退款。且不支持接收方为个人的分账单发起退款退分账。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.refund` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `out_trade_no` 与 `trade_no` 二选一传入,不能同时为空。两者同时存在时,优先使用 `trade_no`。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `refund_amount` | price | 必选 | 16 | 退款金额,单位为元,支持两位小数,不能大于订单金额 | 如果正向交易使用了营销,该退款金额包含营销金额。支付宝会按业务规则分配营销和买家自有资金分别退多少,默认优先退买家的自有资金 | `200.12` | | `out_trade_no` | string | 二选一 | 64 | 商户订单号,订单支付时传入,商家自定义且保证商家系统中唯一 | 与 `trade_no` 不能同时为空 | `20150320010101001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号 | 与 `out_trade_no` 不能同时为空;两者同时存在时,优先取 `trade_no` | `2014112611001004680073956707` | | `refund_reason` | string | 可选 | 256 | 退款原因说明,商家自定义 | 会在商户和用户的 PC 退款账单详情中展示 | `正常退款` | | `out_request_no` | string | 可选 | 64 | 退款请求号,标识一次退款请求,需要保证在交易号下唯一 | 部分退款时必选。同一次退款请求失败或异常后重试时,必须保证退款请求号不变,防止重复退款。支付宝会保证同样的退款请求号多次请求只退一次 | `HZ01RF001` | #### 请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.refund&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "out_trade_no":"20150320010101001", "trade_no":"2014112611001004680073956707", "refund_amount":"200.12", "refund_reason":"正常退款", "out_request_no":"HZ01RF001", "refund_goods_detail":[ { "out_sku_id":"outSku_01", "out_item_id":"outItem_01", "goods_id":"apple-01", "refund_amount":"19.50", "out_certificate_no_list":[ "202407013232143241231243243423" ] } ], "refund_royalty_parameters":[ { "amount":"0.1", "trans_in":"2088101126708402", "royalty_type":"transfer", "trans_out":"2088101126765726", "trans_out_type":"userId", "royalty_scene":"达人佣金", "trans_in_type":"userId", "trans_in_name":"张三", "desc":"分账给2088101126708402" } ], "query_options":[ "refund_detail_item_list" ], "related_settle_confirm_no":"2024041122001495000530302869" }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeRefundModel; import com.alipay.api.request.AlipayTradeRefundRequest; import com.alipay.api.response.AlipayTradeRefundResponse; import com.alipay.api.domain.RefundGoodsDetail; import com.alipay.api.domain.OpenApiRoyaltyDetailInfoPojo; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeRefund { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); AlipayTradeRefundModel model = new AlipayTradeRefundModel(); // 设置商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680073956707"); // 设置退款金额 model.setRefundAmount("200.12"); // 设置退款原因说明 model.setRefundReason("正常退款"); // 设置退款请求号 model.setOutRequestNo("HZ01RF001"); // 设置退款包含的商品列表信息 List refundGoodsDetail = new ArrayList(); RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail(); refundGoodsDetail0.setOutSkuId("outSku_01"); refundGoodsDetail0.setOutItemId("outItem_01"); refundGoodsDetail0.setGoodsId("apple-01"); refundGoodsDetail0.setRefundAmount("19.50"); List outCertificateNoList = new ArrayList(); outCertificateNoList.add("202407013232143241231243243423"); refundGoodsDetail0.setOutCertificateNoList(outCertificateNoList); refundGoodsDetail.add(refundGoodsDetail0); model.setRefundGoodsDetail(refundGoodsDetail); // 设置退分账明细信息 List refundRoyaltyParameters = new ArrayList(); OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo(); refundRoyaltyParameters0.setAmount("0.1"); refundRoyaltyParameters0.setTransIn("2088101126708402"); refundRoyaltyParameters0.setRoyaltyType("transfer"); refundRoyaltyParameters0.setTransOut("2088101126765726"); refundRoyaltyParameters0.setTransOutType("userId"); refundRoyaltyParameters0.setRoyaltyScene("达人佣金"); refundRoyaltyParameters0.setTransInType("userId"); refundRoyaltyParameters0.setTransInName("张三"); refundRoyaltyParameters0.setDesc("分账给2088101126708402"); refundRoyaltyParameters.add(refundRoyaltyParameters0); model.setRefundRoyaltyParameters(refundRoyaltyParameters); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("refund_detail_item_list"); model.setQueryOptions(queryOptions); // 设置针对账期交易 model.setRelatedSettleConfirmNo("2024041122001495000530302869"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeRefundResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeRefund { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeRefundRequest request = new AlipayTradeRefundRequest(); AlipayTradeRefundModel model = new AlipayTradeRefundModel(); // 设置商户订单号 model.OutTradeNo = "20150320010101001"; // 设置支付宝交易号 model.TradeNo = "2014112611001004680073956707"; // 设置退款金额 model.RefundAmount = "200.12"; // 设置退款原因说明 model.RefundReason = "正常退款"; // 设置退款请求号 model.OutRequestNo = "HZ01RF001"; // 设置退款包含的商品列表信息 List refundGoodsDetail = new List(); RefundGoodsDetail refundGoodsDetail0 = new RefundGoodsDetail(); refundGoodsDetail0.OutSkuId = "outSku_01"; refundGoodsDetail0.OutItemId = "outItem_01"; refundGoodsDetail0.GoodsId = "apple-01"; refundGoodsDetail0.RefundAmount = "19.50"; List outCertificateNoList = new List(); outCertificateNoList.Add("202407013232143241231243243423"); refundGoodsDetail0.OutCertificateNoList = outCertificateNoList; refundGoodsDetail.Add(refundGoodsDetail0); model.RefundGoodsDetail = refundGoodsDetail; // 设置退分账明细信息 List refundRoyaltyParameters = new List(); OpenApiRoyaltyDetailInfoPojo refundRoyaltyParameters0 = new OpenApiRoyaltyDetailInfoPojo(); refundRoyaltyParameters0.Amount = "0.1"; refundRoyaltyParameters0.TransIn = "2088101126708402"; refundRoyaltyParameters0.RoyaltyType = "transfer"; refundRoyaltyParameters0.TransOut = "2088101126765726"; refundRoyaltyParameters0.TransOutType = "userId"; refundRoyaltyParameters0.RoyaltyScene = "达人佣金"; refundRoyaltyParameters0.TransInType = "userId"; refundRoyaltyParameters0.TransInName = "张三"; refundRoyaltyParameters0.Desc = "分账给2088101126708402"; refundRoyaltyParameters.Add(refundRoyaltyParameters0); model.RefundRoyaltyParameters = refundRoyaltyParameters; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("refund_detail_item_list"); model.QueryOptions = queryOptions; // 设置针对账期交易 model.RelatedSettleConfirmNo = "2024041122001495000530302869"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeRefundResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const AlipaySdk = require("alipay-sdk").default; const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", }); const result = await alipaySdk.exec("alipay.trade.refund", { bizContent: { out_trade_no: "20150320010101001", trade_no: "2014112611001004680073956707", refund_amount: "200.12", refund_reason: "正常退款", out_request_no: "HZ01RF001", refund_goods_detail: { 0: { out_sku_id: "outSku_01", out_item_id: "outItem_01", goods_id: "apple-01", refund_amount: "19.50", out_certificate_no_list: { 0: "202407013232143241231243243423", }, }, }, refund_royalty_parameters: { 0: { amount: "0.1", trans_in: "2088101126708402", royalty_type: "transfer", trans_out: "2088101126765726", trans_out_type: "userId", royalty_scene: "达人佣金", trans_in_type: "userId", trans_in_name: "张三", desc: "分账给2088101126708402", }, }, query_options: { 0: "refund_detail_item_list", }, related_settle_confirm_no: "2024041122001495000530302869", }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoYE...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 必选 | 64 | 支付宝交易号 | - | `2013112011001004330000121536` | | `out_trade_no` | string | 必选 | 64 | 商户订单号 | - | `6823789339978248` | | `buyer_logon_id` | string | 必选 | 100 | 用户的登录 ID | - | `159****5620` | | `refund_fee` | price | 必选 | 11 | 退款总金额,单位为元 | 指该笔交易累计已经退款成功的金额 | `88.88` | | `buyer_user_id` | string | 特殊可选 | 28 | 买家在支付宝的用户 ID | 新商户建议使用 `buyer_open_id` 替代该字段。对于新商户,`buyer_user_id` 字段未来计划逐步回收,存量商户可继续使用。若使用 `buyer_open_id`,请确认“应用 - 开发配置 - openid 配置管理”已启用;无该配置项时,可查看 [openid 配置申请](https://ideservice.alipay.com/cms/site/0ai9ok?pathHash=de631c06) | `2088101117955611` | | `buyer_open_id` | string | 特殊可选 | 128 | 买家支付宝用户唯一标识 | 详情可查看 [openid 简介](https://ideservice.alipay.com/cms/site/0ai2i6?pathHash=13dd5946) | `074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5` | | `send_back_fee` | string | 特殊可选 | 11 | 本次商户实际退回金额,单位为元 | 如需获取该值,需在入参 `query_options` 中传入 `refund_detail_item_list` | `1.8` | | `fund_change` | string | 可选 | 1 | 本次退款是否发生了资金变化 | `Y` 通常表示退款成功;`N` 或无此字段时需通过退款查询接口进一步确认退款状态 | `Y` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_refund_response": { "code": "10000", "msg": "Success", "trade_no": "2013112011001004330000121536", "out_trade_no": "6823789339978248", "buyer_logon_id": "159****5620", "fund_change": "Y", "refund_fee": "88.88", "refund_detail_item_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21", "fund_type": "DEBIT_CARD" } ], "store_name": "望湘园联洋店", "buyer_user_id": "2088101117955611", "buyer_open_id": "074a1CcTG1LelxKe4xQC0zgNdId0nxi95b5lsNpazWYoCo5", "send_back_fee": "1.8", "refund_hyb_amount": "10.24", "refund_charge_info_list": [ { "refund_charge_fee": "0.01", "switch_fee_rate": "0.01", "charge_type": "trade", "refund_sub_fee_detail_list": [ { "refund_charge_fee": "0.10", "switch_fee_rate": "0.01" } ] } ], "refund_voucher_detail_list": [ { "id": "2015102600073002039000002D5O", "name": "XX超市5折优惠", "type": "ALIPAY_FIX_VOUCHER", "amount": "10.00", "merchant_contribute": "9.00", "other_contribute": "1.00", "memo": "学生专用优惠", "template_id": "20171030000730015359000EMZP0", "other_contribute_detail": [ { "contribute_type": "BRAND", "contribute_amount": "8.00" } ], "purchase_buyer_contribute": "2.01", "purchase_merchant_contribute": "1.03", "purchase_ant_contribute": "0.82" } ], "pre_auth_cancel_fee": "12.45" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_refund_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.ALLOC_AMOUNT_VALIDATE_ERROR` | 退分账金额超限 | 请调整退分账金额后重试 | | `ACQ.BUYER_ENABLE_STATUS_FORBID` | 买家状态异常 | 联系支付宝小二确认买家状态异常原因,或者联系买家进行线下退款处理 | | `ACQ.BUYER_ERROR` | 买家状态异常 | 联系支付宝小二确认买家状态异常原因,或者联系买家进行线下退款处理 | | `ACQ.BUYER_NOT_EXIST` | 买家不存在 | 买家已经注销账号,建议联系买家进行线下退款处理 | | `ACQ.CURRENCY_NOT_SUPPORT` | 退款币种不支持 | 请确认传入的退款币种是否正确 | | `ACQ.CUSTOMER_VALIDATE_ERROR` | 账户已注销或者被冻结 | 请查询账户状态:如果账户已注销,请线下处理;如果账户已冻结,请联系支付宝小二确认冻结原因 | | `ACQ.DISCORDANT_REPEAT_REQUEST` | 请求信息不一致 | 退款请求号对应的退款已经执行成功,且本次请求的退款金额与之前请求的金额不一致。请检查退款金额是否正确,或通过退款查询接口获取退款执行结果 | | `ACQ.ENTERPRISE_PAY_BIZ_ERROR` | 因公付业务异常 | 如果提示“当前交易不含企业出资”,请确认交易是否包含企业出资;如果不包含,接口入参不能指定 `enterprise_pay_info`;如果确认包含,请联系支付宝核实。如果提示“无效企业退款金额”,请检查指定的企业退款金额是否超过当前交易企业支付的金额。其他情况请联系支付宝小二 | | `ACQ.INVALID_PARAMETER` | 参数无效 | 请根据接口返回的错误信息检查请求参数,修改后重新发起请求 | | `ACQ.NOT_ALLOW_PARTIAL_REFUND` | 不支持部分退款 | 由于交易使用了特定优惠券等场景,该笔交易不支持部分退款,请进行全额退款或联系买家线下退款 | | `ACQ.ONLINE_TRADE_VOUCHER_NOT_ALLOW_REFUND` | 交易不允许退款 | 此交易中核销了购买的代金券,不允许退款,可联系买家线下退款 | | `ACQ.OVERDRAFT_AGREEMENT_NOT_MATCH` | 垫资退款接口传入模式和签约配置不一致 | 请检查垫资退款合约中的出资方式,修改合约或接口传参后重试 | | `ACQ.OVERDRAFT_ASSIGN_ACCOUNT_INVALID` | 垫资退款出资账号和商户信息不一致 | 垫资退款出资账号必须为商户名下支付宝账号,请更换出资账号后重试 | | `ACQ.REASON_TRADE_BEEN_FREEZEN` | 请求退款的交易被冻结 | 联系支付宝小二确认该笔交易的具体情况 | | `ACQ.REASON_TRADE_REFUND_FEE_ERR` | 退款金额无效 | 同一笔交易累计请求的退款金额不能大于交易总金额,请检查退款请求金额是否正确 | | `ACQ.REASON_TRADE_STATUS_INVALID` | 交易状态异常 | 查询交易,确认交易是否为支付成功状态;如是,可联系支付宝小二确认交易状态 | | `ACQ.REFUNDALLOC_UNAUTH_LIMIT` | 分账接收方未开启分账回退,退分账失败 | 请联系分账接收方在支付宝商家平台 > 资金管理 > 资金服务 > 分账接收设置中开启分账回退授权后再发起调用 | | `ACQ.REFUND_ACCOUNT_NOT_EXIST` | 退款出资账号不存在或账号异常 | 检查退款出资账号状态,账号正常后重试 | | `ACQ.REFUND_AMT_NOT_EQUAL_TOTAL` | 退款金额超限 | 请检查退款金额是否正确,请求退款金额不能大于交易总金额;如果不是全额退款,退款请求号必填,请检查是否传入退款请求号 | | `ACQ.REFUND_CHARGE_ERROR` | 退收费异常 | 请过一段时间后再重试发起退款 | | `ACQ.REFUND_FEE_ERROR` | 交易退款金额有误 | 请检查传入的退款金额是否正确 | | `ACQ.REFUND_ROYALTY_PAYEE_ACCOUNT_NOT_EXIST` | 退分账收入方账户不存在 | 请确认收入方账号是否正确,更换账号后重新发起 | | `ACQ.SELLER_BALANCE_NOT_ENOUGH` | 卖家余额不足 | 商户支付宝账户充值后重新发起退款 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 当前退款请求可能成功也可能失败。请使用相同参数再次重试,保证退款请求号和退款金额不变;如果前一次退款已经成功,接口会幂等返回成功;如果前一次未成功,接口会重试执行退款。也可通过退款查询接口查询退款执行结果,发起退款查询需保证距离退款请求大于 5 秒 | | `ACQ.TRADE_HAS_CLOSE` | 交易已关闭 | 该交易已关闭,不能再退款,请确认请求退款的交易是否未支付或已完成退款 | | `ACQ.TRADE_HAS_FINISHED` | 交易已完结 | 该交易已完结,已超过退款期限,不允许退款;建议联系买家线下退款 | | `ACQ.TRADE_NOT_ALLOW_REFUND` | 当前交易不允许退款 | 检查当前交易状态是否为交易成功状态,以及签约的退款属性是否允许退款,确认后重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 检查请求中的交易号和商户订单号是否正确,确认后重新发起 | | `ACQ.TRADE_SETTLE_ERROR` | 交易结算异常 | 请检查传入的退结算项信息是否正确;如果正确,请联系支付宝小二 | | `ACQ.TRADE_STATUS_ERROR` | 交易状态非法 | 查询交易,确认交易是否已经付款 | | `ACQ.USER_NOT_MATCH_ERR` | 交易用户不匹配 | 请联系支付宝小二处理 | --- ### 统一收单交易退款查询接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 其他基础接口 > 统一收单交易退款查询接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/other-basic-interfaces/alipay-trade-fastpay-refund-query.md 商户可使用该接口查询提交的退款请求是否执行成功。 #### 接口说明 接口名称:`alipay.trade.fastpay.refund.query` 商户可使用该接口查询自己通过 `alipay.trade.refund` 提交的退款请求是否执行成功。 #### 注意事项 1. 该接口返回码 `10000` 仅代表本次查询操作成功,不代表退款成功。当接口返回的 `refund_status` 值为 `REFUND_SUCCESS` 时,表示退款成功;否则表示退款没有执行成功。 2. 如果退款未成功,商户可以调用退款接口重试。重试时请务必保证退款请求号和退款金额一致,防止重复退款。 3. 发起退款查询接口的时间不能离退款请求时间太短,建议间隔 10 秒以上。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.fastpay.refund.query` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `trade_no` 与 `out_trade_no` 二选一传入,不能同时为空。两者同时存在时,优先使用 `trade_no`。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_request_no` | string | 必选 | 64 | 退款请求号 | 请求退款接口时传入的退款请求号;如果退款请求时未传入,则该值为创建交易时的商户订单号 | `HZ01RF001` | | `trade_no` | string | 二选一 | 64 | 支付宝交易号 | 与商户订单号不能同时为空 | `2021081722001419121412730660` | | `out_trade_no` | string | 二选一 | 64 | 商户订单号,订单支付时传入 | 与支付宝交易号不能同时为空;`trade_no`、`out_trade_no` 同时存在时,优先取 `trade_no` | `2014112611001004680073956707` | #### 请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.fastpay.refund.query&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "trade_no":"2021081722001419121412730660", "out_trade_no":"2014112611001004680073956707", "out_request_no":"HZ01RF001", "query_options":[ "refund_detail_item_list" ] }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.domain.AlipayTradeFastpayRefundQueryModel; import com.alipay.api.response.AlipayTradeFastpayRefundQueryResponse; import com.alipay.api.request.AlipayTradeFastpayRefundQueryRequest; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeFastpayRefundQuery { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest(); AlipayTradeFastpayRefundQueryModel model = new AlipayTradeFastpayRefundQueryModel(); // 设置支付宝交易号 model.setTradeNo("2021081722001419121412730660"); // 设置商户订单号 model.setOutTradeNo("2014112611001004680073956707"); // 设置退款请求号 model.setOutRequestNo("HZ01RF001"); // 设置查询选项 List queryOptions = new ArrayList(); queryOptions.add("refund_detail_item_list"); model.setQueryOptions(queryOptions); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeFastpayRefundQueryResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeFastpayRefundQuery { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeFastpayRefundQueryRequest request = new AlipayTradeFastpayRefundQueryRequest(); AlipayTradeFastpayRefundQueryModel model = new AlipayTradeFastpayRefundQueryModel(); // 设置支付宝交易号 model.TradeNo = "2021081722001419121412730660"; // 设置商户订单号 model.OutTradeNo = "2014112611001004680073956707"; // 设置退款请求号 model.OutRequestNo = "HZ01RF001"; // 设置查询选项 List queryOptions = new List(); queryOptions.Add("refund_detail_item_list"); model.QueryOptions = queryOptions; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeFastpayRefundQueryResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `code` | String | 必选 | - | 网关返回码,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `40004` | | `msg` | String | 必选 | - | 网关返回码描述,详见[公共错误码](https://ideservice.alipay.com/cms/site/02km9f) | `Business Failed` | | `sub_code` | String | 可选 | - | 业务返回码,参见具体 API 接口文档 | `ACQ.TRADE_HAS_SUCCESS` | | `sub_msg` | String | 可选 | - | 业务返回码描述,参见具体 API 接口文档 | `交易已被支付` | | `sign` | String | 必选 | - | 签名,详见[签名文档](https://ideservice.alipay.com/cms/site/02kf5q) | `DZXh8eeTuAHoY...` | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 特殊可选 | 64 | 支付宝交易号 | - | `2014112611001004680073956707` | | `out_trade_no` | string | 特殊可选 | 64 | 创建交易传入的商户订单号 | - | `20150320010101001` | | `out_request_no` | string | 特殊可选 | 64 | 本笔退款对应的退款请求号 | - | `20150320010101001` | | `total_amount` | price | 特殊可选 | 11 | 该笔退款所对应交易的订单金额,单位为元 | - | `100.20` | | `refund_amount` | price | 特殊可选 | 11 | 本次退款请求对应的退款金额,单位为元 | - | `12.33` | | `refund_status` | string | 特殊可选 | 32 | 退款状态 | `REFUND_SUCCESS`:退款处理成功。未返回该字段表示退款请求未收到或退款失败。如果退款查询发起时间早于退款时间,或距离退款发起时间太短,可能出现查询时尚未处理成功、后续又处理成功的情况,建议退款发起后间隔 10 秒以上再查询 | `REFUND_SUCCESS` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_fastpay_refund_query_response": { "code": "10000", "msg": "Success", "trade_no": "2014112611001004680073956707", "out_trade_no": "20150320010101001", "out_request_no": "20150320010101001", "total_amount": "100.20", "refund_amount": "12.33", "refund_status": "REFUND_SUCCESS", "refund_royaltys": [ { "refund_amount": "10", "royalty_type": "transfer", "result_code": "SUCCESS", "trans_out": "2088102210397302", "trans_out_email": "alipay-test03@alipay.com", "trans_in": "2088102210397302", "trans_in_email": "zen_gwen@hotmail.com", "ori_trans_out": "2088111111111111", "ori_trans_in": "2088111111111111" } ], "gmt_refund_pay": "2014-11-27 15:45:57", "refund_detail_item_list": [ { "fund_channel": "ALIPAYACCOUNT", "amount": "10", "real_amount": "11.21", "fund_type": "DEBIT_CARD" } ], "send_back_fee": "88", "deposit_back_info": { "has_deposit_back": "true", "dback_status": "S", "dback_amount": "1.01", "bank_ack_time": "2020-06-02 14:03:48", "est_bank_receipt_time": "2020-06-02 14:03:48" }, "refund_hyb_amount": "10.24", "refund_charge_info_list": [ { "refund_charge_fee": "0.01", "switch_fee_rate": "0.01", "charge_type": "trade", "refund_sub_fee_detail_list": [ { "refund_charge_fee": "0.10", "switch_fee_rate": "0.01" } ] } ], "deposit_back_info_list": [ { "has_deposit_back": "true", "dback_status": "S", "dback_amount": "1.01", "bank_ack_time": "2020-06-02 14:03:48", "est_bank_receipt_time": "2020-06-02 14:03:48" } ], "refund_voucher_detail_list": [ { "id": "2015102600073002039000002D5O", "name": "XX超市5折优惠", "type": "ALIPAY_FIX_VOUCHER", "amount": "10.00", "merchant_contribute": "9.00", "other_contribute": "1.00", "memo": "学生专用优惠", "template_id": "20171030000730015359000EMZP0", "other_contribute_detail": [ { "contribute_type": "BRAND", "contribute_amount": "8.00" } ], "purchase_buyer_contribute": "2.01", "purchase_merchant_contribute": "1.03", "purchase_ant_contribute": "0.82" } ], "pre_auth_cancel_fee": "12.45" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_fastpay_refund_query_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.ENTERPRISE_PAY_BIZ_ERROR` | 因公付业务异常 | 重新发起查询请求;如果多次重试后仍返回同样错误,请联系支付宝小二处理 | | `ACQ.INVALID_PARAMETER` | 参数无效 | 请根据接口返回的错误信息检查请求参数,修改后重新发起请求 | | `ACQ.SYSTEM_ERROR` | 系统错误 | 重新发起查询请求;如果多次重试后仍返回系统错误,请联系支付宝小二处理 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 请确认传入的外部订单号或交易号是否正确 | | `TRADE_NOT_EXIST` | 查询退款的交易不存在 | 确认交易号是否为正确的支付宝交易号,修改后重新查询 | --- ### 统一收单交易关闭接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 其他基础接口 > 统一收单交易关闭接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/other-basic-interfaces/alipay-trade-close.md 用于交易创建后,用户在一定时间内未进行支付,可调用该接口直接将未付款的交易进行关闭。 #### 接口说明 接口名称:`alipay.trade.close` 用于交易创建后,用户在一定时间内未进行支付,可调用该接口直接将未付款的交易进行关闭。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.close` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递,具体参照各产品快速接入文档 | - | #### 业务请求参数 > `trade_no` 与 `out_trade_no` 二选一传入,不能同时为空。若两者同时传入,以 `trade_no` 为准。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 二选一 | 64 | 该交易在支付宝系统中的交易流水号,最短 16 位,最长 64 位 | 与 `out_trade_no` 不能同时为空;若同时传入 `out_trade_no` 和 `trade_no`,以 `trade_no` 为准 | `2013112611001004680073956707` | | `out_trade_no` | string | 二选一 | 64 | 订单支付时传入的商户订单号 | 与支付宝交易号不能同时为空;若 `trade_no`、`out_trade_no` 同时存在,优先取 `trade_no` | `HZ0120131127001` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.close&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "trade_no":"2013112611001004680073956707", "out_trade_no":"HZ0120131127001", "operator_id":"YX01" }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeCloseRequest; import com.alipay.api.domain.AlipayTradeCloseModel; import com.alipay.api.response.AlipayTradeCloseResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeClose { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCloseRequest request = new AlipayTradeCloseRequest(); AlipayTradeCloseModel model = new AlipayTradeCloseModel(); // 设置该交易在支付宝系统中的交易流水号 model.setTradeNo("2013112611001004680073956707"); // 设置订单支付时传入的商户订单号 model.setOutTradeNo("HZ0120131127001"); // 设置商家操作员编号 id model.setOperatorId("YX01"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCloseResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeClose { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCloseRequest request = new AlipayTradeCloseRequest(); AlipayTradeCloseModel model = new AlipayTradeCloseModel(); // 设置该交易在支付宝系统中的交易流水号 model.TradeNo = "2013112611001004680073956707"; // 设置订单支付时传入的商户订单号 model.OutTradeNo = "HZ0120131127001"; // 设置商家操作员编号 id model.OperatorId = "YX01"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCloseResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::aipay-tab{key="Node.js" title="Node.js"} ```javascript const { AlipaySdk } = require("alipay-sdk"); const alipaySdk = new AlipaySdk({ appId: "<-- 请填写您的AppId,例如:2019091767145019 -->", privateKey: "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->", alipayPublicKey: "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->", gateway: "https://openapi.alipay.com/gateway.do", appAuthToken: "<-- 请填写应用授权令牌 -->", }); const result = await alipaySdk.exec("alipay.trade.close", { bizContent: { trade_no: "2013112611001004680073956707", out_trade_no: "HZ0120131127001", operator_id: "YX01", }, }); ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | ACQ.TRADE_HAS_SUCCESS | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | 交易已被支付 | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `trade_no` | string | 特殊可选 | 64 | 支付宝交易号 | - | `2013112111001004500000675971` | | `out_trade_no` | string | 特殊可选 | 64 | 创建交易传入的商户订单号 | - | `YX_001` | #### 响应示例 ::::aipay-tabs{defaultActiveKey="正常示例"} :::aipay-tab{key="正常示例" title="正常示例"} ```json { "alipay_trade_close_response": { "code": "10000", "msg": "Success", "trade_no": "2013112111001004500000675971", "out_trade_no": "YX_001" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::aipay-tab{key="异常示例" title="异常示例"} ```json { "alipay_trade_close_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ::: :::: #### 公共错误码 [前往查看公共错误码](https://ideservice.alipay.com/cms/site/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.INVALID_PARAMETER` | 参数无效 | 检查请求参数,修改后重新发起请求 | | `ACQ.REASON_ILLEGAL_STATUS` | 交易状态异常 | 确认交易状态,非待支付状态下不支持关单操作 | | `ACQ.REASON_TRADE_STATUS_INVALID` | 交易状态异常 | 确认交易状态,非待支付状态下不支持关单操作 | | `ACQ.SYSTEM_ERROR` | 系统异常 | 重新发起请求 | | `ACQ.TRADE_NOT_EXIST` | 交易不存在 | 检查传入的交易号和外部订单号是否正确,修改后重新发起 | | `ACQ.TRADE_STATUS_ERROR` | 交易状态不合法 | 检查当前交易的状态是否为等待买家付款。只有等待买家付款状态下才能发起交易关闭 | #### 触发通知类型 | 通知类型 | 描述 | 默认开启 | | --- | --- | --- | | `tradeStatus.TRADE_CLOSED` | 交易关闭 | `1` | | `tradeStatus.TRADE_SUCCESS` | 交易成功 | `0` | #### 触发通知示例 ```text https://www.merchant.com/receive_notify.htm?notify_type=trade_status_sync¬ify_id=91722adff935e8cfa58b3aabf4dead6ibe¬ify_time=2017-02-16 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&trade_no=null&app_id=null&out_trade_no=null&out_biz_no=null&buyer_logon_id=null&seller_id=null&seller_email=null&trade_status=null&total_amount=null&refund_fee=null&subject=null&body=null&gmt_create=null&gmt_payment=null&gmt_refund=null&gmt_close=null&fund_bill_list=null&receipt_amount=null&invoice_amount=null&buyer_pay_amount=null&point_amount=null&buyer_id=null ``` --- ### 统一收单交易撤销接口 目录路径:Token Pay · AI 连续订阅 > API列表 > 其他基础接口 > 统一收单交易撤销接口 来源:https://aipay.alipay.com/docs/subscribe/api-list/other-basic-interfaces/trade-cancel.md 支付交易返回失败或支付系统超时时,可调用该接口撤销交易。如果该订单用户支付失败,支付宝系统会将订单关闭;如果用户支付成功,支付宝系统会将订单资金退还给用户。 接口名称:`alipay.trade.cancel` 支付交易返回失败或支付系统超时时,可调用该接口撤销交易。如果该订单用户支付失败,支付宝系统会将订单关闭;如果用户支付成功,支付宝系统会将订单资金退还给用户。 注意:只有发生支付系统超时或支付结果未知时才可调用撤销。其他正常支付的订单如需实现相同功能,请调用申请退款 API。提交支付交易后,应先调用查询订单 API;没有明确支付结果时,再调用撤销订单 API。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.cancel` | | `format` | String | 可选 | 40 | 仅支持 JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如 `utf-8`、`gbk`、`gb2312` 等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持 `RSA2` 和 `RSA`,推荐使用 `RSA2` | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | 详见示例 | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式为 `yyyy-MM-dd HH:mm:ss` | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为 `1.0` | `1.0` | | `app_auth_token` | String | 可选 | 40 | 详见[应用授权概述](https://ideservice.alipay.com/cms/site/04h2nx) | - | | `biz_content` | String | 必选 | - | 请求参数集合。除公共参数外,所有请求参数都必须放在该参数中传递 | - | #### 业务请求参数 > `out_trade_no` 与 `trade_no` 二选一传入,不能同时为空。 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_trade_no` | string | 二选一 | 1-64 | 原支付请求的商户订单号 | 与支付宝交易号不能同时为空 | `20150320010101001` | | `trade_no` | string | 二选一 | 1-64 | 支付宝交易号 | 与商户订单号不能同时为空 | `2014112611001004680073956707` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="cURL" title="cURL"} ```bash curl 'https://openapi.alipay.com/gateway.do?charset=UTF-8&method=alipay.trade.cancel&format=json&sign=${sign}&app_id=${appid}&version=1.0&sign_type=RSA2×tamp=${now}' \ -F 'app_auth_token=${app_auth_token}' \ -F 'biz_content={ "out_trade_no":"20150320010101001", "trade_no":"2014112611001004680073956707" }' ``` ::: :::aipay-tab{key="Java" title="Java"} ```java package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.request.AlipayTradeCancelRequest; import com.alipay.api.domain.AlipayTradeCancelModel; import com.alipay.api.response.AlipayTradeCancelResponse; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeCancel { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCancelRequest request = new AlipayTradeCancelRequest(); AlipayTradeCancelModel model = new AlipayTradeCancelModel(); // 设置原支付请求的商户订单号 model.setOutTradeNo("20150320010101001"); // 设置支付宝交易号 model.setTradeNo("2014112611001004680073956707"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCancelResponse response = alipayClient.execute(request); System.out.println(response.getBody()); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ```csharp using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeCancel { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeCancelRequest request = new AlipayTradeCancelRequest(); AlipayTradeCancelModel model = new AlipayTradeCancelModel(); // 设置原支付请求的商户订单号 model.OutTradeNo = "20150320010101001"; // 设置支付宝交易号 model.TradeNo = "2014112611001004680073956707"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeCancelResponse response = alipayClient.Execute(request); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ```php setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $responseResult = $alipayClient->execute($request, null, "<-- 请填写应用授权令牌 -->", null); $responseApiName = str_replace(".","_",$request->getApiMethodName())."_response"; $response = $responseResult->$responseApiName; if(!empty($response->code)&&$response->code==10000){ echo("调用成功"); } else{ echo("调用失败"); } function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::: #### 公共响应参数 | 参数 | 类型 | 是否必选 | 描述 | 示例值 | | :--- | :--- | :--- | :--- | :--- | | code | String | 必选 | 网关返回码,[详见文档](https://opendoc.alipay.com/common/02km9f) | 40004 | | msg | String | 必选 | 网关返回码描述,[详见文档](https://opendoc.alipay.com/common/02km9f) | Business Failed | | sub_code | String | 可选 | 业务返回码,参见具体的 API 接口文档 | ACQ.TRADE_HAS_SUCCESS | | sub_msg | String | 可选 | 业务返回码描述,参见具体的 API 接口文档 | 交易已被支付 | | sign | String | 必选 | 签名,[详见文档](https://opendoc.alipay.com/common/02kf5q) | DZXh8eeTuAHoYE3w1J... | #### 业务响应参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 注意事项/枚举值 | 示例值 | | --- | --- | --- | --- | --- | --- | --- | | `out_trade_no` | string | 必选 | 64 | 商户订单号 | - | `6823789339978248` | | `retry_flag` | string | 必选 | 1 | 是否需要重试 | - | `N` | | `trade_no` | string | 可选 | 64 | 支付宝交易号 | 当发生交易关闭或交易退款时返回 | `2013112011001004330000121536` | | `action` | string | 可选 | 10 | 本次撤销触发的交易动作 | 接口调用成功且交易存在时返回。`close`:交易未支付,触发关闭交易动作,无退款;`refund`:交易已支付,触发交易退款动作;未返回:未查询到交易,或接口调用失败 | `close` | #### 响应示例 ##### 正常示例 ```json { "alipay_trade_cancel_response": { "code": "10000", "msg": "Success", "trade_no": "2013112011001004330000121536", "out_trade_no": "6823789339978248", "retry_flag": "N", "action": "close" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` ##### 异常示例 ```json { "alipay_trade_cancel_response": { "code": "20000", "msg": "Service Currently Unavailable", "sub_code": "isp.unknow-error", "sub_msg": "系统繁忙" }, "sign": "ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE" } ``` #### 公共错误码 [前往查看公共错误码](https://opendoc.alipay.com/common/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | `ACQ.CANCEL_NOT_ALLOWED` | 交易不允许撤销 | 该笔交易不支持撤销 | | `ACQ.INVALID_PARAMETER` | 参数无效 | 请求参数有误,重新检查请求后再调用撤销 | | `ACQ.REASON_TRADE_BEEN_FREEZEN` | 当前交易被冻结,不允许进行撤销 | 联系支付宝小二,确认该笔交易的具体情况 | | `ACQ.REASON_TRADE_REFUND_FEE_ERR` | 退款金额无效 | 请确认交易是否已经发起过退款,已退款场景下不能再发起撤销 | | `ACQ.SELLER_BALANCE_NOT_ENOUGH` | 商户的支付宝账户中无足够的资金进行撤销 | 商户支付宝账户充值后重新发起撤销 | | `ACQ.SYSTEM_ERROR` | 系统异常 | 请过一段时间后重试 | | `ACQ.TRADE_CANCEL_TIME_OUT` | 超过撤销时间范围 | 交易超过撤销时间范围,可使用退款接口发起交易退款 | | `ACQ.TRADE_HAS_FINISHED` | 交易已经完结 | 交易已完结状态下不允许退款 | | `AQC.SYSTEM_ERROR` | 系统错误 | 请使用相同参数再次调用 | --- ## Agent Pay · Agent支付 ### Agent Pay 智能体支付 目录路径:Agent Pay · Agent支付 > 产品与 Skill 介绍 > Agent Pay 智能体支付 来源:https://aipay.alipay.com/products/agent-pay.md 连接智能体、用户与商品服务。Agent 在用户授权下完成下单、支付与凭证回传。 #### Agent Pay 智能体支付。连接智能体、用户与商品服务。Agent 在用户授权下完成下单、支付与凭证回传。 ##### 办公、移动与新终端智能体支付 支持 PC、手机与智能设备,适配本地 Agent 与云端 Agent 的交互流程。 ###### [办公智能体支付]() 面向本地与云端办公智能体的支付解决方案,让 Agent 在用户授权下完成下单、支付与凭证回传。 给你的办公智能体一个 AI 钱包,让 AI 帮你下单付款,一句话完成。 [阅读 Markdown]() ###### [移动智能体支付]() 面向智能体与 AI 终端的原生支付解决方案。把支付能力嵌入对话与场景流。 即时支付:用户逐笔确认。委托任务:用户预先设定金额、频次与条件,智能体在授权边界内执行支付。 [阅读 Markdown]() ###### [新终端智能体支付]() 面向智能眼镜、智能耳机、具身智能设备等新一代 AI 终端的原生支付解决方案。看一下、说一声就能完成支付。 产品目前处于定向邀请试运营阶段,面向符合要求的企业级 AI 终端设备厂商开放。 [阅读 Markdown]() ##### 支付,自然发生在对话中 Agent 在用户授权下完成下单、支付与凭证回传。 - [办公智能体支付演示]():智能体识别需求并发起订单,用户授权后完成支付,结果自动回传智能体继续履约。[联系销售]()。 - [移动智能体支付演示]():移动智能体连接商品与服务,用户在熟悉的系统界面中确认订单并完成授权。[查看接入文档]()。 - [新终端智能体支付演示]():看一下支付(识别金额、虹膜核身、点头支付)与说一下支付(说出需求、确认订单、确认支付)。定向邀请试运营,面向符合要求的企业级 AI 终端设备厂商。[联系销售]()。 ##### 从“能聊、能查”升级为“能成交” 支付能力不只是一个结果页,而是一条从意图确认到履约的安全闭环。 - 安全可控:每笔交易都需用户授权,支付宝安全风控识别意图,确保交易符合用户预期。 - 一句话支付:AI 原生的支付体验,用户在对话中确认,智能体继续完成任务。 - 多端适配:支持 PC、手机与智能设备,适配本地 Agent 与云端 Agent 的交互流程。 - 安全保障:由支付宝提供技术支持与账户安全保障,支付结果可靠回传。 ##### 连接智能体平台与商品服务 办公、移动与新终端智能体通过 Agent Pay(智能体支付 / AI 钱包)连接商品与服务供给。 - 办公智能体:千问办公、豆包工作、WorkBuddy,支持本地端与云端智能体。 - 移动智能体:千问 APP、OPPO 小布、小米小爱,适配手机与智能设备的原生交互。 - 新终端智能体:智能眼镜、智能耳机、具身智能设备,定向邀请试运营。 - 数字资源服务商家:API、MCP、Skill、内容、算力,让智能体按需购买并按量付费。[了解按量付费]()。 - 商品与生活服务商家:零售、餐饮、出行、本地生活,让智能体帮助用户购买商品与服务。[商品和生活服务商户接入智能体平台]()。 以下四步说明交易过程,是上述连接关系的补充。 ##### 从用户意图,到交易完成 支付宝 AI 付将意图、授权、支付与凭证串成完整交易链路,覆盖办公、移动与新终端智能体。 1. 识别需求:智能体识别需求并发起订单。 2. 用户授权:即时确认,或预先设定金额、频次与条件。 3. 完成支付:智能体在授权边界内执行支付。 4. 结果回传:结果自动回传智能体继续履约。 ##### 与支付宝共同构建面向未来的智能体商业网络 让每一个 Agent 都能拥有自己的 AI 钱包,让商品、服务和消费需求在可信的交易网络中自然连接。 - 1 亿用户规模愿景:服务更广泛的 AI 原生消费需求。 - 3 亿交易规模愿景:以支付宝 AI 付连接每一次可信成交。 - 全场景商业覆盖:贯通数字服务、实体商品与生活服务。 - 共建开放生态:携手智能体平台与商家拓展新增长。 ##### 为你的智能体接入支付 办公智能体安装 Skill,移动智能体查看接入文档,新终端提交接入申请。 - 办公智能体:将安装指令发给你的智能体,安装 Skill、开通支付能力,并完成支付宝账户授权绑定。指令:`帮我安装开通支付宝钱包的能力npx -y @alipay/agent-payment@latest install,安装后帮我开启支付宝支付功能`。 - 移动智能体:查看智能体平台接入文档,将支付能力嵌入对话与场景流。[智能体平台接入文档]()。 - 新终端智能体:定向邀请试运营,面向符合要求的企业级 AI 终端设备厂商。[申请新终端接入]()。 --- ### 办公智能体支付 目录路径:Agent Pay · Agent支付 > 产品与 Skill 介绍 > 办公智能体支付 来源:https://aipay.alipay.com/products/office-agent-pay.md 面向本地与云端办公智能体的支付解决方案,让 Agent 在用户授权下完成下单、支付与凭证回传。 所属产品:[Agent Pay]() 给你的办公智能体一个 AI 钱包,让 AI 帮你下单付款,一句话完成。 #### 让智能体帮你完成第一笔支付 在线体验由百宝箱提供支持。[登录后体验原生 Agent 支付]() · [打开百宝箱官网](https://www.tbox.cn/)。 #### 在你常用的智能体里体验支付 将体验指令发给下方任一已支持的智能体,在对话中体验 Agent 支付流程。 `npx -y @alipay/agent-payment@latest install-experience,执行命令安装 skill,我的星座是「天秤座」,请给我今日运势。` 支持的智能体持续更新。目前包括 ArkClaw、AutoClaw、百炼Claw、ChatGPT、Claude、Claude Code、Cline、Codex CLI、CoPaw、CowAgent、Coze、Cursor、DeepSeek Harness、DeerFlow、DTClaw、HappyCapy、Hermes Agent、JVSClaw、KimiClaw、MaxClaw、nanobot、OpenClaw、Pi Agent、QClaw、QwenWork、Trae、WorkBuddy。 #### 每一次代办,都有授权与保障 从识别支付意图到用户授权,让智能体在办公任务中完成付款,并由支付宝提供安全保障。 - 安全可控:每笔交易都需用户授权,支付宝安全风控识别意图,确保交易符合用户预期。 - 一键支付:AI 原生的支付体验,一句话完成 AI 帮你下单付款。 - 办公场景适配:支持本地与云端办公智能体,在任务上下文中完成支付。 - 支付宝安全保障:官方提供技术支持,账户安全 7×24 小时守护。 #### 用真实支付任务检验智能体 AgentPay Benchmark 覆盖钱包开通、订单支付与付费资源获取,对比不同 Agent 与模型的端到端成功率、体验耗时和 Token 消耗。 - 最高端到端成功率:Claude Code(Kimi-K3),100%。 - 最短体验耗时:OpenClaw(Kimi-K3),56.9s。 - 最低已提供输出 Token:OpenClaw(Kimi-K3),1.2K。 | Agent名称 | 端到端成功率 | 模型 | 体验耗时 | 输入token | 输出token | | --- | --- | --- | --- | --- | --- | | Claude Code | 100% | Kimi-K3 | 117.6s | 15.5K | 6.1K | | OpenClaw | 94.7% | Kimi-K3 | 56.9s | 39.8K | 1.2K | | 千问办公 | 94.1% | auto | 60.4s | — | — | | WorkBuddy | 93.8% | Kimi-K3 | 78.4s | 230.03K | 1.27K | | 豆包工作 | 89% | auto | 158.3s | — | — | | Dumate | 84.4% | auto | 132.0s | 572.75K | 5.06K | — 表示框架暂时无法直接获取 Token 准确消耗数据,不代表零消耗。排序仅比较可获取的数据。 模型选择:支持更换模型的 Agent 框架统一使用 Kimi-K3 评测;不支持更换模型的框架使用其自动模型选择模式(auto)。 当前结果基于20260904定格的 Agent 框架版本。 #### 从工作所需到日常所用 购买加油包、获取付费资料、点一杯咖啡或部署应用,让智能体把任务中的购买与付款一并完成。 #### 让你的商品与服务被智能体购买 商品和生活服务接入商品服务链路,API、MCP 与 Skill 接入按量付费链路,按你的业务类型选择对应文档。 - [商品和生活服务商户接入智能体平台](https://aipay.alipay.com/docs/agent-pay/merchant-to-agent-platform.html) - [查看 AI 按量服务文档](https://aipay.alipay.com/docs/ai-receive/MACHINE_PAY.html) --- ### 移动智能体支付 目录路径:Agent Pay · Agent支付 > 产品与 Skill 介绍 > 移动智能体支付 来源:https://aipay.alipay.com/products/mobile-agent-pay.md 面向智能体与 AI 终端的原生支付解决方案,把支付能力嵌入对话与场景流。 所属产品:[Agent Pay]() 让 AI 在明确授权下,替你完成每一次交易。 面向智能体与 AI 终端的原生支付解决方案。把支付能力嵌入对话与场景流。 [智能体平台接入文档]() #### 两种支付方式:即时确认,或提前委托 智能体支付既支持用户当下确认的即时交易,也支持在明确条件、额度和期限内的委托任务。 ##### 即时支付 单次授权,现场确认 用户在对话中实时发起交易,每笔订单独立授权并完成身份确认。 ###### 语音点餐 AI 完成选品和下单,用户在支付环节核验并确认,交易完成后服务立即启动。 ##### 委托任务 条件触发,授权内执行 用户预先设定金额、频次与条件,智能体在授权边界内执行支付。 ###### 自动监控抢票 用户预先设定日期、席别与价格上限;满足条件时,智能体在授权边界内完成任务。 #### 让智能发生,也让每一笔资金可控 把自然语言的便捷与金融级安全放进同一条交易链路。 ##### 意图即交易 智能体在自然对话中识别购物意图,把商品咨询、方案确认与支付衔接在同一上下文。 ##### 人机协同确权 AI 辅助决策,用户最终确认;敏感环节由支付宝安全核验,避免指令越权。 ##### 凭证化授权 智能体仅获得受控凭证,不接触支付敏感信息;金额、频次与有效期均可设定。 ##### 多终端适配 覆盖移动应用、智能座舱、智能眼镜与具身智能设备,提供一致的支付体验。 #### 支付,始终由用户掌控 从当面确认到预先委托,支付始终在用户知情、授权与可控的边界内完成。 ##### 对话中确认 安全完成支付 智能体识别用户需求并完成下单,用户核对订单后确认支付,交易结果自动回传至当前对话。 - 智能体内完成选品与下单 - 用户逐笔确认,支付意图清晰 - 支付与签约结果实时回传 ##### 一次明确授权,按约完成任务 用户预先确认任务范围、金额与有效期,智能体仅在授权条件满足时执行支付,并持续同步执行状态。 - 任务、金额与期限逐项授权 - 满足触发条件后自动执行 - 授权状态与任务结果随时可查 #### 合作客户 连接智能终端、智能平台与消费场景,共同拓展智能体支付体验。 智能终端 ##### OPPO 小布 智能终端 ##### 小米小爱 智能终端 ##### HONOR 荣耀 智能平台 ##### 千问 APP 智能体 ##### 阶跃STEPX 商户 ##### luckin coffee 瑞幸 品牌名称仅用于合作客户展示,排序不分先后。 #### 为你的 Agent 接入支付能力 面向 Agent 平台方,让你的智能体在任务中完成支付。产品目前处于定向邀请试运营阶段,面向符合要求的企业级 AI 应用开放。 01 ##### 企业主体 使用支付宝企业账号,并完成真实经营信息验证。 02 ##### 智能体资料 准备清晰的 Agent 名称、官方头像与实际服务场景。 03 ##### 定向申请 联系支付宝行业运营经理,完成场景沟通与接入申请。 [智能体平台接入文档]() · [留下联系方式]() 当前阶段免费,后续计费方式以正式通知为准。 #### 让你的商品与服务被 Agent 购买 面向商品和生活服务商家,让用户通过智能体完成购买。 [商品和生活服务商户接入智能体平台]() --- ### 移动端智能体支付 目录路径:Agent Pay · Agent支付 > 移动端智能体支付 来源:https://aipay.alipay.com/docs/agent-pay/mobile-agent-pay.md 移动端智能体如何接入支付宝支付 完成 [接入准备](https://opendocs.alipay.com/pre-open/0h6n92?referPath=0h6n93_67a31294) 后,商家/服务商可根据接入指南指引快速接入 **智能体支付** 产品。 **说明:** + **智能体支付** 仅支持自研商家/服务商通过 [自研应用](https://opendocs.alipay.com/common/02bijh#%E8%87%AA%E7%A0%94%E6%9C%8D%E5%8A%A1%E5%9E%8B%E5%BA%94%E7%94%A8) 或 [第三方应用](https://opendocs.alipay.com/common/02bijh#%E4%B8%89%E6%96%B9%E6%9C%8D%E5%8A%A1%E5%9E%8B%E5%BA%94%E7%94%A8) 代调用(传入 `app_auth_token`)方式,调用 API 接入。 + **智能体支付** 产品暂不支持沙箱调试。 本文用于说明 智能体平台 如何接入支付宝智能体支付产品 #### 整体交互流程图 ::aipay-image{src="https://mass.alipay.com/aipay_assets/afts/file/wEKHTZp1AiMAAAAATyAAAAgAeoh5AQJr" width="100%"} 以下对重点步骤做简要说明: + **阶段一 下单阶段**:用户在 智能体平台 发起购买意图,智能体平台 将用户意图提交至 商家服务端,由商家服务端调用支付宝发起**APP支付**(alipay.trade.order.prepay),商家将 APP支付 预下单号返回给智能体平台。 + **阶段二 智能体支付阶段**:由智能体平台发起加签(alipay.trade.agent.pay),获取orderStr,再通过orderStr唤起支付宝客户端SDK,发起支付。 + **阶段三 异步通知阶段**:支付成功后,支付宝服务端将最终支付结果异步通知给 智能体平台。 **注意:** 当前只支持APP支付,商家需要集成alipay.trade.order.prepay接口。其他收单产品如需支持,请联系对应的支付宝行业运营经理进行咨询与申请。 #### 智能体支付流程 ##### 智能体平台接入支付 + 前置步骤:已签约 **智能体代理支付** 产品。 + 智能体支付加签:智能体平台调用 [alipay.trade.agent.pay]() 加签接口,获取 orderStr 用于唤起支付宝客户端SDK。 + 客户端接入:智能体平台 传入 orderStr 唤起支付宝APP推进支付。详细接入文档如下:[产品接入指南 - 支付宝Agent支付文档](https://aipay.alipay.com/docs/vibe-pay/mobile-app-pay/app-pay-integration-guide-new.html#%E5%AE%A2%E6%88%B7%E7%AB%AF%E6%8E%A5%E5%85%A5) ##### 智能体平台处理支付结果 支付成功后,异步通知发送到 alipay.trade.agent.pay 加签时入参的公共参数 notify_url 地址中,未设置该参数则不触发异步。通知参数及规则详见 [异步通知支付成功结果](https://opendocs.alipay.com/open/204/105301) 。 --- ### 移动端智能体支付成功异步消息通知 目录路径:Agent Pay · Agent支付 > 移动端智能体支付成功异步消息通知 来源:https://aipay.alipay.com/docs/agent-pay/payment-notify.md 移动端智能体支付成功异步消息通知 在支付成功后,支付宝通过 **From 蚂蚁消息**异步通知手机厂商,由手机厂商更新并管理整体订单状态。接收与验签方式参考[《From 蚂蚁消息服务使用》](https://opendocs.alipay.com/common/02km9j)。 #### 配置异步通知地址 在请求[alipay.trade.agent.pay](https://aipay.alipay.com/docs/agent-pay/api-list/agent-pay.html) 时**必须**配置请求公参:`notifyUrl` (异步通知地址) ```groovy //Java版: request.setNotifyUrl("商户自己的notify_url地址"); //PHP版: $request->setNotifyUrl("商户自己的notify_url地址"); //.net版: request.SetNotifyUrl("商户自己的notify_url地址"); //node.js版: formData.addField('notifyUrl', '商户自己的notify_url地址'); //Python版: request.notify_url = "商户自己的notify_url地址" ``` #### 接收 POST 请求 手机厂商需要提供一个可被支付宝访问的应用网关地址。支付宝以 `POST` 方式发送通知,请按 `application/x-www-form-urlencoded` 表单解析请求正文,不要直接按 JSON 请求体解析。 请求正文示例(`sign` 的具体值省略): ```latex charset=UTF-8&biz_content=%7B...%7D&utc_timestamp=1786345479770&sign={URL编码后的RSA2签名值}&app_id=2021007194668012&version=1.1&sign_type=RSA2¬ify_id=2026081000262150439010154745911788&msg_method=alipay.aipay.agentpay.renderinfo.notify ``` 本消息需要重点处理以下参数: | 参数 | 说明 | | --- | --- | | `biz_content` | 通知业务数据。表单 URL 解码后为 JSON 字符串,验签通过后再解析。 | | `msg_method` | 消息接口标识。本场景固定为 `alipay.aipay.agentpay.renderinfo.notify`。 | | `notify_id` | 消息通知唯一标识,用于幂等处理。 | | `charset` | 验签字符集,本示例为 `UTF-8`。 | | `sign_type` | 签名算法,本示例为 `RSA2`。 | | `sign` | 支付宝对通知参数生成的签名。 | #### 验签与消息处理 1. 将表单参数解析为字符串键值对,保留 URL 解码后的原始参数值;在验签完成前,不要重新序列化或修改 `biz_content`。 2. 标准 From 蚂蚁消息验签时,移除 `sign` 和 `sign_type`,将其余参数按参数名的字母顺序排序,并以 `参数名=参数值` 的形式使用 `&` 连接。 3. 使用报文中的 `charset`、`sign_type` 和支付宝公钥验证 `sign`。Java 接入可使用支付宝服务端 SDK 的 `AlipaySignature#getSignCheckContentV1` 和 `AlipaySignature#rsaCheck`。 4. 验签通过后,确认 `msg_method`,解析 `biz_content`,更新订单状态和支付结果卡片。 5. 建议通过`passback_params` 透传平台内部订单号进行消息处理幂等控制。同一个订单已处理成功时,不要重复执行业务逻辑,直接返回 `success`。 基于上述示例请求,移除 `sign`、`sign_type` 并排序后的待验签字符串如下: ```latex app_id=2021007194668012&biz_content={"agent_order_dto":{"amount":"1.00","seller_name":"DEVBTCONE","discount_amount":"0.00","actual_amount":"1.00","out_shake_no":"20260810008282150358840000078279","pay_time":"2026-08-10 15:04:38"},"alipay_brand_dto":{"icon_url":"https://mdn.alipayobjects.com/huamei_5fajmi/afts/img/ev8ySJTC13QAAAAAQKAAAAgADlahAQFr/original","title":"支付宝AI支付","content":"24h守护你的资金安全"}}&charset=UTF-8&msg_method=alipay.aipay.agentpay.renderinfo.notify¬ify_id=2026081000262150439010154745911788&utc_timestamp=1786345479770&version=1.1 ``` #### biz_content 格式 ```json { "agent_order_dto": { "amount": "1.00", "seller_name": "DEVBTCONE", "discount_amount": "0.00", "actual_amount": "1.00", "out_shake_no": "20260810008282150358840000078279", "pay_time": "2026-08-10 15:04:38" }, "alipay_brand_dto": { "iconUrl": "https://mdn.alipayobjects.com/huamei_5fajmi/afts/img/B-y9S6ZeSiYAAAAAQCAAAAgADlahAQFr/original", "content": "24h守护你的资金安全", "checkIconUrl": "https://mdn.alipayobjects.com/huamei_5fajmi/afts/img/BE3zQbkG-WAAAAAALyAAAAgADlahAQFr/original" }, "passback_params": "agent平台自定义透传json串" } ``` 其中,`agent_order_dto` 用于更新订单金额、卖家、支付时间及订单号等订单信息;`alipay_brand_dto` 用于更新支付结果卡片中的支付宝品牌展示信息。 #### 响应要求 消息验签且业务处理成功后,HTTP 同步响应正文必须返回纯文本 `success`,支付宝收到后停止重试: ```http HTTP/1.1 200 OK Content-Type: text/plain; charset=UTF-8 success ``` 返回 `fail`、空字符串或其他内容均会被认为处理失败,支付宝可能按照消息投递重试策略再次发送。同一条消息可能被重复投递,因此必须保证 `notify_id` 幂等;如采用异步业务处理,应在消息已可靠落库或进入可靠消息队列后再返回 `success`。 --- ### 商品和生活服务商户接入智能体平台 目录路径:Agent Pay · Agent支付 > 商品和生活服务商户接入智能体平台 来源:https://aipay.alipay.com/docs/agent-pay/merchant-to-agent-platform.md 我之前在APP、网站经营,现在我想要让我的服务可以被Agent调用并收款。 #### 商家接入移动端智能体 ##### 适用场景 商家之前在 APP 经营,现在想让我的商品或服务可以被 移动端Agent 调用,在用户确认后使用支付宝完成支付。 ##### 集成方案 关键逻辑说明: + 前置要求:已签约 APP支付 收单产品码 + 商户关键集成步骤:商户调用支付宝 预下单 接口发起收单,将支付宝返回 **【预下单号prepayId】**(alipay.trade.order.prepay) 返回给智能体平台。由智能体平台通过 **【预下单号prepayId】** 推进支付 + 接口集成文档:[https://opendocs.alipay.com/pre-open/05lo9o?pathHash=5d40322b](https://opendocs.alipay.com/pre-open/05lo9o?pathHash=5d40322b) ::aipay-image{src="https://mass.alipay.com/aipay_assets/afts/file/wEKHTZp1AiMAAAAATyAAAAgAeoh5AQJr" width="100%"} #### 商家接入PC端智能体 ##### 适用场景 商家之前在 电脑网站经营,现在想让我的商品或服务可以被 PC 端 Agent 调用,在用户确认后使用支付宝完成支付。 ##### 集成方案 + 如果你的服务未接入支付宝电脑网站支付,请先参考文档接入支付宝电脑网站支付。 + 在接入支付宝电脑网站支付后,这份指南会带你在原有系统外增加一个“商家下单 Skill”。完成后,Agent 可以帮用户选择商品、创建订单,并在支付环节把流程交给支付宝支付处理 Skill,最终由支付宝引导用户完成支付。 ![](https://intranetproxy.alipay.com/skylark/lark/__mermaid_v3/b3a5901d6e3a711579bc169f01c1f728.svg) ##### 商家下单skill改造 + 步骤一 下单阶段: - **步骤 1~6:** 需要提供一个SKILL,由 Agent 唤起,支持 选品、下单、支付等处理流程。支付流程需要对接支付宝 电脑网站支付 收单产品,通过 GET 方式集成alipay.trade.page.pay接口。接口文档参考:[https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-page-pay.html](https://aipay.alipay.com/docs/vibe-pay/ai-web-app-payment-qianyi/api-list/alipay-trade-page-pay.html) + 步骤二 推进支付阶段: - **步骤 7~8:** 取 alipay.trade.page.pay 接口返回的 pageRedirectionData 字段,为了防止 pageRedirectionData 过长,需要唤起支付宝alipay-bot trigger-payment-signal命令做链接压缩,得到支付短链。命令如下: ```json alipay-bot trigger-payment-signal \ --payment-link "" \ --merchant-info "<商户信息,商品名称,订单金额(元)>" \ --amount "<订单金额>" ``` - **步骤 9~10:** 将压缩得到的 支付短链 唤起支付宝 SKILL 推进支付,使用alipay-bot submit-payment命令。支付宝将接管整体支付流程,引导用户完成支付。命令如下: ```json alipay-bot submit-payment --payment-link <支付链接> --intent-summary <商户信息,商品名称,订单金额(元) > ``` ##### 联调准备 开发和联调前,请安装支付宝相关 Skill 与 `alipay-bot` 命令,安装后可以发起调试 ```plain npx -y @alipay/agent-payment@latest install ``` ##### 示例 Demo + 场景举例:商家希望将 在 Agent 环境中,支持 运势预测服务 通过支付宝支付收款,并以 Skill 方式接入。 + 代码仓库:[支付宝电脑网站支付 Demo - 运势预测(Node.js)](https://github.com/alipay/ai/tree/main/code_example/page-pay-demo-with-agentpay) 获取示例代码和配套商家下单 Skill。 + 代码模块说明: - 接入电脑网站支付服务代码:`app.js` - 商家下单 Skill 代码:`SKILL/SKILL.md` - Skill 支付上翻适配代码:`SKILL/references/create-cashier-url.js` - 详细流程:`SKILL/README.md` --- ### 委托支付 目录路径:Agent Pay · Agent支付 > 委托支付 来源:https://aipay.alipay.com/docs/agent-pay/delegation-pay.md 智能体平台如何接入支付宝委托支付 #### 标准版接入文档 完成 [接入准备](https://opendocs.alipay.com/pre-open/0h6n92?referPath=0h6n93_67a31294) 后,智能体平台可根据接入指南指引快速接入 **智能体支付** 产品。 **说明:** + **智能体支付** 仅支持自研商家/服务商通过 [自研应用](https://opendocs.alipay.com/common/02bijh#%E8%87%AA%E7%A0%94%E6%9C%8D%E5%8A%A1%E5%9E%8B%E5%BA%94%E7%94%A8) 或 [第三方应用](https://opendocs.alipay.com/common/02bijh#%E4%B8%89%E6%96%B9%E6%9C%8D%E5%8A%A1%E5%9E%8B%E5%BA%94%E7%94%A8) 代调用(传入 `app_auth_token`)方式,调用 API 接入。 + **智能体支付** 产品暂不支持沙箱调试。 本文用于说明 智能体平台 如何接入委托支付 ##### 产品特色 智能体委托支付是指用户在**智能体平台**发起代买任务并完成支付宝授权后,委托智能体在约定的金额、次数及有效期范围内发起扣款的一种支付产品。适用于智能体代买商品或服务的场景,**扣款时无需用户在场或再次确认**。该产品需完成签约及技术集成后方可使用。 ##### 使用示例 场景1:单笔委托授权(如:酒店抢房) | 用户对话Query | 发起委托任务,授权额度 | 授权成功 | 发起委托支付扣款 | 委托任务账单展示 | | :--- | :--- | :--- | :--- | :--- | | ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1793951559294-b3d0a113-2f48-4020-b64c-d88011d60d1e.png) | ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1794277953047-17a6a881-85b5-4af9-abc2-fd1e292ceab6.png) | ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1793935358117-4d880fa8-5d38-4c8e-93bc-748cd62eb6d9.png) | 当满足扣款条件,由智能体平台发起扣款,满足授权要求(范围、次数、金额、上下文 等要求)、安全风险,可以免密扣款成功。 用户可以在「支付宝-我的-设置-支付设置-AI钱包」查看扣款成功账单 | ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1794195059492-d930beac-dbed-4f05-87e5-3b3092158998.png) | 场景2:周期委托授权(如:每周一个代办任务,每天早上点一杯咖啡) | 用户对话Query | 发起委托任务,授权额度 | 授权成功 | 发起委托支付扣款 | 委托任务账单展示 | | :--- | :--- | :--- | :--- | :--- | | ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1793951559294-b3d0a113-2f48-4020-b64c-d88011d60d1e.png) | ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1794278070177-7a4f79de-678d-403a-a3fc-10b35aca98a5.png) | ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1793935358117-4d880fa8-5d38-4c8e-93bc-748cd62eb6d9.png) | 当满足扣款条件,由智能体平台发起扣款,满足授权要求(范围、次数、金额、上下文 等要求)、安全风险,可以免密扣款成功。 用户可以在「支付宝-我的-设置-支付设置-AI钱包」查看扣款成功账单 | ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1794278271934-0f3d362c-ca77-4ed2-a151-b31e468098d9.png) | ##### 申请条件 支持的账号类型:[支付宝企业账号](https://opendocs.alipay.com/common/02kkum) 产品签约:请联系支付宝客户经理完成签约 ##### 整体交互流程 ###### 申请委托任务 ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/144456470/1793932986862-13d046c2-79a2-4893-884c-e2de01e86fc4.png) ###### 委托支付扣款执行 ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/svg/144456470/1793930041624-dd0345ab-b40d-4f35-abf2-b94980ade600.svg) ##### 接口总览 | 接口api名称 | 接口类型 | 接口名称 | 功能 | | :--- | :--- | :--- | :--- | | alipay.user.agreement.delegation.apply | 服务端openapi接口 | 个人委托代买任务申请 | 创建委托任务申请,生成 orderStr 唤起授权 | | alipay.user.agreement.delegation.query | 服务端openapi接口 | 个人代买委托任务查询 | 查询授权状态及剩余金额/次数 | | alipay.user.agreement.delegation.cancel | 服务端openapi接口 | 个人代买委托任务取消 | 取消委托任务 | | 委托任务申请成功、取消成功 异步消息通知 | https POST形式通知,通知地址是alipay.user.agreement.delegation.apply接口传入的notifyUrl | 委托任务状态变更通知接口 | 通知智能体平台委托任务状态更新成功 | | alipay.trade.order.prepay | 委托扣款发起下单接口 | 智能体委托支付 | 发起支付收单 | | alipay.trade.agent.delegation.pay | 服务端openapi接口 | 智能体委托支付 | 基于委托 ID 对商户订单扣款 | | 委托任务扣款成功异步消息通知 | https POST形式通知,通知地址是alipay.trade.agent.delegation.pay接口传入的notifyUrl | 委托任务支付成功通知接口 | 通知智能体平台支付扣款成功 | ##### API列表 ###### 申请委托任务 **子章节:** 接口名 章节路径:标准版接入文档 > API列表 > 申请委托任务 > 接口名 alipay.user.agreement.delegation.apply **子章节:** 集成说明 章节路径:标准版接入文档 > API列表 > 申请委托任务 > 集成说明 + 服务端参数准备:商户需在服务端完成签约参数的组装,通过调用 `alipay.user.agreement.delegation.apply` 接口生成签约请求参数,并将生成的 `orderStr` 下发至客户端。 + 客户端实现:客户端接收到服务端下发的签约参数后,调用支付宝客户端 SDK 的签约方法,引导用户完成协议授权。 + 接口说明:该接口是 签名数据准备接口,用于生成可信签名字符串(orderStr)。可信签名串中包含业务参数及商户身份信息,可防止数据被篡改,一般用于打开支付宝客户端。请在服务端执行支付宝SDK中sdkExecute方法,读取响应中的body()结果 + 智能体调用支付宝SDK唤起委托任务授权页面 - IOS集成:[https://opendocs.alipay.com/open/00dn76?pathHash=8cf05d19](https://opendocs.alipay.com/open/00dn76?pathHash=8cf05d19) - Android集成:[https://opendocs.alipay.com/open/00dn75?referPath=01dcc0_cf89b2be](https://opendocs.alipay.com/open/00dn75?referPath=01dcc0_cf89b2be) - Harmony集成:[https://opendocs.alipay.com/open/0f71b5?pathHash=bedc38ba](https://opendocs.alipay.com/open/0f71b5?pathHash=bedc38ba) **子章节:** 公共请求参数 章节路径:标准版接入文档 > API列表 > 申请委托任务 > 公共请求参数 | **参数** | **类型** | **是否必选** | **最大长度** | **描述** | **示例值** | | :--- | :--- | :--- | :--- | :--- | :--- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.user.agreement.delegation.apply` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | **子章节:** 业务请求参数 章节路径:标准版接入文档 > API列表 > 申请委托任务 > 业务请求参数 | 参数 | 类型 | 必选 | 说明 | | :--- | :--- | --- | --- | | agent_id | String | 是 | 找支付宝BD后台申请得到,固定值 | | personal_product_code | String | 是 | 固定传入:UAM_AGENT_AUTH_MULTI_P | | conversation_history | String | 是 | 用户与智能体会话历史,序列化后 ≤ 4096 字符 | | access_params | `Map` | 是 | 来源渠道 | | | --channel | String | 否 | | delegation_params | `Map` | 是 | 委托任务参数 | | --delegation_tag | String | 是 | 委托任务场景描述 | | --max_total_amount | String | 是 | 委托任务金额总上限,2位小数,单位为元 | | --times_limit | String | 是 | 次数上限(预估扣款次数)。单次:传入1;多次:传入对应次数 | | --validity_start_time | Date | 是 | 起始时间(实际当天 00:00:00) | | --validity_end_time | Date | 是 | 截止时间(实际当天 23:59:59) | | --external_delegation_id | String | 是 | 智能体委托任务号,用于控制幂等。建议:重试取相同值;重新发起业务流程申请取不同值 | | --delegation_desc | String | 是 | 委托任务语义化总结 | | --delegation_scene | String | 是 | 单次任务:STANDARD_DELEGATION_SINGLE_PAY周期任务:STANDARD_DELEGATION_PERIOD_PAY | | --goods_sku_info | String | 是 | 【描述】商品 SKU 信息【示例值】可口可乐-无糖型-550ml/瓶 | **子章节:** 业务返回结果 章节路径:标准版接入文档 > API列表 > 申请委托任务 > 业务返回结果 | 参数 | 类型 | 必选 | 说明 | | :--- | :--- | :--- | :--- | | orderStr | String | 是 | 拉起委托任务页面加签串 | **子章节:** 重要参数说明 章节路径:标准版接入文档 > API列表 > 申请委托任务 > 重要参数说明 + personal_product_code:智能体委托任务申请的产品码固定为 UAM_AGENT_AUTH_MULTI_P。 + conversation_history:用户与智能体的会话历史,取下单前一段内容即可。 - 序列化后的长度不能超过4096个字符 + delegation_params:委托任务参数 - delegation_scene: 固定值STANDARD_DELEGATION_SINGLE_PAY - delegation_tag 委托任务的场景描述 - max_total_amount 申请委托任务的金额上限,如需多次购买,以预估总和进行申请。 - times_limit 申请委托任务的次数上限,以预估的扣款次数进行申请。 - validity_start_time 起始生效时间,实际起始时间为当天00:00:00。 - validity_end_time 截止生效时间,实际截止时间为当天23:59:59。 - external_delegation_id 智能体委托任务号,每次申请时以不同的值发起。 - delegation_desc 委托任务的语义化总结。 + access_params:填写固定值即可 - ALIPAYAPP :支付宝客户端签约。 **子章节:** 特殊规则说明 章节路径:标准版接入文档 > API列表 > 申请委托任务 > 特殊规则说明 + 单个任务授权金额上限:5万元 + 单个任务扣款上限:5万元 + 单个任务有效期上限:31天 ###### 签约成功消息通知 **子章节:** 说明 章节路径:标准版接入文档 > API列表 > 签约成功消息通知 > 说明 用户进行签约、解约的的操作完成后,支付宝将以 POST 方式发送信息给商家应用在支付宝开放平台中配置的应用网关地址。其中 delegation_id 代表委托任务ID,是上文查询、取消任务的请求条件 **子章节:** 异步通知示例 章节路径:标准版接入文档 > API列表 > 签约成功消息通知 > 异步通知示例 ```plain charset=UTF-8¬ify_time=2026-07-13 12:55:53¬ify_id=202600012¬ify_type=dut_user_sign&sub_notify_type=DELEGATION_APPLY&delegation_apply_time=2026-07-13 12:55:53&delegation_id=20260901&external_delegation_id=202609240001&agreement_no=20260001&external_agreement_no=merchant_agreement_******&personal_product_code=UAM_AGENT_AUTH_MULTI_P&status=NORMAL&silent_upgrade_flag=T&sign_scene=INDUSTRY|AGENT_AUTH&alipay_user_id=2088************&alipay_logon_id=138******00&external_user_id=202600001&external_logon_id=merchant_logon_******&auth_app_id=2021************&app_id=2021************&sign_time=2026-07-13 12:55:53&valid_time=2026-07-13 12:55:53&invalid_time=2026-08-13 12:55:53&version=1.0&sign_type=RSA2&sign=****** ``` ###### 委托任务查询 **子章节:** 接口名 章节路径:标准版接入文档 > API列表 > 委托任务查询 > 接口名 `alipay.user.agreement.delegation.query` **子章节:** 公共请求参数 章节路径:标准版接入文档 > API列表 > 委托任务查询 > 公共请求参数 | **参数** | **类型** | **是否必选** | **最大长度** | **描述** | **示例值** | | :--- | :--- | :--- | :--- | :--- | :--- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.user.agreement.delegation.query` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | **子章节:** 业务请求参数 章节路径:标准版接入文档 > API列表 > 委托任务查询 > 业务请求参数 | 参数 | 类型 | 必选 | 说明 | | :--- | :--- | :--- | :--- | | agent_id | String | 是 | 智能体ID,找支付宝BD后台申请得到,固定值 | | delegation_id | String | 否 | 委托任务号 或 商户委托任务号 二者传入一个都可以查询。可以通过下文4.3完成授权消息 | | external_delegation_id | String | 否,和delegation_id二选一 | | | external_agreement_no | String | 是 | 传入agentId即可 | | product_code | String | 是 | 固定传入UAM_AGENT_AUTH_MULTI_P | **子章节:** 业务返回结果 章节路径:标准版接入文档 > API列表 > 委托任务查询 > 业务返回结果 | 参数 | 类型 | 必选 | 说明 | | :--- | :--- | :--- | :--- | | valid_time | Date | 是 | 【描述】协议生效时间,格式为 yyyy-MM-dd HH:mm:ss。;【示例值】2017-05-24 15:00:40 | | invalid_time | Date | 是 | 【描述】协议失效时间,格式为 yyyy-MM-dd HH:mm:ss。;【示例值】2117-05-24 00:00:00 | | status | String | 是 | 【描述】协议当前状态 ;1. NORMAL:任务有效;2. CANCEL:任务取消;3. FINISH:任务结束;【示例值】NORMAL | | external_logon_id | String | 是 | 【描述】用户在商户侧的唯一标识。;【示例值】0101010101 | | external_user_id | String | 是 | 【描述】用户在商户侧的唯一标识。;【示例值】0101010101 | | agreement_no | String | 是 | 【描述】支付宝系统中用以唯一标识用户签约记录的编号(用户签约成功后的协议号 ) ,如果传了该参数,其他参数会被忽略;【示例值】20170322450983769228 | | alipay_logon_id | String | 是 | 【描述】返回脱敏的支付宝账号;【示例值】test***ali@alipay.net | | principal_id | String | 是 | 【描述】授权主体信息;【示例值】2088xxx | ###### 委托任务取消 **子章节:** 接口名 章节路径:标准版接入文档 > API列表 > 委托任务取消 > 接口名 `alipay.user.agreement.delegation.cancel` **子章节:** 公共请求参数 章节路径:标准版接入文档 > API列表 > 委托任务取消 > 公共请求参数 | **参数** | **类型** | **是否必选** | **最大长度** | **描述** | **示例值** | | :--- | :--- | :--- | :--- | :--- | :--- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.user.agreement.delegation.cancel` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | **子章节:** 业务请求参数 章节路径:标准版接入文档 > API列表 > 委托任务取消 > 业务请求参数 | 参数 | 类型 | 必选 | 说明 | | :--- | :--- | :--- | :--- | | product_code | String | 是 | 固定传入UAM_AGENT_AUTH_MULTI_P | | delegation_id | String | 是 | 委托任务号。可以通过下文4.3完成授权消息 | **子章节:** 业务返回结果 章节路径:标准版接入文档 > API列表 > 委托任务取消 > 业务返回结果 无业务响应参数,只需要判断success字段即可,success=true代表已成功,其他代表失败 ###### 委托任务扣款下单 说明:该接口需要商户集成,智能体平台无需集成 **子章节:** 接口名 章节路径:标准版接入文档 > API列表 > 委托任务扣款下单 > 接口名 `alipay.trade.order.prepay` **子章节:** 公共请求参数 章节路径:标准版接入文档 > API列表 > 委托任务扣款下单 > 公共请求参数 | **参数** | **类型** | **是否必选** | **最大长度** | **描述** | **示例值** | | :--- | :--- | :--- | :--- | :--- | :--- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.order.prepay` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | **子章节:** 业务请求参数 章节路径:标准版接入文档 > API列表 > 委托任务扣款下单 > 业务请求参数 总体请求参数,可以参考当前发起app支付参数 | 参数 | 类型 | 必选 | 说明 | | :--- | :--- | :--- | :--- | | total_amount | String | 是 | 订单金额,单位为元 | | product_code | String | 是 | 固定值:QUICK_MSECURITY_PAY | | out_trade_no | String | 是 | 外部订单号,用于控制幂等 | | payment_type | String | 是 | 固定值:agent_pay | | subject | String | 是 | 订单标题 | | seller_id | String | 否 | 卖家id;建议:如果没有特殊诉求,和当前APP参数保持一致 | | goods_detail | `List` | 是 | 商品信息,需要传入商品数量和名称等关键信息 | | --goods_id | String | 是 | 可以传入商品SKU ID 或 商家体系内能代表商品的唯一ID | | --goods_name | String | 是 | 商品名称,需要明文传入商品名称,支付宝会做授权意图和商品一致性比对 | | --quantity | String | 是 | 商品数量 | | --body | String | 是 | 商品描述,需要明文传入商品描述,支付宝会做授权意图和商品一致性比对 | | --price | String | 是 | 单价 | | --goods_category | String | 是 | 商品类目,支付宝会做商品类目与商家经营一致性比对 | | time_expire | String | 否 | 订单绝对超时时间 | | timeout_express | String | 否 | 订单相对超时时间 | | extend_params | `Map` | 否 | 扩展参数;建议:如果没有特殊诉求,和当前APP参数保持一致 | | business_params | string | 否 | 扩展参数 | 业务返回结果 | 参数 | 必选 | 类型 | 说明 | | :--- | :--- | :--- | :--- | | prepay_id | 是 | String | 预下单号 | ###### 委托支付扣款 **子章节:** 接口名 章节路径:标准版接入文档 > API列表 > 委托支付扣款 > 接口名 `alipay.trade.agent.delegation.pay` **子章节:** 公共请求参数 章节路径:标准版接入文档 > API列表 > 委托支付扣款 > 公共请求参数 | **参数** | **类型** | **是否必选** | **最大长度** | **描述** | **示例值** | | :--- | :--- | :--- | :--- | :--- | :--- | | `app_id` | String | 必选 | 32 | 支付宝分配给开发者的应用 ID | `2014072300007148` | | `method` | String | 必选 | 128 | 接口名称 | `alipay.trade.agent.delegation.pay` | | `format` | String | 可选 | 40 | 仅支持JSON | `JSON` | | `charset` | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | `utf-8` | | `sign_type` | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | `RSA2` | | `sign` | String | 必选 | 344 | 商户请求参数的签名串,详见[签名](https://ideservice.alipay.com/cms/site/02khjm) | `详见示例` | | `timestamp` | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm" | `2014-07-24 03:07:50` | | `version` | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | `1.0` | | `biz_content` | String | 必选 | - | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | - | **子章节:** 业务请求参数 章节路径:标准版接入文档 > API列表 > 委托支付扣款 > 业务请求参数 | 参数 | 必选 | 类型 | 说明 | | :--- | :--- | :--- | :--- | | prepay_id | 是 | string | 预下单 ID(trade.order.prepay 获取) | | agreement_no | 是 | string | 用户签约协议号 | | delegation_id | 是 | string | 代买委托 id | | agent_id | 否 | string | 智能体 id | **子章节:** 业务返回结果 章节路径:标准版接入文档 > API列表 > 委托支付扣款 > 业务返回结果 | 参数 | 必选 | 类型 | 说明 | | :--- | :--- | :--- | :--- | | tradeNo | 是 | String | 扣款成功后,支付宝交易号 | **子章节:** 业务错误码 章节路径:标准版接入文档 > API列表 > 委托支付扣款 > 业务错误码 | 错误码 | 说明 | 建议处理 | | :--- | :--- | :--- | | ACQ.AGREEMENT_NOT_EXIST | 协议不存在或已解约 | 重新引导签约 | | ACQ.AGREEMENT_INVALID | 用户协议失效 | 重新签约 | | ACQ.BEYOND_AVALIABLE_AUTH_AMOUNT | 超过可用授权金额 | 检查扣款金额 | | ACQ.FREQUENCY_LIMITED | 扣款频率过高 | 重试间隔 ≥ 5 分钟 | | ACQ.ORDER_NOT_EXIST / ACQ.TRADE_NOT_EXIST | 订单/交易不存在 | 确认 prepay_id;过期重新预下单 | | ACQ.TRADE_HAS_SUCCESS | 交易已支付成功 | 幂等,无需重试 | | ACQ.TRADE_HAS_CLOSE | 交易已关闭 | 超时未支付/已退款,重新预下单 | | ACQ.BUYER_BALANCE_NOT_ENOUGH | 买家余额不足 | 绑卡或充值后重试 | | ACQ.ACCESS_FORBIDDEN | 无权限 | 确认收单及代理支付合约有效 | | SYSTEM_ERROR / ACQ.SYSTEM_ERROR | 系统繁忙 | 原参重试 | ###### **委托支付扣款成功通知** 在`alipay.trade.agent.delegation.pay`阶段传入通知地址,支付宝会通知到商户对应地址 参考报文: ```plain https://aipay.alipay.com/|47.115.192.15|400|147ms|GBK]: https://aipay.alipay.com/?gmt_create=2026-10-27 22:38:07¬ify_action_type=payByAccountAction&charset=UTF-8&gmt_payment=2026-10-27 22:38:12¬ify_time=2026-10-27 22:38:13&sign=$$$&trade_action=PAY&version=1.0¬ify_id=2026102701222223812158841600119952&prepay_id=VVRQY2E3OWQ4ZWYxOWRjNGQ0YjljODZhYzg2ZjdkNzkxZWIkMDA=¬ify_type=trade_status_sync&out_trade_no=734894867892410271234567&platform_pid=2088501973148745&total_fee=600.00&trade_status=TRADE_SUCCESS&trade_no=2026102722001458841600050093&app_id=2021007194668012&sign_type=RSA2 ``` 字段说明: | 参数 | 必选 | 类型 | 说明 | | :--- | :--- | :--- | :--- | | gmt_create | 是 | string | 交易创建时间 | | notify_action_type | 是 | String | 通知动作类型,该字段无需解析,可以忽略 | | trade_action | 是 | String | 交易动作,固定PAY | | notify_type | 是 | String | 通知类型,固定trade_status_sync | | notify_id | 是 | String | 支付宝通知幂等ID | | trade_no | 是 | String | 交易号 | | prepay_id | 是 | String | 预下单ID,在alipay.trade.order.prepay接口返回的预下单号。可以用该字段做关联 | | out_trade_no | 是 | String | 外部单号 | | platform_pid | 是 | String | 智能体平台PID | | total_fee | 是 | String | 订单总金额 | | trade_status | 是 | String | 交易状态,TRADE_SUCCESS代表成功g | | charset | 是 | string | 编码类型 | | gmt_payment | 是 | string | 支付时间 | | notify_time | 是 | String | 通知时间 | | sign | 是 | String | 加签签名 | | app_id | 是 | String | 应用APPID | | sign_type | 是 | String | 签名类型 | 验签说明:接收到通知消息后,需要根据签名做验签, ###### **交易查询接口** 接口名:`alipay.trade.query` 对接文档:[https://opendocs.alipay.com/open/82ea786a_alipay.trade.query?scene=23&pathHash=0745ecea](https://opendocs.alipay.com/open/82ea786a_alipay.trade.query?scene=23&pathHash=0745ecea) ##### SDK版本 支付宝服务端SDK:JAVA版本升级到4.40.976.ALL ##### 对接要求 建议请求统一设置bizContent字段,内部是按照上述文档要求设置JSON结果即可,对接成本最低 --- ### 智能体支付接口 目录路径:Agent Pay · Agent支付 > API列表 > 智能体支付接口 来源:https://aipay.alipay.com/docs/agent-pay/api-list/agent-pay.md #### 接口说明 该接口是 **签名数据准备接口**,用于生成可信签名字符串(`orderStr`)。可信签名串中包含业务参数及商户身份信息,可防止数据被篡改,一般用于打开支付宝客户端。请在服务端执行支付宝SDK中`sdkExecute`方法,读取响应中的`body()`结果。 #### 公共请求参数 | 参数 | 类型 | 是否必选 | 最大长度 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | app_id | String | 必选 | 32 | 支付宝分配给开发者的应用ID | 2014072300007148 | | method | String | 必选 | 128 | 接口名称 | alipay.trade.agent.pay | | format | String | 可选 | 40 | 仅支持JSON | JSON | | charset | String | 必选 | 10 | 请求使用的编码格式,如utf-8,gbk,gb2312等 | utf-8 | | sign_type | String | 必选 | 10 | 商户生成签名字符串所使用的签名算法类型,目前支持RSA2和RSA,推荐使用RSA2 | RSA2 | | sign | String | 必选 | 344 | 商户请求参数的签名串,详见签名 | 详见示例 | | timestamp | String | 必选 | 19 | 发送请求的时间,格式"yyyy-MM-dd HH:mm:ss" | 2014-07-24 03:07:50 | | version | String | 必选 | 3 | 调用的接口版本,固定为:1.0 | 1.0 | | notify_url | String | 可选 | 256 | 支付宝服务器主动通知商户服务器里指定的页面http/https路径。 | http://api.test.alipay.net/atinterface/receive_notify.htm | | app_auth_token | String | 可选 | 40 | 详见应用授权概述 | | | biz_content | String | 必选 | | 请求参数的集合,最大长度不限,除公共参数外所有请求参数都必须放在这个参数中传递,具体参照各产品快速接入文档 | | #### 业务请求参数 | 参数 | 名称 | 是否必选 | 类型 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | prepay_id | 预下单ID | 必选 | string[1,512] | 预下单ID,通过请求alipay.trade.order.prepay接口获取预下单ID | `MV91dHAucHJlb3JkZXJfMjAyNTA2MDRfMjA4ODg0MTAzMzUzMTQ0OF9YUDE1MjUwNjA0MDU1MDA2MDQzNTAyOTQwMDY5OTJfMzMwNzg2XzQyLTIwNzYxJDgq` | | agent_id | 智能体唯一标识 | 可选 | string[1,512] | 联系对应BD进行KYA申请后下发的智能体id | `2026000000010000` | | cashier_scene | 收银台场景 | 可选 | string[1,64] | 收银台场景,在Agent支付标准版场景下固定填"appPay" | `appPay` | #### 常见请求示例 ::::aipay-tabs{defaultActiveKey="Java"} :::aipay-tab{key="Java" title="Java"} ``` package com.java.sdk.demo; import com.alipay.api.AlipayApiException; import com.alipay.api.AlipayClient; import com.alipay.api.DefaultAlipayClient; import com.alipay.api.AlipayConfig; import com.alipay.api.response.AlipayTradeAgentPayResponse; import com.alipay.api.request.AlipayTradeAgentPayRequest; import com.alipay.api.domain.AlipayTradeAgentPayModel; import com.alipay.api.FileItem; import java.util.Base64; import java.util.ArrayList; import java.util.List; public class AlipayTradeAgentPay { public static void main(String[] args) throws AlipayApiException { // 初始化SDK AlipayClient alipayClient = new DefaultAlipayClient(getAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeAgentPayRequest request = new AlipayTradeAgentPayRequest(); AlipayTradeAgentPayModel model = new AlipayTradeAgentPayModel(); // 设置预下单ID model.setPrepayId("MV91dHAucHJlb3JkZXJfMjAyNTA2MDRfMjA4ODg0MTAzMzUzMTQ0OF9YUDE1MjUwNjA0MDU1MDA2MDQzNTAyOTQwMDY5OTJfMzMwNzg2XzQyLTIwNzYxJDgq"); // 设置智能体唯一标识 model.setAgentId("2026000000010000"); // 设置收银台场景 model.setCashierScene("appPay"); request.setBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.putOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeAgentPayResponse response = alipayClient.sdkExecute(request); String orderStr = response.getBody(); System.out.println(orderStr); if (response.isSuccess()) { System.out.println("调用成功"); } else { System.out.println("调用失败"); // sdk版本是"4.38.0.ALL"及以上,可以参考下面的示例获取诊断链接 // String diagnosisUrl = DiagnosisUtils.getDiagnosisUrl(response); // System.out.println(diagnosisUrl); } } private static AlipayConfig getAlipayConfig() { String privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; String alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.setServerUrl("https://openapi.alipay.com/gateway.do"); alipayConfig.setAppId("<-- 请填写您的AppId,例如:2019091767145019 -->"); alipayConfig.setPrivateKey(privateKey); alipayConfig.setFormat("json"); alipayConfig.setAlipayPublicKey(alipayPublicKey); alipayConfig.setCharset("UTF-8"); alipayConfig.setSignType("RSA2"); return alipayConfig; } } ``` ::: :::aipay-tab{key="C#" title="C#"} ``` using System; using System.Collections.Generic; using Aop.Api; using Aop.Api.Request; using Aop.Api.Response; using Aop.Api.Domain; using Aop.Api.Util; namespace SdkDemoTest { public class AlipayTradeAgentPay { public static void Main(string[] args) { // 初始化SDK IAopClient alipayClient = new DefaultAopClient(GetAlipayConfig()); // 构造请求参数以调用接口 AlipayTradeAgentPayRequest request = new AlipayTradeAgentPayRequest(); AlipayTradeAgentPayModel model = new AlipayTradeAgentPayModel(); // 设置预下单ID model.PrepayId = "MV91dHAucHJlb3JkZXJfMjAyNTA2MDRfMjA4ODg0MTAzMzUzMTQ0OF9YUDE1MjUwNjA0MDU1MDA2MDQzNTAyOTQwMDY5OTJfMzMwNzg2XzQyLTIwNzYxJDgq"; // 设置智能体唯一标识 model.AgentId = "2026000000010000"; // 设置收银台场景 model.CashierScene = "appPay"; request.SetBizModel(model); // 第三方代调用模式下请设置app_auth_token // request.PutOtherTextParam("app_auth_token", "<-- 请填写应用授权令牌 -->"); AlipayTradeAgentPayResponse response = alipayClient.SdkExecute(request); string orderStr = response.Body; Console.WriteLine(orderStr); if(!response.IsError) { Console.WriteLine("调用成功"); } else { Console.WriteLine("调用失败"); } } private static AlipayConfig GetAlipayConfig() { string privateKey = "<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->"; string alipayPublicKey = "<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->"; AlipayConfig alipayConfig = new AlipayConfig(); alipayConfig.ServerUrl = "https://openapi.alipay.com/gateway.do"; alipayConfig.AppId = "<-- 请填写您的AppId,例如:2019091767145019 -->"; alipayConfig.PrivateKey = privateKey; alipayConfig.Format = "json"; alipayConfig.AlipayPublicKey = alipayPublicKey; alipayConfig.Charset = "UTF-8"; alipayConfig.SignType = "RSA2"; return alipayConfig; } } } ``` ::: :::aipay-tab{key="PHP" title="PHP"} ``` setBizContent(json_encode($model,JSON_UNESCAPED_UNICODE)); // 如果是第三方代调用模式,请设置app_auth_token(应用授权令牌) $orderStr = $alipayClient->sdkExecute($request, "<-- 请填写应用授权令牌 -->"); echo $orderStr; function getAlipayConfig() { $privateKey = '<-- 请填写您的应用私钥,例如:MIIEvQIBADANB ... ... -->'; $alipayPublicKey = '<-- 请填写您的支付宝公钥,例如:MIIBIjANBg... -->'; $alipayConfig = new AlipayConfig(); $alipayConfig->setServerUrl('https://openapi.alipay.com/gateway.do'); $alipayConfig->setAppId('<-- 请填写您的AppId,例如:2019091767145019 -->'); $alipayConfig->setPrivateKey($privateKey); $alipayConfig->setFormat('json'); $alipayConfig->setAlipayPublicKey($alipayPublicKey); $alipayConfig->setCharset('UTF-8'); $alipayConfig->setSignType('RSA2'); return $alipayConfig; } ``` ::: :::: #### 公共响应参数 无公共响应参数 #### 业务响应参数 | 参数 | 名称 | 是否必选 | 类型 | 描述 | 示例值 | | --- | --- | --- | --- | --- | --- | | orderStr | 签名字符串 | 必选 | string(16384) | 获取签名后的业务数据具体使用方法请参考[移动端智能体支付]()| 请参考响应示例 | #### 响应示例 ```text app_id=2017060101317939&biz_content=%7B%22agent_id%22%3A%222026000000010000%22%2C%22agreement_no%22%3A%2220170322450983769228%22%2C%22user_token_type%22%3A%22encrypt_phone%22%2C%22agreement_sign_params%22%3A%22%22%2C%22user_token%22%3A%22bcb49fcWEFSDb6ed517449b6c9WDSDSDF13e9cba16b9aDGE32dd82%22%2C%22cashier_scene%22%3A%22appPay%22%2C%22prepay_id%22%3A%22MV91dHAucHJlb3JkZXJfMjAyNTA2MDRfMjA4ODg0MTAzMzUzMTQ0OF9YUDE1MjUwNjA0MDU1MDA2MDQzNTAyOTQwMDY5OTJfMzMwNzg2XzQyLTIwNzYxJDgq%22%7D&charset=UTF-8&format=json&method=alipay.trade.agent.pay&sign=ERITJKEIJKJHKKKKKKKHJEREEEEEEEEEEE&sign_type=RSA2×tamp=2014-07-24+03%3A07%3A50&version=1.0 ``` #### 公共错误码 [前往查看](https://opendoc.alipay.com/common/02km9f) #### 业务错误码 | 错误码 | 错误描述 | 解决方案 | | --- | --- | --- | | SYSTEM_ERROR | 系统繁忙 | 服务器异常 可能发生了网络或者系统异常,导致服务调用失败,商户可以用同样的请求发起重试 | | INVALID_PARAMETER | 参数有误 | 请根据接口返回的参数非法的具体错误信息,修改参数后进行重试 | #### 触发通知示例 ```text 21:46:15&sign_type=RSA2&sign=WcO+t3D8Kg71dTlKwN7r9PzUOXeaBJwp8/FOuSxcuSkXsoVYxBpsAidprySCjHCjmaglNcjoKJQLJ28/Asl93joTW39FX6i07lXhnbPknezAlwmvPdnQuI01HZsZF9V1i6ggZjBiAd5lG8bZtTxZOJ87ub2i9GuJ3Nr/NUc9VeY=&trade_no=2013112011001004330000121536&gmt_create=2026-03-26 13:59:54&gmt_payment=2026-03-26 13:59:55&trade_action=PAY&passback_params={"uid":"1234567890"}&prepay_id=MV91dHAucHJlb3JkZXJfMjAyNTA2MDRfMjA4ODg0MTAzMzUzMTQ0OF9YUDE1MjUwNjA0MDU1MDA2MDQzNTAyOTQwMDY5OTJfMzMwNzg2XzQyLTIwNzYxJDg=&voucher_detail_list=[{"amount":"1.80","id":"XXXXXFRHC1","name":"立减1.8元","productCode":"DISCOUNT","templateId":"XXXXXXXJZN670","type":"DISCOUNT","vccExtendInfo":{"fundProvider":"MERCHANT","fundType":"BALANCE","camp_id":"XXXX"}}]&out_trade_no=131306007260350146021752339&total_fee=订单总金额&trade_status=TRADE_SUCCESS ``` --- ## 智能终端设备 ### 新终端智能体支付 目录路径:智能终端设备 > 产品与 Skill 介绍 > 新终端智能体支付 来源:https://aipay.alipay.com/products/device-agent-pay.md 面向智能眼镜、智能耳机、具身智能设备等新一代 AI 终端的原生支付解决方案。看一下、说一声就能完成支付。 所属产品:[Agent Pay]() 智能终端的 AI 支付宝,帮你完成每一笔交易 面向智能眼镜、智能耳机、具身智能设备等新一代 AI 终端的原生支付解决方案。看一下、说一声就能完成支付。 [联系销售](https://aipay.alipay.com/merchant-intent) #### AI 支付多端覆盖 支付宝 AI 支付以统一 SDK 覆盖智能眼镜、耳机与具身智能设备,提供一致的支付体验 ##### AI 眼镜支付 看一下就能完成支付,视觉+语音双模态触发,支持虹膜无感核身 看码支付 看设备支付 虹膜识别 ##### AI 耳机支付 说一声就能完成支付,声纹支付,安全自然 语音支付 声纹核身 智能体业务 ##### 具身智能支付 机器狗扫码+语音支付,助力具身智能完成代办任务 扫码支付 点咖啡 城市导览 #### AI 眼镜支付 看一下支付 看一下、说一声即可支付,解放双手。结合支付宝数据与核身能力,为新一代智能眼镜提供端内服务。 - 语音唤醒与视觉扫码,双模态触发支付 - 支持看码支付与 N 设备蓝环识别支付 - 虹膜核身、点头确认,完成无感支付 - 眼镜端 APK 配合手机端 SDK,信令直连,无需厂商中转 - 摘下眼镜自动退出支付流程 #### AI 耳机支付 说一下支付 通过手机端 SDK,让语音助手衔接日常生活服务。无需改动设备端,适用于无摄像头的 RTOS 耳机或眼镜。 - 全部能力由手机端 SDK 实现 - 录入声纹核身,语音确认支付 - 支持充话费、点咖啡、停车缴费等场景 - 支持 Android、iOS、鸿蒙三平台 - 绑定后默认开通话费充值与瑞幸咖啡服务 - 摘下耳机自动退出支付流程 #### 具身智能支付 高德机器狗 途途 高德机器狗途途接入支付宝 AI 支付,帮助视障用户穿行复杂环境、识别商品并安全付款。 - 自主行动、视觉识别与扫码支付协同 - 复用手机端 SDK,设备端提供扫码算法 - 支持看一下支付、点咖啡、城市导览 - 扫码 SDK 支持一维码、二维码,码值加密回传 #### 两种支付方式 看一下,或说一下——覆盖新终端多样化交互场景 ##### 看一下支付 设备摄像头看向收款码或 N 设备蓝环,视觉识别触发支付。支持虹膜识别+点头确认的无感支付体验。 看码支付 看设备支付(N 设备蓝环) 虹膜+点头确认 视觉触发 · 虹膜识别+点头确认 ##### 说一下支付 通过语音指令发起支付或智能体业务,AI 完成选品下单,用户语音确认支付。适用于耳机等无摄像头设备。 语音支付 智能体业务 语音触发 · AI 辅助决策 #### 应用场景 从日常消费到科技助残,新终端智能体支付覆盖多元生活场景 ##### 眼镜看设备支付 眼镜看向 N 设备,蓝环亮起识别金额,虹膜识别+点头确认完成支付 ##### 语音点咖啡 耳机/眼镜语音点单,AI 完成选品下单,取单号回传设备 ##### 充话费 语音指令充值话费,支持精确金额与模糊意图 ##### 停车缴费 语音缴纳停车费,绑定车牌后自动识别 ##### 机器狗自主购物 视障用户语音指令,机器狗带路、识别商品、扫码支付 ##### 电影购票 语音选片选座,AI 完成下单,用户确认支付 #### 统一技术架构 一套 SDK 整合安全、核身、AI 交互等能力,适配多种新终端形态 终端层 AI 眼镜 眼镜 APK + 眼镜 SDK 智能耳机 RTOS + 手机 SDK 机器狗 扫码 SDK + 手机 SDK SDK 层 · 支付宝统一输出 意图理解 声纹核身 扫码识别 TTS 播报 支付组件 服务层 AI 服务 智能体业务 码路由 订单管理 安全层 风控引擎 安全核身 蓝盾加密 设备绑定 #### 开启新终端智能体支付能力 产品目前处于定向邀请试运营阶段,面向符合要求的企业级 AI 终端设备厂商开放 01 ##### 企业主体 使用支付宝企业账号,完成经营信息验证 02 ##### 设备资料 准备设备型号、SDK 集成方案、唤醒词 03 ##### 定向申请 联系支付宝行业运营经理,完成接入申请 当前阶段免费,后续计费方式以正式通知为准 --- ### 支付宝SDK无网眼镜接入文档 目录路径:智能终端设备 > 支付宝SDK无网眼镜接入文档 来源:https://aipay.alipay.com/docs/device-agent-pay/sdk-intro-for-glasses-without-internet.md 说明无网眼镜如何接入支付宝SDK #### 1 无网眼镜 无网眼镜指的是眼镜在支付过程中不直连因特网、而是通过手机中转网络请求的眼镜。无网眼镜因眼镜端无法直接发起 **HTTP** 和 **WebSocket** 等网络请求,需要通过连接手机蓝牙,通过**蓝牙通道**做数据交换,真实的网络请求在手机端发起。 ##### 1.1 产品方案介绍 「看一下支付」,是面向下一代个人智能设备的支付方式,看一下、说一声就能完成支付,解放双手高效更便捷。 未来也会结合支付宝的底层数据和核身能力,为眼镜厂商提供更多的支付宝端内服务,丰富AI眼镜的智能生态。 ###### 1.1.1 交互流程介绍 ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/11743/1791774176102-d8805586-d097-4a7d-af50-c05e871a7475.png) ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/11743/1791774215955-edb55297-87f6-4fb9-8184-9d66988995ba.png) ###### 1.1.2 厂商关键词配置 | **场景** | **厂商唤醒关键词** | **示例** | | --- | --- | --- | | 缴话费 | 交话费、充话费、缴话费、手机充值、电话充值
金额结合型(用户意图明确)
+ 【动词】+【话费/元】:充50话费、交100元、充200块话费 | 帮我充值、帮我交话费、帮我手机充值50元、
帮我交50元话费、我要充50元话费 | | 停车缴费 | XX 停车缴费、XX停车费、
给【XX车牌号】交下停车费、停车费怎么交? | 乐奇,停车缴费、帮我停车缴费、启动停车缴费
小爱同学,停车缴费、给我交停车费
交一下停车费、付停车费、给这辆车交下停车费
浙A28372交停车费 | | 点咖啡 | 点一杯、来一杯、我要点、点杯、来杯 **+** 咖啡名(奥瑞白、杨枝甘露、鲜萃、美式、拿铁、咖啡)/瑞幸
新增:推荐一杯好喝的、推荐一杯、推荐新品 | 帮我点杯咖啡、帮我点一杯瑞幸咖啡、点一杯瑞幸咖啡、来一杯瑞幸咖啡、来一杯咖啡、我要点咖啡、点杯咖啡、请帮我点⼀杯柠C美式、来一杯 XXXX 咖啡、点一杯XXXX咖啡、来杯精萃澳瑞白、点一杯生椰杨枝甘露、点杯鲜萃轻轻茉莉 | | 看一下支付 | 扫码支付、扫码支付XX元
支付XX元、支付宝支付
看一下支付、看一下支付XX元、
帮我支付、帮我支付XX元、
句式:XX +支付、支付+xx元 | 扫码支付、扫码支付10元、支付10元、
看一下支付10元、我要支付、我要支付10元 | | 看一下货柜 | 1、扫码、扫二维码、扫描、扫条形码+ 开门、开柜、取货、开启
2、货柜、支付宝+开门、开柜、取货、开启 | 扫码开门、支付宝开门、货柜开门
| ##### 1.2 支付宝输出产物 | **平台** | **产物** | **功能与说明** | | --- | --- | --- | | Android | 眼镜端支付宝Apk | 支付宝主要业务和逻辑处理 | | | 眼镜端glassAPI | 借助眼镜Rom一些能力 1、借助厂商蓝牙通道做数据传输
2、借助厂商媒体播放TTS | | | 手机端SDk | 1、发起网络数据交互,HTTP和wss等协议
2、借助厂商蓝牙通道与眼镜端做数据传输 | | iOS | 手机端SDk | 同Android手机端SDK | ##### 1.3 系统框图 ![画板](https://intranetproxy.alipay.com/skylark/lark/0/2026/jpeg/29588/1769150863988-2064505f-b1e0-4a19-a645-8d87eb51c495.jpeg) #### 2 对接细则 ##### 2.1、眼镜APK **厂商接入,不可重签名** 安装到眼镜端,主要处理支付宝业务逻辑和发起支付 需要Android敏感权限,**需要厂商默认授予** ```xml ``` | **权限** | **描述** | **调用方** | **备注** | | :--- | :--- | :--- | :--- | | FOREGROUND_SERVICE、POST_NOTIFICATIONS | 应用运行前台服务,防止被杀,并通知用户 | 眼镜端 | 眼镜端glassApp使用,手机端无 | | READ_PRIVILEGED_PHONE_STATE, READ_PHONE_STATE | 访问手机状态信息 | 眼镜端 | 如获取deviceId | | WRITE_SECURE_SETTINGS | 写安全配置 | 眼镜端 | | | READ_EXTERNAL_STORAGE, WRITE_EXTERNAL_STORAGE, MANAGE_EXTERNAL_STORAGE | 读写sdcard权限 | 眼镜端、手机端 | | | CAMERA | 访问相机权限,扫码使用 | 眼镜端 | | | ACCESS_NETWORK_STATE,ACCESS_WIFI_STATE | 访问网络状态 | 手机端或有网眼镜 | | | QUERY_ALL_PACKAGES | 查询包信息,配合query包名使用 | 眼镜端 | 眼镜端glassApp用 | | BLUETOOTH | 扫描蓝牙设备 | 眼镜端 | | | ACCESS_THREAT_DETECTION | 访问设备的威胁检测服务 | 眼镜端 | | | VIBRATE | 控制设备的振动器 | 手机端 | | ##### 2.2、眼镜端SDK 厂商系统集成眼镜端SDK,作为中间件串联手机端和眼镜Apk,主要用于眼镜系统侧与眼镜APK的AIDL通信,主要接口类:**AlipayGlassV3Sdk** ```java AlipayGlassV3Sdk.getInstance(this).initSDK(extParams, new GlassSDKCallback() { @Override public void onStartRecording(String token) { //绑定阶段通知开启录音,需要在手机端回传音频数据到receiveDenoiseAudio } @Override public void onStopRecording() { //绑定阶段通知停止录音,停止后手机端不再回调 } @Override public String onStartPlayback(String ttsData) { //播放支付过程提示文案(厂商可选眼镜端or手机端播放) } @Override public int sendDeviceLinkAsync(String data) { //眼镜发送数据-->手机,异步发送 return 0; } @Override public boolean onWearDetection() { //佩戴检测 return true; } @Override public void onErrorEvent(String code, String message) { //错误回调 //Q9990("AlipayGlassSDKExit", "眼镜SDK已退出支付或绑定"), //其他错误码通知 } public void onEvent(String code, String message, Map extInfo) { //Q9991("AlipayGlobalStateChange", "通知厂商SDK状态机变化"), } @Override public void onViIntentResult(String bizType, String dataJson, Map extInfo) { //意图回调(手机端处理) } }); ``` ```java AlipayGlassV3Sdk.getInstance(this).onGateDataReceived(message); ``` 初始化SDK,进程启动在眼镜App建立连接时调用,会将参数传递给眼镜初始化glassApp,支持重复调用; 入参:(入参key详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | --- | | isvName | String | 厂商名称 | 是 | | | deviceModel | String | 设备机型 | 是 | $brand-$model 具体眼镜型号,要确保后续刷机不会变 | | deviceSN | String | 设备SN | 是 | 眼睛端sn,保证不变且唯一,关联支付账号 | | glassSupportNetwork | boolean | 眼镜是否支持联网 | 是 | | | phoneSysType | String | 用户手机型号 | 否 | | | glassPayConfig | String | glassSDK的配置json | 否 | | | glassScreenType | String | 眼镜的显示状态
add -since 1.3.2 | 是 | 0 = 无显
10 = 单绿 - 厂商渲染UI
11 = 单绿 - 自渲染
20 = 全彩 | 收到手机端消息回传给SDK :::warning 支付过程中部分音频数据需要录制成音频,部分语音需要在线合成TTS,需要注意语音播报需要互斥,新的语音指令需要打断前序的播报,以避免在线TTS慢导致的语音排队问题 ::: ###### **2.2.1 ****onErrorEvent****错误事件** + Q9990 AlipayGlassSDKExit:特殊错误码,表示sdk退出绑定或支付; ###### 2.2.2 onEvent事件 **子章节:** **2.2.2.1 Q9991 AlipayGlobalStateChange对应的状态** 章节路径:2 对接细则 > 2.2、眼镜端SDK > 2.2.2 onEvent事件 > 2.2.2.1 Q9991 AlipayGlobalStateChange对应的状态 ```plain SDK_INIT, SDK_BIND_BEGIN,//开始绑定 SDK_BIND_END, SDK_SCAN_BEGIN,//开始扫码 SDK_SCANNING, SDK_SCAN_END,//扫码结束 SDK_AMOUNT_CONFIRM, SDK_AMOUNT_MODIFY, SDK_PAY_BEGIN,// SDK_PAY_END, SDK_EXIT, //sdk退出,同Q9990含义 ``` ###### 2.2.3 数据清理(支付安全) **眼镜换绑手机或者账号后需要清理支付绑定数据** **厂商侧需要调用 unbind 清理眼镜端绑定数据** ##### 2.3、手机端SDK-Android 主要接口类:**AlipayGlassV2SDK** ###### 2.3.1 初始化 ```java AlipayGlassV2Sdk.initSDK(context, extParams, new GlassSDKCallback() { @Override public void onStartRecording(String token) { //手机端无需处理 } @Override public void onStopRecording() { //手机端无需处理 } //播放TTS @Override public String onStartPlayback(String ttsData) { //播放支付过程提示文案(厂商可选眼镜端or手机端播放) } @Override @Deprecated public DeviceResponseData sendDeviceLink(DeviceRequireData data) { //手机发送数据-->眼镜,同步发送,已废弃,请使用 sendDeviceLinkAsync } //发送数据到蓝牙通道 @Override public int sendDeviceLinkAsync(String data) { //手机发送数据-->眼镜,异步发送 } @Override public boolean onWearDetection() { //手机端无需处理 } @Override public void onErrorEvent(String code, String message) { // ● onErrorEvent: // ○ Q1010/1011:sdk调用initCloudEnv失败,或者wss建联失败;收到此错误码仅需播音提示用户。 // ○ Q9990:glassSDK已释放退出 } @Override public void onViIntentResult(String bizType, String dataJson, Map extInfo) { //返回意图和核身结果,厂商按需处理;比如将query显示到手机助手的聊天记录等 } }); ``` | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | --- | | isvName | String | 厂商名称 | 是 | | | deviceModel | String | 设备机型 | 是 | $brand-$model 具体眼镜型号,要确保后续刷机不会变 | | deviceSN | String | 设备SN | 是 | 眼镜端sn号,保证唯一且不变 | | glassSupportNetwork | boolean | 眼镜是否支持联网 | 是 | | | phoneSysType | String | 用户手机型号 | 否 | | | glassPayConfig | String | glassSDK的配置json | 否 | | | glassScreenType | String | 眼镜的显示状态
add -since 1.3.2 | 是 | 0 = 无显
10 = 单绿 - 厂商渲染UI
11 = 单绿 - 自渲染
20 = 全彩 | ###### 2.3.2 getBindStatus ```java void getBindStatus(BindStatusCallBack bindStatusCallBack, boolean needCloudStatus) ``` 获取眼镜的绑定状态;在手机端展示绑定状态 或者每次发起支付前调用;若未绑定,提示用户去厂商App中进行绑定; + needCloudStatus=true, 查询云端状态,一般填true; + needCloudStatus=false, 查询本地缓存状态; 从GAlipayApp1.2.4版本开始,账号绑定、服务开通、核身录入独立解耦;厂商根据featureStatusList判断服务是否开通。 | **字段** | **类型** | **说明** | **示例** | | --- | --- | --- | --- | | isBinded | boolean | 账号绑定状态;(基本废弃,厂商根据featureStatusList判断服务是否开通) | true/false | | extInfo | Map | 扩展信息 | | | \|-featureStatusList | String | 服务开通状态,若已开通则同时返回对应的manageUrl。
| featureStatusList":["{\"featureId\":\"CAR_PARKING\",\"status\":\"STATUS_BIND\"}","{\"featureId\":\"PAYMENT\",\"status\":\"STATUS_BIND\"}","{\"featureId\":\"QUICK_MODE\",\"status\":\"STATUS_UNBIND\"}","
{\"featureId\":\"PAYMENT\",\"status\":\"STATUS_BIND\", \"manageUrl\":\"`http:xxx`\"}","{\"featureId\":\"PAY_DEMO\",\"status\":\"STATUS_BIND\"}"]}
注:若服务从未开通过,则列表不展示 | | \|-verifyMethodStatus | 核身方法录入状态 | `VERIFY_VOICE:OPEN`,表示已录入
`VERIFY_IRIS:CLOSE`, 已关闭 | | ###### 2.3.3 startBinding ```java AlipayGlassV2Sdk.startBinding(map, new BindingCallBack() { @Override public void onGetBindingSchemeSuccess(String bindingScheme, String token) { //收到支付宝绑定页面,跳转scheme } @Override public void onBindingSuccess() { //绑定完成 } @Override public void onBindingFailed(String errorCode) { //绑定失败 } @Override @Deprecated public String getReturnUrl() { return "";//可忽略,在入参map中传入 } @Override @Deprecated public Map onGetBindExtInfo(Map extInfo1, String extInfo2) { return Collections.emptyMap(); } }); ``` 开始绑定,用户点击手机上的【开始绑定】按钮时调用; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | returnUrl | String | 绑定完成后的回跳地址 | 否 | 优先级高于callback中的getReturnUrl | | sourceFrom | String | 发起开通的服务名称来源 | 是 | ("PAYMENT", "支付")
("CAR_PARKING", "停车缴费"),
("CAR_PARKING_MESSAGE", "停车缴费消息"),
("CITY_SIGHTSEEING", "城市导览"),
("GLASSES_WUFU", "五福"),
("GLASSES_HONGBAO", "口令红包"),
("BICYCLE_SERVICE", "两轮车"),
("AQ_SERVICE", "阿福健康管家"),
("QUICK_MODE", "极速模式"), | ~~**onGetBindExtInfo extInfo1返回参数:**~~ | ~~**参数key**~~ | ~~**类型**~~ | ~~**含义**~~ | ~~**返回时机**~~ | ~~**备注**~~ | | :--- | :--- | :--- | :--- | :--- | | ~~AlipayAppDownloadUrl~~ | ~~String~~ | ~~支付宝App下载地址~~ | ~~返回bindingschema时~~ | ~~绑定时,若用户手机未安装支付宝,则提示其下载安装~~ | ###### 2.3.4 receiveDenoiseAudio ```java void receiveDenoiseAudio(byte[] audioData, String codeName, int sampleFormat, int sampleRate, int channelCount, Map audioExt) ``` 接受降噪音频传入,格式要求:pcm,单声道,16000采样率,16位深(AV_SAMPLE_FMT_S16); + 绑定阶段:当进入支付宝小程序读文案界面时,会回调onStartRecording,此时打开麦克风,上传音频; + 支付阶段:识别支付意图时,调用scanpay接口,同时将用户这句话也调用receiveDenoiseAudio传入; **子章节:** 唤起语上传 章节路径:2 对接细则 > 2.3、手机端SDK-Android > 2.3.4 receiveDenoiseAudio > 唤起语上传 唤起语料厂商先做缓存,当识别到支付意愿调用scanpay接口时,同时把唤起语音进行上传,并在扩展字段中填写flowNode标识;调用示例: ```java //唤起语上传 audioExt.put("flowNode", "AROUSE"); receiveDenoiseAudio(data, "pcm", AlipayGlassSdk.AVSampleFormat.AV_SAMPLE_FMT_S16.getSampleType(), 16000, 1, audioExt); //支付过程的流式音频上传 receiveDenoiseAudio(data, codeFmt, AlipayGlassSdk.AVSampleFormat.AV_SAMPLE_FMT_S16.getSampleType(), sampleRate, channelCnt, null) ``` :::warning 注意:唤起语音频上传要在scanpay之后才有效 ::: ###### ~~2.3.5 unbind~~ ```java boolean unbind() ``` 解绑支付宝账号,仅清除眼镜本地缓存uid tid信息; 厂商手机App端解绑按钮建议跳转到支付宝小程序设备页面,进行解绑。跳转地址见**getCustomInfoV2** ###### 2.3.6 sendDeviceLinkAsync 通过蓝牙通道发送数据,异步发送。 ###### 2.3.7 onGateDataReceived ```java String onGateDataReceived(String resData) //example String result = onGateDataReceived(data); if (!TextUtils.isEmpty(result)) { sendDataByBluetooth(result); } ``` 蓝牙通道收到数据后回传给SDK即可;因眼镜端->手机端发送的消息多为同步消息,若onGateDataReceived **有返回值且非空,需将返回值通过蓝牙发到眼镜端。** ###### 2.3.8 scanpay ```java void scanpay(Map params, IScanPayCallbck scanPayCallBack) ``` 调用开始扫码支付;当识别到用户支付意图时,调用前请先检查绑定状态。厂商侧调用 scanpay 同时需要开启回传音频,通过 receiveDenoise 回传,在收到支付结束回调 onErrorEvent(ErrorCode.Q9990) 时关闭音频回传,支付阶段SDK不会回调 startRecording 和 stopRecording。 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | USE_DEMO_MODE | bool | 是否启用演示模式 | 否 | 仅对当笔看码付有效 | | disableTransparent | bool | 是否打开扫码预览 | 否 | | | PAY_INIT_ASR | String | 唤起语文本传入 | 否 | sdk收到后放入initCloudEnv请求中,返回extInfo里面加个PAY_INIT_ASR_INTENTION; 设备通信用initIntentData | **V1.2.2新增字段:** key定义参考Constants.java | tradeNo | String | 如停车缴费订单号 | 否 | | | --- | :--- | :--- | :--- | --- | | verifyId | String | 如gpaasSDK前置核身id | 否 | | | amount | String | 订单金额 | 否 | | | orderStr | String | 外部订单号,需码路由 | 否 | | | tradeStep2SdkState | String | 推进阶段 | 否 | 值为**AlipayGlobalStateChange**中的字符串 | | **v1.2.3加入** | | | | | | launchQuick | bool | 是否快捷唤起(非语音唤起支付) | 否 | true:快捷键唤起 | | scene | String | 场景码 | 否 | Payment, //支付
parkingPay, //停车缴费
bicycle, //共享单车.... | | locationLat | 纬度 | 地理位置 | 否(咖啡必填) | 31.564343 | | locationLnt | 经度 | 地理位置 | 否(咖啡必填) | 120.533231 | | coordType | 坐标系 | 经纬度对应坐标系 | 否(咖啡必填) | 高德:GCJ-02
百度:BD-09 | ###### 2.3.9 command ```java void command(final Map params) ``` 发送指令,比如用户点击眼镜的返回按键、摘下眼镜等时机调用; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | commandCode | int | 指令编码 | 是 | 0:表示退出
1:表示按键命令 | | keyCode | int | 具体按键值 | 否 | | | source | String | 命令来源 | 否 | GlassAppDisconnect:眼镜端glassApp断开连接;
其他退出reason; | ###### 2.3.10 getCustomInfoV2 ```java void getCustomInfoV2(final Map params, CustomInfoCallback callback) ``` 获取客制化的自定义信息; 入参:1)params:表示要获取信息的key, value按需填写; 2)customInfoCallback:返回指定keys的查询信息; 出参:CustomInfoCallback的onCustomInfo中返回要查询的信息; keys取值如下: | **参数key** | **参数Val** | **含义** | **备注** | | :--- | :--- | :--- | :--- | | AlipayAppDownloadUrl | "" | 支付宝App下载地址 | 绑定时,若用户手机未安装支付宝,则提示其下载安装 | | AlipayManageGlassPage | 填写对应来源,如
sourceFrom=PAYMENT/CAR_PARKING.... | 支付宝App管理glass设备的小程序页面 | 解绑时跳转到支付宝小程序设备管理页面,若无支付宝则跳转到下载链接页面;参数Val详见2.3.2节列表 | | currentTradeUrl | "" | 当前交易订单的url地址 | 可跳转到支付宝订单详情页 | | currentAlipayUid | "" | 内部用,获取uid | | | glassDeviceSn | "" | 内部用,获取眼镜sn | | | glassOnBinding | true | 眼镜是否在绑定中 | | | glassOnPaying | false | 眼镜是否在支付中 | | ```plain String customKeys = new HashMap(); customKeys.put("AlipayAppDownloadUrl", ""); customKeys.put("AlipayManageGlassPage", "sourceFrom=CAR_PARKING"); AlipayGlassV2Sdk.getCustomInfoV2(customKeys, new CustomInfoCallback() { @Override public void onCustomInfo(String data, Map extInfo) { //data暂未使用; extInfo中为各个key对应的信息 } }); ``` ###### 2.3.11 setWearingState ```java void setWearingState(boolean wearing) ``` 接口定义:public void setWearingState(boolean wearing) 入参:wearing=true表示眼镜戴上,false表示眼镜摘下; 功能描述:当眼镜佩戴状态发生变化时,通知眼镜sdk; 调用时机:当眼镜佩戴状态发生变化时调用; ###### 2.3.12 日志重定向 接口:setLogger 功能:用于将眼镜SDK的日志重定向到厂商日志中,便于后续客户端问题排查;Log等级跟随厂商设置,一般release包设置为Info,debug包设置为Verbose; ```json public class AlipayLogger extends Logger { @Override public int verbose(String tag, String msg) { //重定向输出到厂商log文件 return 0; } //。。。其他日志接口实现 } com.alipay.glass.log.Log.setLogger(new AlipayLogger()); ``` ###### 2.3.13 startAlipayService ```java String startAlipayService(final String appId, final String serviceCode, final Map params, final GAlipayCallback callback); void stopAlipayService(final String appId, final String serviceCode, final Map params, final String sessionId, final GAlipayCallback callback) ``` 启动/停止支付宝服务,serviceCode为具体的服务编码;厂商侧调用 startAlipayService 同时需要开启回传音频,通过 receiveDenoise 回传,在收到支付结束回调 onErrorEvent(ErrorCode.Q9990) 时关闭音频回传,支付阶段SDK不会回调 startRecording 和 stopRecording。 params参数:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | USE_DEMO_MODE | bool | 是否启用演示模式 | 否 | 仅对当笔看码付有效 | | disableTransparent | bool | 是否打开扫码预览 | 否 | | | PAY_INIT_ASR | String | 唤起语文本传入 | 否 | sdk收到后放入initCloudEnv请求中,返回extInfo里面加个PAY_INIT_ASR_INTENTION; 设备通信用initIntentData | V1.2.2新增字段:key定义参考Constants.java | tradeNo | String | 如停车缴费订单号 | 否 | | | :--- | :--- | :--- | :--- | :--- | | verifyId | String | 如gpaasSDK前置核身id | 否 | | | amount | String | 订单金额 | 否 | | | orderStr | String | 外部订单号,需码路由 | 否 | | | tradeStep2SdkState | String | 当前推进阶段 | 否 | 值为**AlipayGlobalStateChange**中的枚举值的字符串 | ##### 2.4、手机端SDK-iOS ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/196456339/1773907528089-d78e3466-81e2-4cf4-a980-991922b183fb.png) + 把以上所有包引入iOS工程中,并在Target->buildSrttings->otherLinkerFlage中添加-ObjC + 需要在info中添加跳转支付宝的schemes白名单alipays + 如果是Swift项目则需要桥接文件,然后引入 **AlipayGlassSDK.h文件** + Resources.bundle为音频资源,支付过程中眼镜端无法播放提示音时可发送指令由手机端播放提示音,如不需要可不引入 + ios_websocket_sdk.framework为动态库,其他为静态库 + iOS端主要接口类:**AlipayGlassSDK.h** + iOS端权限相关:需要蓝牙和麦克风权限、用于数据交互和识别语音指令 ###### 2.4.1、初始化 ```plain ///需要实现的相关协议,详情请查看AlipayGlassSDK.h文件 ///APGSDKSendToDeviceDelegate 设备通信回调 ///BluetoothCenterDelegate 蓝牙代理 ///BindStatusCallBack 绑定状态回调 ///BindingCallBack 绑定回调 ///IScanPayCallBack 支付相关回调 ///CustomInfoCallback 客制化自定义参数接口回调 @interface ViewController () ///初始化 [AlipayGlassSDK initSDK:@{ AlipayGlassInitKeyIsvName: @"", //眼镜设备的厂商名称 AlipayGlassInitKeySN: @"", //眼镜设备的sn AlipayGlassInitKeyDeviceModel: @"", //眼镜设备类型 AlipayGlassInitKeySupportNetwork: @(NO), //是否可联网 AlipayGlassInitKeyPhoneSysType: @"" //Android iOS等 AlipayGlassInitKeyAPGBlueSheildImageName: @"" //非必填,用于多bundleID场景,不同环境上传不同加密图片名称如nearx_bs_dev,nearx_bs_dis } delegate:self]; ``` **注** 入参说明同Android端。其中APGSDKSendToDeviceDelegate#onPrintLog务必实现,重定向SDK日志打印,用于排查问题; ###### 2.4.2 getBindStatus 获取眼镜的绑定状态;在手机端展示绑定状态 或者每次发起支付前调用;若未绑定,提示用户去厂商App中进行绑定;**featureList和具体详情请参考Android部分的说明。** + needCloudStatus=true, 查询云端状态,一般填true; + needCloudStatus=false, 查询本地缓存状态; ```java ///获取绑定状态 [AlipayGlassSDK getBindStatus:self needCloudStatus:YES]; ///同时获取设备自定义参数接口,参数下面getCustomInfo有说明 [AlipayGlassSDK getCustomInfo:@[AlipayGlassCustomInfoKeyAlipayAppDownloadUrl, AlipayGlassCustomInfoKeyAlipayManageGlassPage] callback:self]; ///结果回调 - (void)onGetBindStatus:(BOOL)isBinded { } ``` ###### 2.4.3 startBinding ```java ///蓝牙链接状态下发起绑定 [AlipayGlassSDK startBinding:@{AlipayGlassBindParamKeyReturnUrl:@""} callback:self]; ///相关回调,拿到回调参数后跳转支付宝 - (void)onGetBindingSchemeSuccess:(NSString*)bindingScheme token:(NSString*)token { } ///成功 - (void)onBindingSuccess { } ///失败 - (void)onBindingFailed:(NSString *)errorCode { } ///额外信息 - (NSDictionary *)onGetBindExtInfo:(NSDictionary *)extInfo1 extInfo2:(NSString *)extInfo2 { return @{}; } ``` 开始绑定,用户点击手机上的【开始绑定】按钮时调用; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | returnUrl | String | 绑定完成后的回跳地址 | 否 | 优先级高于callback中的getReturnUrl | **onGetBindExtInfo extInfo1返回参数:** | **参数key** | **类型** | **含义** | **返回时机** | **备注** | | :--- | :--- | :--- | :--- | :--- | | AlipayAppDownloadUrl | String | 支付宝App下载地址 | 返回bindingschema时 | 绑定时,若用户手机未安装支付宝,则提示其下载安装 | ###### 2.4.4 receiveDenoiseAudio 接受降噪音频传入,格式要求:pcm,单声道,16000采样率,16位深(AV_SAMPLE_FMT_S16); + 绑定阶段:当进入支付宝小程序读文案界面时,会回调onStartRecording,此时打开麦克风,上传音频; + 支付阶段:识别支付意图时,调用scanpay接口,同时将用户这句话也调用receiveDenoiseAudio传入; **子章节:** 唤起语上传 章节路径:2 对接细则 > 2.4、手机端SDK-iOS > 2.4.4 receiveDenoiseAudio > 唤起语上传 唤起语料厂商先做缓存,当识别到支付意愿调用scanpay接口时,同时把唤起语音进行上传;在扩展字段中填写{"flowNode":"AROUSE"}; ```java [AlipayGlassSDK receiveDenoiseAudio:pcmData codeName:@"pcm" sampleFormat:APGAVSampleFormatS16 sampleRate:16000 channelCount:1 audioExt:@{}]; ``` ###### ~~2.4.5 unbind~~ 解绑支付宝账号,仅清除眼镜本地缓存uid tid信息; 厂商手机App端解绑按钮建议跳转到支付宝小程序设备页面,进行解绑。 ###### 2.4.6 sendDeviceLinkAsync 通过蓝牙通道发送数据,异步发送。 ###### 2.4.7 onGateDataReceived 蓝牙通道收到数据后回传给SDK即可,若onGateDataReceived **有返回值且非空,需将返回值通过蓝牙发到眼镜端。** ###### 2.4.8 scanpay 调用开始扫码支付;当识别到用户支付意图时,调用前请先检查绑定状态。厂商侧调用 scanpay 同时需要开启回传音频,通过 receiveDenoise 回传,在收到支付结束回调 onErrorEvent(ErrorCode.Q9990) 时关闭音频回传,支付阶段SDK不会回调 onStartRecording 和 stopRecording。 入参:(详见GlasspayConfig.java中定义),详细说明参考Android部分 ```java [AlipayGlassSDK scanpay:@{AlipayGlassScanPayExtKeyPayInitASR:@"支付一元"} scanpayCallback:self]; ///开启音频 dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(3 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{ [self actionRecord:nil]; }); ///相关回调 /** * 支付成功 * @param scanResult 支付结果 */ -(void)onScanSuccess:(APGScanResult *)scanResult { } /** * 扫码失败 * @param errorCode 1001 扫码超时 、 1002 摄像头异常 、1003 网络异常 、 1004 系统繁忙 、 1005 用户取消 、 1006 暂不支持扫描的码 */ -(void)onScanFailed:(int)errorCode { } /** * 扫码中间过程的回调 * @param process 过程id * @param tips 文案描述 */ -(void)onScanProcess:(int)process tips:(NSString *)tips { } /** * 支付接口回调 * @param resultCode 9000 支付成功、 8000 支付结果未知,需要提示用户找商家确认、4000 支付失败 * @param memo 支付结果提示文案 */ -(void)onPayResult:(NSString *)resultCode memo:(NSString *)memo { } ``` ###### 2.4.9 command 发送指令,比如用户点击眼镜的返回按键、摘下眼镜等时机调用; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | commandCode | int | 指令编码 | 是 | 0:表示退出
1:表示按键命令 | | keyCode | int | 具体按键值 | 否 | | | source | String | 命令来源 | 否 | GlassAppDisconnect:眼镜端glassApp断开连接 | ###### 2.4.10 getCustomInfoV2 void getCustomInfoV2( Map params, ICustomInfoCallback callback) 获取客制化的自定义信息; 入参:1)params:表示要获取信息的key, value按需填写; 2)customInfoCallback:返回指定keys的查询信息; 出参:CustomInfoCallback的onCustomInfo中返回要查询的信息; keys取值如下: | **参数key** | **参数Val** | **含义** | **备注** | | :--- | :--- | :--- | :--- | | AlipayAppDownloadUrl | "" | 支付宝App下载地址 | 绑定时,若用户手机未安装支付宝,则提示其下载安装 | | AlipayManageGlassPage | 若从非看一下进入填写对应来源,如
source=CAR_PARKING | 支付宝App管理glass设备的小程序页面 | 解绑时跳转到支付宝小程序设备管理页面,若无支付宝则跳转到下载链接页面 | | currentTradeUrl | "" | 当前交易订单的url地址 | 可跳转到支付宝订单详情页 | | currentAlipayUid | "" | 内部用,获取uid | | | glassDeviceSn | "" | 内部用,获取眼镜sn | | | glassOnBinding | | 眼镜是否在绑定中状态 | | | glassOnPaying | | 眼镜是否在支付中状态 | | ```plain ///获取自定义信息 [AlipayGlassSDK getCustomInfo:@[AlipayGlassCustomInfoKeyAlipayAppDownloadUrl, AlipayGlassCustomInfoKeyAlipayManageGlassPage] callback:self]; ///回调信息 - (void)onCustomInfo:(NSString *)data extInfo:(NSDictionary *)extInfo { } ``` ###### 2.4.11 setWearingState 接口定义:setWearingState(boolean wearing) 入参:wearing=true表示眼镜戴上,false表示眼镜摘下; 功能描述:当眼镜佩戴状态发生变化时,通知眼镜sdk; 调用时机:当眼镜佩戴状态发生变化时调用; ###### 2.4.12 日志重定向onPrintLog 定义:APGSDKSendToDeviceDelegate代理方法(void)onPrintLog:(NSString*)log 功能:SDK内日志输出,对接中此方法一定要实现,便于排查问题 ###### 2.4.13 startAlipayService 启动/停止支付宝服务,serviceCode为具体的服务编码;厂商侧调用 startAlipayService 同时需要开启回传音频,通过 receiveDenoise 回传,在收到支付结束回调 onErrorEvent(ErrorCode.Q9990) 时关闭音频回传,支付阶段SDK不会回调 startRecording 和 stopRecording。 params参数:(详细说明参考Android部分GlasspayConfig.java中定义) ```plain /** * 启动服务,用于非扫码业务,参数同上 * @param appId 预留参数 * @param serviceCode 预留参数 * @param params 同scanpay */ + (void)startAlipayService:(NSString *)appId serviceCode:(NSString *)serviceCode params:(NSDictionary * _Nullable )params callback:(id)callback; @protocol GAlipayCallback /** *startAlipayService接口相关结果回调 */ - (void)onResponse:(APGAlipayResponse *)response; /** * 组件状态回调接口 * @param eventId 跟组件注册的componentId保持一致 * @param data 组件透传数据 * @param extra 额外扩展字段 */ - (void)onEvent:(NSString*)eventId data:(NSString*)data extra:(NSDictionary*)extra; @end ``` ##### 2.5、交互流程 ###### 2.5.1 绑定流程 ```mermaid sequenceDiagram autonumber participant ISVPhone as 厂商手机App participant ZFBApp as 手机支付宝App participant PhoneSDK as 手机眼镜SDK participant GlassApp as 眼镜支付Apk participant OPENAPI as 支付宝服务端 activate ISVPhone ISVPhone->>PhoneSDK: InitSDK初始化眼镜SDK ISVPhone->>PhoneSDK: 查询绑定状态getBindStatus PhoneSDK->>GlassApp: getBindStatus GlassApp-->>PhoneSDK: onGetBindStatus返回绑定状态 PhoneSDK-->>ISVPhone: 返回绑定状态 alt 已绑定 ISVPhone->>ISVPhone: 绑定结束 else 未绑定 ISVPhone->>PhoneSDK: 点击去绑定startBinding PhoneSDK->>GlassApp: 发送startBinding请求 GlassApp->>GlassApp: initCloudEnv初始化
startBindingProcess串联核身 GlassApp-->>PhoneSDK: 返回绑定schema PhoneSDK-->>ISVPhone: onGetBindingSchemeSuccess返回schema ISVPhone->>ZFBApp: 打开绑定小程序 ZFBApp->>ZFBApp: 用户绑定操作 GlassApp->>GlassApp: 打开麦克风
用户朗读文案 GlassApp->>ISVPhone: 小核传输音频到手机端 ISVPhone->>PhoneSDK: 降噪音频receiveDenoiseAudio PhoneSDK->>OPENAPI: wss上传音频 loop 轮询绑定状态
无网眼镜需手机转发 GlassApp->>OPENAPI: 轮询绑定状态 OPENAPI-->>GlassApp: 返回绑定状态 end GlassApp-->>PhoneSDK: 返回绑定状态 PhoneSDK-->>ISVPhone: onBindingSuccess/onBindingFailed
返回绑定状态 end ISVPhone->>PhoneSDK: releaseSDK deactivate ISVPhone ``` ###### 2.5.2 支付流程 ```mermaid sequenceDiagram autonumber participant ISVPhone as 厂商手机App participant PhoneSDK as 手机眼镜SDK participant GlassApp as 眼镜支付Apk participant OPENAPI as 支付宝服务端 activate ISVPhone ISVPhone->>PhoneSDK: InitSDK初始化眼镜SDK ISVPhone->>PhoneSDK: 识别到支付意图scanpay
同时receiveDenoiseAudio上传唤起语 PhoneSDK->>GlassApp: scanpay GlassApp->>GlassApp: 打开相机开始扫码 GlassApp->>GlassApp: 扫到码值 alt 带金额码值 GlassApp->>GlassApp: 播音请确认支付 else 无金额码值 GlassApp->>GlassApp: 播音请输入金额 ISVPhone->>PhoneSDK: 用户语音输入/修改金额 PhoneSDK->>OPENAPI: wss上传音频 OPENAPI-->>PhoneSDK: 返回金额意图 PhoneSDK->>GlassApp: 金额意图 GlassApp->>GlassApp: 播音即将支付xx元,请说确认支付 end ISVPhone->>PhoneSDK: 用户语音确认支付 PhoneSDK->>OPENAPI: wss上传音频 OPENAPI-->>PhoneSDK: 返回确认意图 PhoneSDK->>GlassApp: 确认意图 GlassApp->>PhoneSDK: 确认支付rpc PhoneSDK-->>GlassApp: 确认支付结果
播音支付成功/失败 GlassApp-->>PhoneSDK: 返回支付结果 PhoneSDK-->>ISVPhone: IScanPayCallBack返回结果 ``` #### 3 错误码 | **错误码** | **错误描述** | **解决方案** | | :--- | :--- | :--- | | 1001 | 扫码超时 | 检查二维码是否破损并重试 | | 1002 | 摄像头异常 | 重启设备,检查摄像头是否正常 | | 1003 | 网络异常 | 检查网络是否正常 | | 1004 | 系统繁忙 | 1、绑定失败重试超过100次;
2、码路由信息解析异常 | | 1005 | 用户取消扫码 | 用户主动关闭,无需处理 | | 1006 | 暂不支持扫描的码 | 更换支持的支付宝收款码、经营码等 | | 1007 | 手机端解绑 | 重新绑定设备 | | 1011 | 重复发起支付 | 完成支付流程再发起支付 | | 1012 | 未绑定支付宝账号 | 先绑定再发起支付 | | 4000 | 1、系统繁忙,请稍后再试
2、手机端解绑
3、付款功能关闭
4、支付超出限额 | 根据errorMessage具体处理 | | 8000 | 支付结果未知,请与商家确认 | 联系商户确认支付结果 | | 9000 | 支付成功 | 无需处理 | ```java Q9990("AlipayGlassSDKExit", "眼镜SDK已退出,通知厂商侧语音助手退出技能,恢复到Idle状态等待下次唤醒"), Q9991("AlipayGlobalStateChange", "通知厂商SDK状态机变化"), //客户端本地错误码: Q100001("扫码超时", "检查二维码是否破损并重试"), Q100002("摄像头异常", "重启设备,检查摄像头是否正常"), Q100003("网络异常", "检查网络是否正常"), Q100004("系统繁忙", "绑定失败重试超过100次/码路由信息解析异常"), Q100005("用户取消扫码", "用户主动关闭,无需处理"), Q100006("无效二维码,请扫描支付宝收款码", "更换支持的支付宝收款码、经营码等"), Q100007("还没绑定支付宝哦,去手机App完成绑定吧", "重新绑定设备"), Q100008("扫码超时", "检查二维码是否破损并重试"), Q100009("看蓝环超时", "请正对蓝环设备并重试"), Q100010("网络或蓝牙连接异常,请使用手机支付宝付款", "网络或蓝牙连接异常,请使用手机支付宝付款"), Q100011("网络或蓝牙连接异常", "网络或蓝牙连接异常"), Q100012("支付APP已断开", "眼镜端glassApp已断开,手机端sdk进行释放重置,请稍后再重试"), Q100023("摄像头异常", "重启设备,检查摄像头是否正常"), Q100030("请勿重复发起支付", "重复发起支付"), Q100031("流程超时", "超时退出"), //服务端错误码: Q100500("支付结果未知,请和商家确认", "通用错误提示"), Q100501("支付结果未知,请和商家确认", "请求失败"), Q100504("支付账号已解绑,请重新绑定", "通用错误提示"), Q100507("支付结果未知,请和商家确认", "支付请求网络失败"), Q100558("支付账号已解绑,请重新绑定", "PAY_RESULT_ALREADY_UNBIND"), Q100559("请在手机端打开付款功能", "PAY_RESULT_PAYMENT_CLOSED"), Q100560("支付超出限额,请用手机支付宝付款", "PAY_RESULT_EXCEED_LIMIT"), Q100561("无效二维码,请扫描支付宝收款码", "PAY_RESULT_UNSUPPORT_CODE"), Q100562("资金不足,支付失败", "PAY_RESULT_BALANCE_NOT_ENOUGH"), Q100563("发现非本人操作,支付已终止。", "PAY_RESULT_VERIFY_FAIL"), Q100564("请不要扫自己的码", "PAY_RESULT_UNSUPPORT_CODE"), Q100565("没听清,请说确认支付", "PAY_RESULT_CODE_VERIFY_PENDING"), Q100566("二维码无法识别", "通用错误提示"), Q100600("需要语音确认,请说确认支付", "PAY_RESULT_QUICKMODE_FAIL"), Q100599("支付结果未知,请和商家确认", "PAY_RESULT_FAIL"), Q100598("支付结果未知,请和商家确认", "客户端代码异常"), Q100597("支付结果未知,请和商家确认", "json解析异常"), Q100596("支付结果未知,请和商家确认", "出了点问题,问问商家支付成功了吗"), Q100595("已退出支付", "支付过程中如果双击退出则不在遍历结果"), Q100594("订单交易失败,请在手机端支付", "PAY_RESULT_TRADE_FAIL--缴费、点咖啡等创单失败"), Q100570("支付结果未知,请和商家确认", "等待码路由结果超时"), Q100571("退出支付", "语音意图主动退出支付"), Q100572("退出支付", "command退出支付"), Q100573("输入金额超时", "输入金额超时"), Q100574("确认支付超时", "确认支付超时"), Q100575("修改额度失败", "修改额度失败"), Q100576("支付超时", "支付超时"), //场景操作超时 Q100577("无绑定手机号", "无绑定手机号") ``` #### 4 接入前需要准备好的资源 :::warning 1. **需要收集厂商手机APP的应用签名md5和包名(iOS端BundleId和TeamIdentifier),做签名校验** 1. **Android拿到蓝盾图片nearx_bs.jpg后,放到对应的工程中的app主模块下的assets根目录下即可** 2. **IOS需要放在mainBundle里,图片名称需要为nearx_bs.jpg** 3. **Harmony将nearx_bs.jpg放到主工程entry/src/main/resources/base/media下** 2. **另需搜集眼镜端对接SDK的应用 包名和sha265,用于IPC调用安全校验** ![](https://intranetproxy.alipay.com/skylark/lark/0/2025/png/185656632/1756194675676-0b7350bd-6777-42cd-987b-5c6062f1ff57.png) 4. **支付宝网关侧对接入厂商需要配置appId,接入前需要做好配置,傲凌\莫程** 5. **搜集眼镜型号(brand和model),否则绑定阶段小程序无法跳转** ::: **信息模板:** | **类别** | **厂商提供值** | **含义** | **备注** | | --- | --- | --- | --- | | isvName | | 厂商名称 | | | deviceModel | | 设备型号 | | | 语音唤醒词 | | 语音助手唤醒词 | | | 安卓apk包名 | | 应用包名 | | | 安卓apk签名 | | 应用签名 | apksigner verify -verbose --print-certs ,提供MD5值 | | IOS包名 | | 应用包名 | IOS应用的Bundle Identifier‌ | | 鸿蒙包名 | | 应用包名 | | --- ### 智能耳机支付宝AI付接入文档 目录路径:智能终端设备 > 智能耳机支付宝AI付接入文档 来源:https://aipay.alipay.com/docs/device-agent-pay/sdk-intro-for-smart-earphone.md 说明智能耳机如何接入支付宝SDK #### 1 文档说明 本文档适用于厂商智能耳机/无摄像头眼镜接入支付宝AI支付,包括输出产物、API接口说明和交互流程。 **注:**本文档采用的是**纯手机端SDK方案**,无需设备端改动,适用于无摄像头的RTOS**耳机或眼镜**; ##### 1.1 产品方案 随着智能家居、智能终端、智能穿戴设备的普及,语音助手已成为用户日常交互的重要入口。其场景化服务能力持续向生活服务纵深拓展。 ###### 1.1.1 绑定流程交互 耳机需要绑定支付宝账号,录入声纹才能使用支付功能。绑定后默认开通了交话费,瑞幸咖啡的能力。 + 厂商侧要记录已开未开通支付的状态 + 厂商测需要有常驻的入口,引导用户去开通耳机端的支付宝 + 语音助手要增加意图关键词:开通支付宝,绑定支付宝,解绑支付宝,关闭支付宝 ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/11743/1780020369630-d5f8823d-cebe-4dd9-8ba1-d190d4a77063.png) **子章节:** 停车缴费需要单独开通: 章节路径:1 文档说明 > 1.1 产品方案 > 1.1.1 绑定流程交互 > 停车缴费需要单独开通: 已开通耳机支付宝后,用户在耳机上操作:停车缴费,需要引导用户去录入车牌 ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/11743/1780020639176-b66c0d07-4940-4811-bbec-8086a93c3669.png) 也可以在支付宝端内单独打开 ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/11743/1780020543773-d12e5e26-d058-4c45-a862-a1e53d4ab67c.png) ###### 1.1.2 交话费用户交互 交话费和停车缴费都是属于支付宝的一方应用(支付宝内自闭环) ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/11743/1780021736278-4dfe2f9d-2dae-4010-9059-165be69f8a76.png) ###### 1.1.3 厂商关键词配置 | **场景** | **厂商唤醒关键词** | **示例** | | --- | --- | --- | | 缴话费 | 交话费、充话费、缴话费、手机充值、电话充值
金额结合型(用户意图明确)
+ 【动词】+【话费/元】:充50话费、交100元、充200块话费 | 帮我充值、帮我交话费、帮我手机充值50元、
帮我交50元话费、我要充50元话费、 | | 停车缴费 | XX 停车缴费、XX停车费、
给【XX车牌号】交下停车费、停车费怎么交? | 乐奇,停车缴费、帮我停车缴费、启动停车缴费
小爱同学,停车缴费、给我交停车费、
交一下停车费、付停车费、给这辆车交下停车费
浙A28372交停车费 | | 点咖啡 | 点一杯、来一杯、我要点、点杯、来杯 **+** 咖啡名(奥瑞白、杨枝甘露、鲜萃、美式、拿铁、咖啡)/瑞幸
新增:推荐一杯好喝的、推荐一杯、推荐新品 | 帮我点杯咖啡、帮我点一杯瑞幸咖啡、点一杯瑞幸咖啡、来一杯瑞幸咖啡、来一杯咖啡、我要点咖啡、点杯咖啡、请帮我点⼀杯柠C美式、来一杯 XXXX 咖啡、点一杯XXXX咖啡、来杯精萃澳瑞白、点一杯生椰杨枝甘露、点杯鲜萃轻轻茉莉 | ##### 1.2 支付宝输出产物 | **平台** | **产物** | **功能与说明** | | --- | --- | --- | | Android | 支付宝安卓SDK | 支付宝智能体业务和支付、核身逻辑处理 | | IOS | 支付宝IOS SDK | 同安卓 | | Harmony | 支付宝鸿蒙SDK | 同安卓 | ##### 1.3 系统框图 ![画板](https://intranetproxy.alipay.com/skylark/lark/0/2026/jpeg/198428/1782118100649-25112811-85be-4b8e-b886-6c7fc67eb429.jpeg) #### 2 接口说明 主要接口类:**AlipayGlassV2Sdk** ##### 2.1 initSDK初始化 ```java AlipayGlassV2Sdk.initSDK(context, extParams, new GlassSDKCallback() { //开启录音,发起绑定后回调,开启后需要在receiveDenoiseAudio传入降噪音频 @Override public void onStartRecording(String token) { //startRecordAudio(true); } @Override public void onStopRecording() { //startRecordAudio(false); } //播放支付过程提示文案 @Override public String onStartPlayback(String ttsData) { return null; } //佩戴状态检测 @Override public boolean onWearDetection() { return true; } @Override public void onErrorEvent(String code, String message) { //错误回调 //○ Q1010/1011:sdk调用initCloudEnv失败,或者wss建联失败;收到此错误码仅需播音提示用户。 //○ Q9990:glassSDK已释放退出 } @Override public void onEvent(String eventId, String eventData, Map extInfo) { //SDK内的事件回调,updateView、推进状态等 //Q9991状态机事件回调,SDK_ENTER/SDK_EXIT表示服务进入和退出 //webSyncDownData:长连接推送消息,如咖啡制作状态等 } @Override public void onViIntentResult(String bizType, String dataJson, Map extInfo) { //核身和意图回调:厂商按需处理 } }); ``` 初始化SDK,在手机App和耳机建立连接时调用,支持重复调用; 入参:(入参key详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | --- | | isvName | String | 厂商名称 | 是 | | | deviceModel | String | 设备机型 | 是 | | | deviceSN | String | 设备SN | 是 | | | productType | String | 产品类型 | 否 | 耳机或无摄像头眼镜时,传"earphones" | ##### 2.2 getBindStatus 获取设备的绑定状态和服务开通状态; + 调用时机:在手机端展示服务状态或者每次发起支付前调用;若未开通该服务,提示用户去厂商App中发起开通; + 入参说明: - needCloudStatus=true, 查询云端状态,一般填true; - needCloudStatus=false, 查询本地缓存状态; + 出参说明: | **字段** | **类型** | **说明** | **示例** | | --- | --- | --- | --- | | isBinded | boolean | 账号绑定状态;(基本废弃,厂商根据featureStatusList判断服务是否开通) | true/false | | extInfo | Map | 扩展信息 | | | \|-featureStatusList | String | 服务开通状态,若已开通则同时返回对应的manageUrl。各服务编码说明:
("PAYMENT", "支付")(包含充话费、点咖啡、电影票等)
("CAR_PARKING", "停车缴费"),
("CAR_PARKING_MESSAGE", "停车缴费消息"),
("CITY_SIGHTSEEING", "城市导览"),
| featureStatusList":["{\"featureId\":\"CAR_PARKING\",\"status\":\"STATUS_BIND\"}","{\"featureId\":\"PAYMENT\",\"status\":\"STATUS_BIND\"}","{\"featureId\":\"QUICK_MODE\",\"status\":\"STATUS_UNBIND\"}","
{\"featureId\":\"PAYMENT\",\"status\":\"STATUS_BIND\", \"manageUrl\":\"`http:xxx`\"}","{\"featureId\":\"PAY_DEMO\",\"status\":\"STATUS_BIND\"}"]}
注:若服务从未开通过,则列表不展示 | | \|-verifyMethodStatus | 核身方式录入状态 | VERIFY_VOICE | OPEN,表示已录入 | ##### 2.3 startBinding ```java AlipayGlassV2Sdk.startBinding(map, new BindingCallBack() { @Override public void onGetBindingSchemeSuccess(String bindingScheme, String token) { //收到支付宝绑定页面,跳转scheme } @Override public void onBindingSuccess() { //绑定完成 } @Override public void onBindingFailed(String errorCode) { //绑定失败 } }); ``` 发起服务开通,当用户点击手机上的【去支付宝开通】按钮时调用; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | returnUrl | String | 绑定完成后的回跳地址 | 否 | 优先级高于callback中的getReturnUrl | | sourceFrom | String | 发起开通的服务入口 | 是 | ("PAYMENT", "支付")(含充话费、点咖啡等支付业务),
("CAR_PARKING", "停车缴费"),
("CITY_SIGHTSEEING", "城市导览"), | ##### 2.4 receiveDenoiseAudio 接收降噪音频传入,格式要求:pcm,单声道,16000采样率,16位深(AV_SAMPLE_FMT_S16); + 绑定阶段:当进入支付宝小程序读文案界面时,会回调onStartRecording,此时打开麦克风,上传音频; + 支付阶段:识别智能体或支付意图时,调用startAlipayService接口,同时将用户这句唤醒语也调用receiveDenoiseAudio传入; ###### 唤起语上传 唤起语料需厂商先做缓存,当识别到支付意愿调用scanpay/startAlipayService接口时,同时把唤起语音进行上传;同时在扩展字段中填写 extParams.put("flowNode", "AROUSE"); :::warning 注意:唤起语音频上传要在startAlipayService/scanpay之后才有效 ::: ##### 2.5 unbind + 解绑支付宝账号,仅清除设备本地缓存uid tid信息(不会清除支付宝小程序里的设备); + 厂商手机App端解绑按钮建议跳转到支付宝小程序设备页面,进行解绑: - 可调用getBindStatus或getCustomInfoV2,得到manageUrl后,跳转到支付宝小程序管理页进行解绑; ##### 2.6 command 发送指令,比如用户点击耳机或眼镜的返回按键、摘下耳机/眼镜等时机调用; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | commandCode | int | 指令编码 | 是 | 0:表示退出
1:表示按键命令 | | keyCode | int | 具体按键值 | 否 | | | source | String | 命令来源 | 否 | 摘下、双击退出键等 | 当摘掉耳机或眼镜时,退出支付流程 ```java params.put(GlasspayConfig.KEY_COMMAND_CODE, GlasspayConfig.CommandCode.EXIT); params.put("source", "wearOff"); AlipayGlassV2Sdk.command(params); ``` ##### 2.7 getCustomInfoV2 ```java void getCustomInfoV2(final Map params, CustomInfoCallback callback) ``` 获取客制化的自定义信息; 入参:1)params:表示要获取信息的key, value按需填写; 2)customInfoCallback:返回指定keys的查询信息; 出参:CustomInfoCallback的onCustomInfo中返回要查询的信息; keys取值如下: | **参数key** | **参数Val** | **含义** | **备注** | | :--- | :--- | :--- | :--- | | AlipayAppDownloadUrl | "" | 支付宝App下载地址 | 绑定时,若用户手机未安装支付宝,则提示其下载安装 | | AlipayManageGlassPage | 填写对应来源,如
sourceFrom=PAYMENT/CAR_PARKING.... | 支付宝App对应的服务管理的小程序页面 | 若未安装支付宝则跳转到下载链接页面;
sourceFrom的服务与getBIndStatus返回的featureStatusList中的服务相同; | | currentTradeUrl | "" | 当前交易订单的url地址 | 可跳转到支付宝订单详情页 | | currentAlipayUid | "" | 内部用,获取uid | | ```plain String customKeys = new HashMap(); customKeys.put("AlipayAppDownloadUrl", ""); customKeys.put("AlipayManageGlassPage", "sourceFrom=CAR_PARKING"); AlipayGlassV2Sdk.getCustomInfoV2(customKeys, new CustomInfoCallback() { @Override public void onCustomInfo(String data, Map extInfo) { //data暂未使用; extInfo中为各个key对应的信息 } }); ``` ##### 2.8 setWearingState 接口定义:public void setWearingState(boolean wearing) 入参:wearing=true表示设备戴上,false表示设备摘下; 调用时机:当设备佩戴状态发生变化时调用; ##### 2.9 startAlipayService ```java String startAlipayService(final String appId, final String serviceCode, final Map params, final GAlipayCallback callback); void stopAlipayService(final String appId, final String serviceCode, final Map params, final String sessionId, final GAlipayCallback callback) ``` 启动/停止支付宝服务,serviceCode为具体的服务编码;厂商侧调用 startAlipayService 同时需要开启回传音频,通过 receiveDenoise 回传,在收到支付结束回调 onErrorEvent(ErrorCode.Q9990) 时关闭音频回传; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | --- | :--- | :--- | :--- | --- | | PAY_INIT_ASR | String | 唤起语文本传入 | 是 | | | orderStr | String | 外部订单号,需码路由 | 否 | 预下单后调用支付 | | scene | String | 场景码 | 否(智能体场景需填写) | Coffee, //点咖啡
TopUp, //充话费
MovieTicket, //电影票 | | locationLat | String | 地理位置-纬度 | 否(咖啡必填) | 31.564343 | | locationLnt | String | 地理位置-经度 | 否(咖啡必填) | 120.533231 | | coordType | String | 经纬度对应坐标系 | 否(咖啡必填) | 高德:GCJ-02
百度:BD-09 | | codeResultString | String | 外部码值 | 否 | 外部设备端扫码得到支付宝码值 | | codeResultNeedDecrypt
| String | 码值是否需要解密 | 否 | 外置独立扫码启用加密时传true | ###### 调用示例 ```c Map params = new HashMap<>(); params.put("PAY_INIT_ASR", "帮我交50元话费"); params.put("scene", "TopUp"); AlipayGlassV2Sdk.startAlipayService("appId", "TopUp", params, new GAlipayCallback() { @Override public void onResponse(GAlipayResponse response) { Log.i(TAG, "onResponseresponse=" + response); } @Override public void onEvent(String eventId, String data, Map extra) { Log.i(TAG, "onEvent, eventId=" + eventId + ",data=" + data + ",extra=" + extra); } }); ``` ```c Map params = new HashMap<>(); params.put("PAY_INIT_ASR", "帮我点一杯咖啡"); params.put(GlasspayConfig.KEY_SCENE, "Coffee"); params.put(GlasspayConfig.KEY_LOCATION_LONGITUDE, "120.104739"); params.put(GlasspayConfig.KEY_LOCATION_LATITUDE, "30.261124000000017"); AlipayGlassV2Sdk.startAlipayService("appId", "Coffee", params, new GAlipayCallback()); ``` ##### 2.10 日志重定向 **接口:setLogger** **功能:用于将支付SDK的日志重定向到厂商日志中,便于后续客户端问题排查;Log等级跟随厂商设置,一般release包设置为Info,debug包设置为Verbose;** ```json public class AlipayLogger extends Logger { @Override public int verbose(String tag, String msg) { //重定向输出到厂商log文件 return 0; } //。。。其他日志接口实现 } com.alipay.glass.log.Log.setLogger(new AlipayLogger()); ``` #### 3 交互流程 ##### 3.1 用户动线 ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/jpeg/198428/1775011543682-ba6bef45-6277-4830-9ae4-acec0e2b26ab.jpeg) ##### 3.2 绑定流程 + 绑定支付宝账号、录入声纹、开通支付 ```mermaid sequenceDiagram autonumber participant ISVPhone as 厂商手机App participant PAYSDK as 支付SDK participant ZFBApp as 手机支付宝App participant LauncherApp as 厂商耳机 participant OPENAPI as 支付宝服务端 activate ISVPhone ISVPhone->>PAYSDK: initSDK初始化 ISVPhone->>PAYSDK: 查询绑定状态getBindStatus PAYSDK->>OPENAPI: queryBindStatus OPENAPI-->>PAYSDK: 绑定状态应答 PAYSDK-->>ISVPhone: 返回绑定状态 alt 已绑定 ISVPhone->>ISVPhone: 显示"去支付宝管理" else 未绑定 ISVPhone->>PAYSDK: 点击去绑定startBinding PAYSDK->>PAYSDK: initCloudEnv初始化
startBindingProcess串联核身 PAYSDK->>OPENAPI: 请求bindCode OPENAPI-->>PAYSDK: 返回bindCode PAYSDK-->>ISVPhone: onGetBindingSchemeSuccess返回schema ISVPhone->>ZFBApp: 打开绑定小程序 ZFBApp->>ZFBApp: 用户绑定操作 PAYSDK-->>ISVPhone: onStartRecording开麦通知 ISVPhone->>LauncherApp: 打开麦克风 ISVPhone->>PAYSDK: receiveDenoiseAudio送入音频 PAYSDK->>OPENAPI: wss上传音频 loop 轮询绑定状态 PAYSDK->>OPENAPI: 轮询绑定状态 OPENAPI-->>PAYSDK: 返回绑定状态 end PAYSDK-->>ISVPhone: 返回绑定结果 ISVPhone->>LauncherApp: 关闭麦克风 end ``` ##### 3.3 唤起智能体业务 + 通过厂商语音助手唤醒词,唤起智能体业务,如充话费、电影购票等; ```mermaid sequenceDiagram participant App as 厂商手机App participant SDK as 支付SDK participant BT as 蓝牙通道 participant Ear as 厂商耳机应用 participant Server as 支付宝服务端 App->>Ear: 1 设备建联 App->>SDK: 2 initSDK初始化 Ear->>App: 3 业务唤醒词 alt 支付宝智能体业务 App->>SDK: 4 startAlipayService App->>SDK: 5 receiveDenoiseAudio SDK->>SDK: 6 充话费/点咖啡
TTS交互 SDK->>Server: 7 创建订单,发起支付 Server-->>SDK: 8 支付结果 else 三方智能体业务 App->>App: 9 购物/购票
TTS交互 alt 未登录 App->>SDK: 10 授权登录组件 SDK-->>App: 11 登录结果回调 end App->>Server: 12 厂商skills创建订单 Server-->>App: 13 预下单号 App->>SDK: 14 startAlipayService 发起支付 App->>SDK: 15 receiveDenoiseAudio SDK->>SDK: 16 提示并等待用户意图输入 alt 用户确认支付 SDK->>Server: 17 发起支付请求 Server-->>SDK: 18 返回支付结果 else 用户取消支付 SDK->>SDK: 19 提示用户 end end SDK-->>App: 20 返回支付结果 ``` #### 4 接入流程 1、填写信息登记,申请支付宝服务端绑定、支付、停车缴费配置 **信息模板:** | **类别** | **厂商提供值** | **含义** | **备注** | | --- | --- | --- | --- | | isvName | | 厂商名称 | | | deviceModel | | 设备型号 | | | 语音唤醒词 | | 语音助手唤醒词 | | | 安卓apk包名 | | 应用包名 | | | 安卓apk签名 | | 应用签名 | apksigner verify -verbose --print-certs ,提供MD5值 | | IOS包名 | | 应用包名 | IOS应用的Bundle Identifier‌ | | 鸿蒙包名 | | 应用包名 | | 2、支付宝侧生成蓝盾加密图片**nearx_bs.jpg**, 放到厂商App应用中 + Android拿到蓝盾签名图片后,放到对应的工程中的app主模块下的assets根目录下即可 + iOS需要放在mainBundle里,图片名称需要为nearx_bs.jpg + Harmony放在主应用的src/main/resources/base/media/nearx_bs.jpg 3、集成支付宝sdk,进行对接开发和功能联调; ```java dependencies { //支付宝耳机sdk依赖 implementation files('libs/galipay_sakwrapper-1.3.501.aar') //三方库依赖 implementation "com.alibaba:fastjson:1.2.83@jar" implementation 'com.squareup.wire:wire-lite-runtime:1.5.3.4@jar' implementation 'com.squareup.okio:okio:1.7.0@jar' } ``` 4、绑定和开通入口 + 独立页面形式:页面上展示“说一下支付”、“停车缴费”入口,点击按钮进入子页面时根据getBindStatus返回的fetatureStatusList判断,若服务未开通,则按钮显示“去支付宝开通”,反之显示“去支付宝管理”; + 弹窗引导形式:识别到充话费、点咖啡、停车缴费等支付宝意图时,判断若未开通,则弹出浮窗提示,用户点击后跳转支付宝小程序进行开通; **建议:** 为避免每次发起服务都getBindStatus导致耗时,可以在设备建联或者进入页面时候查询一次getBindStatus,后续使用缓存状态; --- ### 具身智能AI支付接入文档 目录路径:智能终端设备 > 具身智能AI支付接入文档 来源:https://aipay.alipay.com/docs/device-agent-pay/intro-for-embodied-ai.md 说明具身智能如何接入AI支付 #### 1 文档说明 本文档适用于具身智能机器狗/机器人接入支付宝AI支付,包括输出产物、API接口说明和交互流程。 ##### 1.1 支付宝输出产物 | **平台** | **产物** | **功能与说明** | | --- | --- | --- | | Android | 支付宝安卓SDK | 支付宝智能体业务和支付、核身逻辑处理 | | IOS | 支付宝IOS SDK | 同安卓 | | Linux | 支付宝Linux SDK | 扫码算法封装,支持一二维码扫描;音频和意图处理; | ##### 1.2 功能列表 + 看一下支付:具身智能设备扫码,用户语音支付; + 一方智能体业务:充话费、点咖啡等; ##### 1.3 系统框图 若设备支持联网,则直接集成支付宝SDK即可使用,无需连接手机;若不支持联网,则需手机App集成支付宝SDK;此处以搭配手机使用为例: ![画板](https://intranetproxy.alipay.com/skylark/lark/0/2026/jpeg/198428/1790418910348-f9da4908-bd9e-404e-a7da-1c14734a59c0.jpeg) #### 2 接口说明 主要接口类:**AlipayGlassV2Sdk** ##### 2.1 initSDK初始化 ```java AlipayGlassV2Sdk.initSDK(context, extParams, new GlassSDKCallback() { //开启录音,发起绑定后回调,开启后需要在receiveDenoiseAudio传入降噪音频 @Override public void onStartRecording(String token) { //startRecordAudio(true); } @Override public void onStopRecording() { //startRecordAudio(false); } //播放支付过程提示文案 @Override public String onStartPlayback(String ttsData) { return null; } @Override public void onErrorEvent(String code, String message) { //错误回调 //○ Q1010/1011:sdk调用initCloudEnv失败,或者wss建联失败;收到此错误码仅需播音提示用户。 } @Override public void onEvent(String eventId, String eventData, Map extInfo) { //○ Q9991:SDK内状态机回调 //○ updateViewV2:页面驱动事件 } @Override public void onViIntentResult(String bizType, String dataJson, Map extInfo) { //核身和意图回调:厂商按需处理,如显示query对话记录 } }); ``` 初始化SDK,在手机App和耳机建立连接时调用,支持重复调用; 入参:(入参key详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | --- | | isvName | String | 厂商名称 | 是 | | | deviceModel | String | 设备机型 | 是 | | | deviceSN | String | 设备SN | 是 | | | productType | String | 产品类型 | 否 | 耳机或无摄像头眼镜时,传"earphones" | :::warning 支付过程中部分音频数据需要录制成音频,部分语音需要在线合成TTS,需要注意语音播报需要互斥,新的语音指令需要打断前序的播报,以避免在线TTS慢导致的语音排队问题 ::: ##### 2.2 getBindStatus 获取设备的绑定/服务开通状态;在手机端展示绑定状态 或者每次发起支付前调用;若未开通,提示用户去厂商App中进行服务开通; + needCloudStatus=true, 查询云端状态,一般填true; + needCloudStatus=false, 查询本地缓存状态; | **字段** | **类型** | **说明** | **示例** | | --- | --- | --- | --- | | isBinded | boolean | 账号绑定状态;(基本废弃,厂商根据featureStatusList判断服务是否开通) | true/false | | extInfo | Map | 扩展信息 | | | \|-featureStatusList | String | 服务开通状态,若已开通则同时返回对应的manageUrl。各服务编码说明:
("PAYMENT", "支付")(含充话费、点咖啡等)
("CAR_PARKING", "停车缴费"),
("CAR_PARKING_MESSAGE", "停车缴费消息"),
("CITY_SIGHTSEEING", "城市导览"),
| featureStatusList":["{\"featureId\":\"CAR_PARKING\",\"status\":\"STATUS_BIND\"}","{\"featureId\":\"PAYMENT\",\"status\":\"STATUS_BIND\"}","{\"featureId\":\"QUICK_MODE\",\"status\":\"STATUS_UNBIND\"}","
{\"featureId\":\"PAYMENT\",\"status\":\"STATUS_BIND\", \"manageUrl\":\"`http:xxx`\"}","{\"featureId\":\"PAY_DEMO\",\"status\":\"STATUS_BIND\"}"]}
注:若服务从未开通过,则列表不展示 | | \|-verifyMethodStatus | 核身方式录入状态 | VERIFY_VOICE | OPEN,表示已录入 | ##### 2.3 startBinding ```java AlipayGlassV2Sdk.startBinding(map, new BindingCallBack() { @Override public void onGetBindingSchemeSuccess(String bindingScheme, String token) { //收到支付宝绑定页面,跳转scheme } @Override public void onBindingSuccess() { //绑定完成 } @Override public void onBindingFailed(String errorCode) { //绑定失败 } }); ``` 开始绑定,用户点击手机上的【开始绑定】按钮时调用; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | returnUrl | String | 绑定完成后的回跳地址 | 否 | 优先级高于callback中的getReturnUrl | | sourceFrom | String | 发起开通的服务入口 | 是 | ("PAYMENT", "支付")(含充话费、点咖啡等支付业务),
("CAR_PARKING", "停车缴费"),
("CITY_SIGHTSEEING", "城市导览"), | ##### 2.4 receiveDenoiseAudio 接受降噪音频传入,格式要求:pcm,单声道,16000采样率,16位深(AV_SAMPLE_FMT_S16); + 绑定阶段:当进入支付宝小程序读文案界面时,会回调onStartRecording,此时打开麦克风,上传音频; + 支付阶段:识别智能体或支付意图时,调用startAlipayService接口,同时将用户这句唤醒语也调用receiveDenoiseAudio传入; ###### 唤起语上传 唤起语料厂商先做缓存,当识别到支付意愿调用scanpay接口时,同时把唤起语音进行上传;在扩展字段中填写 extParams.put("flowNode", "AROUSE"); :::warning 注意:唤起语音频上传要在startAlipayService/scanpay之后才有效 ::: ##### 2.5 unbind 解绑支付宝账号,仅清除设备本地缓存uid tid信息; 厂商手机App端解绑按钮建议跳转到支付宝小程序设备页面,进行解绑。 ##### 2.6 command 发送指令,比如用户点击耳机或眼镜的返回按键、摘下耳机/眼镜等时机调用; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | :--- | :--- | :--- | :--- | :--- | | commandCode | int | 指令编码 | 是 | 0:表示退出
1:表示按键命令 | | keyCode | int | 具体按键值 | 否 | | | source | String | 命令来源 | 否 | 摘下、双击退出键等 | 当摘掉耳机或眼镜时,退出支付流程 ```java params.put(GlasspayConfig.KEY_COMMAND_CODE, GlasspayConfig.CommandCode.EXIT); params.put("source", "wearOff"); AlipayGlassV2Sdk.command(params); ``` ##### 2.7 getCustomInfoV2 ```java void getCustomInfoV2(final Map params, CustomInfoCallback callback) ``` 获取客制化的自定义信息; 入参:1)params:表示要获取信息的key, value按需填写; 2)customInfoCallback:返回指定keys的查询信息; 出参:CustomInfoCallback的onCustomInfo中返回要查询的信息; keys取值如下: | **参数key** | **参数Val** | **含义** | **备注** | | :--- | :--- | :--- | :--- | | AlipayAppDownloadUrl | "" | 支付宝App下载地址 | 绑定时,若用户手机未安装支付宝,则提示其下载安装 | | AlipayManageGlassPage | 填写对应来源,如
sourceFrom=PAYMENT/CAR_PARKING.... | 支付宝App对应的服务管理的小程序页面 | 若未安装支付宝则跳转到下载链接页面;
sourceFrom的服务与getBIndStatus返回的featureStatusList中的服务相同; | | currentTradeUrl | "" | 当前交易订单的url地址 | 可跳转到支付宝订单详情页 | ```plain String customKeys = new HashMap(); customKeys.put("AlipayAppDownloadUrl", ""); customKeys.put("AlipayManageGlassPage", "sourceFrom=CAR_PARKING"); AlipayGlassV2Sdk.getCustomInfo(customKeys, new CustomInfoCallback() { @Override public void onCustomInfo(String data, Map extInfo) { //data暂未使用; extInfo中为各个key对应的信息 } }); ``` ##### 2.8 setWearingState 机器狗、机器人无佩戴状态检测,未用该接口; ##### 2.9 startAlipayService ```java String startAlipayService(final String appId, final String serviceCode, final Map params, final GAlipayCallback callback); void stopAlipayService(final String appId, final String serviceCode, final Map params, final String sessionId, final GAlipayCallback callback) ``` 启动/停止支付宝服务,serviceCode为具体的服务编码;厂商侧调用 startAlipayService 同时需要开启回传音频,通过 receiveDenoise 回传,在收到支付结束回调 onErrorEvent(ErrorCode.Q9990) 时关闭音频回传; 入参:(详见GlasspayConfig.java中定义) | **参数key** | **类型** | **含义** | **是否必填** | **备注** | | --- | :--- | :--- | :--- | --- | | PAY_INIT_ASR | String | 唤起语文本传入 | 是 | | | orderStr | String | 外部订单号,需码路由 | 否 | 预下单后调用支付 | | scene | String | 场景码 | 否(智能体场景需填写) | Coffee, //点咖啡
TopUp, //充话费
MovieTicket, //电影票 | | locationLat | String | 地理位置-维度 | 否(咖啡必填) | 31.564343 | | locationLnt | String | 地理位置-经度 | 否(咖啡必填) | 120.533231 | | coordType | String | 经纬度对应坐标系 | 否(咖啡必填) | 高德:GCJ-02
百度:BD-09 | | codeResultString | String | 外部码值 | 否 | 外部扫码得到支付宝码值

高德机器狗接入此项必传:
扫码sdk返回的加密二进制数据转成base64字符串后传入 | | codeResultNeedDecrypt
| String | 码值是否需要解密 | 否 | 若启用码值加密,接入时此项需传"true" | ##### **2.10 日志重定向** **接口:setLogger** **功能:用于将支付SDK的日志重定向到厂商日志中,便于后续客户端问题排查;Log等级跟随厂商设置,一般release包设置为Info,debug包设置为Verbose;** ```json public class AlipayLogger extends Logger { @Override public int verbose(String tag, String msg) { //重定向输出到厂商log文件 return 0; } //。。。其他日志接口实现 } com.alipay.glass.log.Log.setLogger(new AlipayLogger()); ``` #### 3 交互流程 ##### 3.1 用户动线 这里以机器狗接入扫码支付、点咖啡和城市导览业务举例: ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/198428/1782183022842-641794d7-c979-40f3-8105-449b0bf94734.png) ##### 3.2 绑定流程 + 绑定支付宝账号、录入声纹、开通支付; + 这里以手机App+无网设备接入为例;当具身智能设备支持独立联网时,将厂商手机App换成厂商具身智能App; ```mermaid sequenceDiagram autonumber participant ISVPhone as 厂商手机App participant PAYSDK as 支付SDK participant ZFBApp as 手机支付宝App participant OPENAPI as 支付宝服务端 activate ISVPhone ISVPhone->>PAYSDK: initSDK初始化 ISVPhone->>PAYSDK: 查询绑定状态getBindStatus PAYSDK->>OPENAPI: queryBindStatus OPENAPI-->>PAYSDK: 绑定状态应答 PAYSDK-->>ISVPhone: 返回绑定状态 alt 已绑定 ISVPhone->>ISVPhone: 显示"去支付宝管理" else 未绑定 ISVPhone->>PAYSDK: 点击去绑定startBinding PAYSDK->>PAYSDK: initCloudEnv初始化
startBindingProcess串联核身 PAYSDK->>OPENAPI: 请求bindCode OPENAPI-->>PAYSDK: 返回bindCode PAYSDK-->>ISVPhone: onGetBindingSchemeSuccess返回schema ISVPhone->>ZFBApp: 打开绑定小程序 ZFBApp->>ZFBApp: 用户绑定操作 PAYSDK-->>ISVPhone: onStartRecording开麦通知 ISVPhone->>ISVPhone: 打开麦克风 ISVPhone->>PAYSDK: receiveDenoiseAudio送入音频 PAYSDK->>OPENAPI: wss上传音频 loop 轮询绑定状态 PAYSDK->>OPENAPI: 轮询绑定状态 OPENAPI-->>PAYSDK: 返回绑定状态 end PAYSDK-->>ISVPhone: 返回绑定结果 ISVPhone->>ISVPhone: 关闭麦克风 end ``` **注:实际用户使用时,可能有两种形式**: + 用户佩戴耳机进行语音交互,全程不用掏手机; + 用户拿着手机,对语音助手摁住录音键说话并发送; ##### 3.3 唤起支付和智能体业务 + 通过厂商语音助手唤醒词,唤起智能体业务,如充话费、点咖啡、电影购票等; ```mermaid sequenceDiagram autonumber participant ISVPhone as 厂商手机App participant PAYSDK as 支付宝SDK participant LauncherApp as 机器狗 participant OPENAPI as 支付宝服务端 activate ISVPhone ISVPhone->>LauncherApp: 设备建联 ISVPhone->>PAYSDK: initSDK初始化 ISVPhone->>ISVPhone: 业务唤醒词 alt 扫码支付 ISVPhone->>ISVPhone: 帮我扫码支付 ISVPhone->>LauncherApp: 发送扫码指令 LauncherApp->>LauncherApp: 打开相机扫码 LauncherApp->>LauncherApp: 遮挡、远近等提示 LauncherApp-->>ISVPhone: 返回码值 ISVPhone->>PAYSDK: startAlipayService(codeStr) PAYSDK->>OPENAPI: parseCode解码 OPENAPI-->>PAYSDK: 返回商户名称、logo、金额 PAYSDK->>PAYSDK: tts: 要付多少钱/即将支付x元 ISVPhone->>PAYSDK: 用户"确认支付" PAYSDK->>OPENAPI: 发起支付 OPENAPI-->>PAYSDK: 返回支付结果 PAYSDK->>PAYSDK: tts: 支付成功/失败(原因) PAYSDK-->>ISVPhone: 返回支付结果 else 支付宝智能体业务 ISVPhone->>ISVPhone: 帮我点杯咖啡 ISVPhone->>PAYSDK: startAlipayService(scene=Coffee) ISVPhone->>PAYSDK: receiveDenoiseAudio PAYSDK->>PAYSDK: 手机号授权(仅首次) PAYSDK->>PAYSDK: 点咖啡
TTS交互 PAYSDK->>OPENAPI: 创建订单,发起支付 OPENAPI-->>PAYSDK: 支付结果(门店地址+取单号) PAYSDK-->>ISVPhone: 门店地址+取单号 ISVPhone->>LauncherApp: 发送取咖啡指令
门店地址+取单号 LauncherApp->>LauncherApp: 前往门店取咖啡 else GPass业务 ISVPhone->>ISVPhone: 打开导览
TTS交互 ISVPhone->>PAYSDK: recognize(scene=city_guide) PAYSDK-->>ISVPhone: 导览TTS交互 ISVPhone->>LauncherApp: 导航位置和内容 LauncherApp->>LauncherApp: 领航和讲解 end ``` ###### 3.3.1 机器狗领取咖啡 + 发起点咖啡服务调用 ```plain params.put("PAY_INIT_ASR", "帮我点一杯咖啡"); params.put(GlasspayConfig.KEY_SCENE, "Coffee"); params.put(GlasspayConfig.KEY_LOCATION_LONGITUDE, "120.104739"); params.put(GlasspayConfig.KEY_LOCATION_LATITUDE, "30.261124000000017"); AlipayGlassV2Sdk.startAlipayService("appId", selectedScene, params, new GAlipayCallback() { @Override public void onResponse(GAlipayResponse response) { Log.i(TAG, "onResponseresponse=" + response); } @Override public void onEvent(String eventId, String data, Map extra) { Log.i(TAG, "onEvent, eventId=" + eventId + ",data=" + data + ",extra=" + extra); } }); ``` + 返回下单结果(地址、门店、取单号) - onResponse返回结果信息: ```json { "code": 1000, "subCode": "Q100000", "subMsg": "OK_SUCCESS", "mResult": "{eventData={\"notificationUrl\":\"https://ur.alipay.com/_7qlgugFbslIgI7pFz7Imcq\",\"notificationTitle\":\"瑞幸下单成功,取餐号:468\",\"code\":\"468\",\"address\":\"北京市西城区西单北大街131号\",\"notificationMessage\":\"下单成功\",\"shopName\":\"瑞幸咖啡(丰潭路站店)\"}, resultCode=9000, memo=订单支付完成, eventType=onPayResult}", "extInfo": {} } ``` - initSDK#onEvent接口返回咖啡制作状态信息: ![](https://intranetproxy.alipay.com/skylark/lark/0/2026/png/198428/1790420368256-13635850-cf25-4bce-91a4-c6609778c43d.png) ```json //dataJson数据示例: { "topic": "PAY_LUCKIN_COFFEE", "bizId": "server-event-id", "payload":{ "intentType": "coffee", "content": { "deliveryScope": "PROCESS", "type": "OrderStatus", "data": { "device_sn": "1901092548008087", "order_id": "7674558732730630153", "dept_name": "春申景城店", "dept_address": "闵行区兴梅路1181号底商", "order_ready_time": "17:31", "order_status_name": 40, "order_status_desc": "制作完成,等待取餐", "update_timestamp": "2026-08-16 17:29:08", "note_msg": 154 } } } } ``` #### 4 接入流程 1、填写信息登记,申请支付宝服务端绑定、支付、停车缴费配置 **信息模板:** | **类别** | **厂商提供值** | **含义** | **备注** | | --- | --- | --- | --- | | isvName | | 厂商名称 | | | deviceModel | | 设备型号 | | | 语音唤醒词 | | 语音助手唤醒词 | | | 安卓apk包名 | | 应用包名 | | | 安卓apk签名 | | 应用签名 | apksigner verify -verbose --print-certs ,提供MD5值 | | IOS包名 | | 应用包名 | IOS应用的Bundle Identifier‌ | | 鸿蒙包名 | | 应用包名 | | 2、支付宝侧生成蓝盾加密图片**nearx_bs.jpg**, 放到厂商App应用中 + Android拿到蓝盾签名图片后,放到对应的工程中的app主模块下的assets根目录下即可 + iOS需要放在mainBundle里,图片名称需要为nearx_bs.jpg + Harmony放在主应用的src/main/resources/base/media/nearx_bs.jpg 3、集成支付宝sdk,进行对接开发和功能联调; ```java dependencies { //支付宝耳机sdk依赖 implementation files('libs/galipay_sakwrapper-1.3.501.aar') //三方库依赖 implementation "com.alibaba:fastjson:1.2.83@jar" implementation 'com.squareup.wire:wire-lite-runtime:1.5.3.4@jar' implementation 'com.squareup.okio:okio:1.7.0@jar' } ``` 4、绑定和开通入口 + 独立页面形式:页面上展示“说一下支付”、“停车缴费”入口,点击按钮进入子页面时根据getBindStatus返回的fetatureStatusList判断,若服务未开通,则按钮显示“去支付宝开通”,反之显示“去支付宝管理”; + 弹窗引导形式:识别到充话费、点咖啡、停车缴费等支付宝意图时,判断若未开通,则弹出浮窗提示,用户点击后跳转支付宝小程序进行开通; **建议:** 为避免每次发起服务都getBindStatus导致耗时,可以在设备建联或者进入页面时候查询一次getBindStatus,后续使用缓存状态; --- ## 接入方式 ### 让支付集成更简单 目录路径:接入方式 > 产品与 Skill 介绍 > 让支付集成更简单 来源:https://aipay.alipay.com/developers/skill.md 支持 AI 网页应用收款、AI 移动应用收款、AI 按量付费三种产品,签约入驻与代码集成一站式完成。 支持 AI 网页应用收款、AI 移动应用收款、AI 按量付费三种产品,签约入驻 + 代码集成一站式完成 一键安装 `npx -y @alipay/alipay-aipay@latest install` #### 产品列表 技能覆盖三大 AI 应用变现场景 ##### AI 网页应用收款 在 PC/H5 网页完成收款,适合电商、社区论坛等网站场景 试试对 Agent 说 `通过 npx -y @alipay/alipay-aipay@latest install 安装支付宝 AI 付 Skill,加载 alipay-aipay 技能为我的项目集成网站支付,完成沙箱测试,并完成签约入驻` ##### AI 移动应用收款 在 APP 内调起支付宝完成收款,适合移动应用场景 试试对 Agent 说 `通过 npx -y @alipay/alipay-aipay@latest install 安装支付宝 AI 付 Skill,加载 alipay-aipay 技能为我的 APP 集成支付宝支付,完成沙箱测试,并完成签约入驻` ##### AI 按量付费 在智能体 Agent 内完成收款,适合 API 等数字资源 试试对 Agent 说 `通过 npx -y @alipay/alipay-aipay@latest install 安装支付宝 AI 付 Skill,加载 alipay-aipay 技能为我的 api 接口集成按量付费,完成沙箱测试,并完成签约入驻` #### 常见问题 用了 Skill 之后,还能自己修改代码吗? 当然可以。代码直接生成在你的项目里,完全开放,后续想加功能、改样式、调逻辑,随便改。 Agent 通过上述 npx 指令下载安装 alipay-aipay 技能反复失败该怎么办? 可前往 https://github.com/alipay/ai/tree/main/skills 获取 alipay-aipay 技能。 Skill 生成的代码可以直接上线吗? 能跑通,但上线前建议做完整的功能和安全测试(尤其是异常流程),再把沙箱密钥换成生产密钥。注意:生产环境的私钥不要明文写在代码里。