> 作者 @zzzzzzzp（立意 · 判据 · 取舍） · 协作 多多 · AI 助手（检索 · 编码 · 核查）
> 版权 著作权归 @zzzzzzzp 所有（All Rights Reserved） · 版本 v1.3.0
万象-支付宝AI付接入
把支付宝「AI 按量付费」从零接到上线：账单、密钥、服务注册、线上验证一次走通。
- 做什么：接入 402 账单、验付、履约回执三件事，跑通站点线上验证。
- 何时用：要让自己的服务支持按次收费，或卡在平台「线上验证」过不去时。
- 不做什么：不代办支付宝商户入驻；不教任何绕过验付的做法。
数据边界与外部连接（必读）
- 文档处理全在本机：所有读写只发生在你显式指定的文件上。
- 不采集、不上传用户的任何内容；不扫描目录、不常驻后台、不联网轮询。
- 唯一的外部连接：技能自带的按量付费组件（
a2m/）会与支付宝发生支付校验与履约回执，
该链路只传订单号与金额，不含你的文件内容；本地服务仅监听127.0.0.1。 - 凭据：作服务端使用时，商户私钥从你的本机环境变量读取，不落盘、不进包。
- 回流组件默认未启用：包内不含任何收件地址，也不自动注册任何钩子；是否启用完全由你决定。
一、什么时候用
- 你要给自己的 API / 数字内容 / 算力资源接「按量付费」（用户或 AI 智能体按次付费）。
- 你已经在支付宝开放平台做完或正在做 AI 付费产品开通，卡在「线上验证」这一步过不去。
- 你要排查 402 链路：账单生成、验付、履约回执、Agent 支付。
- 关键词：402、按量付费、AI 付、Agent 支付、商户开通、验证交易。
二、五步闭环（照做即可）
| 步 | 做什么 | 通过判据 |
|---|---|---|
| 1 | 技术集成：服务端实现 402 账单 + 验付 + 履约回执 | 请求返回 402 + Payment-Needed 头；能解码出 protocol / method 两组字段；商家签名 RSA2 |
| 2 | 产品开通：平台上提交产品开通申请，选经营类目 | 审核通过。类目要与真实经营一致，不按产品名猜 |
| 3 | 服务注册：填服务名称 / 地址 / 单价 / 描述 / 请求示例 | 拿到 服务ID。⚠️ 单价必须与代码里实际扣费完全一致，否则用户无法支付 |
| 4 | 密钥配置：生成密钥对 → 上传应用公钥 → 取回支付宝公钥 | 生产 appId + 应用私钥 + 支付宝公钥三者齐备，且私钥与应用公钥配对 |
| 5 | 线上验证：把沙箱配置换成生产配置 → 发起一笔真实交易 → 填交易号 | 站点显示接入成功。⚠️ 交易必须满足 §三.① |
完整命令与字段清单见 references/01-五步闭环.md。
三、四道硬约束（这四条决定了能不能过，不是优化项）
① 站点「验证交易」唯一校验点＝收款方 ＝ 当前登录用户
- 站点只比对这一件事。付款方是谁、渠道是什么，都不在它的校验里。
- ⇒ 付款方必须与收款方是不同的支付宝账号。同一账号支付会被支付宝拒：
TRADE_PROGRESS_FAILED / 买家和卖家不能相同。 - ⇒ 正确姿势：你的服务（收款方＝你）＋ 另一个账号来付款。
- ⇒ 推论：「随便付一笔」永远过不了；付给别人的商户也不行（收款方不是你）。
② AI 按量付费只能走 402 通道
- 只开通了 AI 付的应用，没有签任何传统收单产品：
alipay.trade.precreate（订单码）、alipay.trade.page.pay（电脑网站）、alipay.trade.wap.pay（手机网站）
全部返回40006 isv.insufficient-isv-permissions。 - 个人收款码收款不构成商户收单交易，同样不算。
- ⇒ 想自建一张能扫的收款码 —— 此路不通，不要在 API 上反复试。
③ 付款方只接受 HTTPS 资源地址
402-buyer-pay对http://直接报paid resource URL must use HTTPS。- ⇒ 本机起服务时，必须有一个 https 入口（内网穿透 / 反向代理 / 正式域名均可）。
④ 机器上的 Agent 钱包决定「付款方是谁」
- 钱包绑在哪个账号，
402-buyer-pay就以哪个账号付款。 - ⇒ 若钱包绑在收款方自己的账号上，必然撞上 §三.① 的「买家＝卖家」。
- ⇒ 换绑方法：
close-wallet（出管理码，当前账号扫码关闭） →apply-wallet（出开通码，目标账号扫码开通）。
四、已知坑（踩过，别再踩）
- 🔴 交易号有两套，别混：收银接口返回的那串（脚本用）与支付宝 APP 里的买家侧交易号（
…22001…形态，站点认的是这个）不是同一串。 - 🔴 公私钥必须指纹比对：「应用公钥」（你的，给它验你的请求）与「支付宝公钥」（它的，给你验它的响应）开头完全相同、肉眼无法区分，填反了验签必失败。
- 🔴 私钥落盘前过三重校验：长度量级（2048 位裸 Base64 ≈1620 字符）→ DER 实解析 → 私钥↔应用公钥配对。
- 🔴 交互式索要文件：付款命令必须显式传账单文件（
-f <文件>），只给资源地址它会卡在交互提示上。 - 🔴
localhost是不确定量：隧道 / 代理 / 转发一律写127.0.0.1。Windows 原生 ssh 会把localhost解析成::1，而 Node 服务常只监听 IPv4 ⇒ 边缘转发到空地址 ⇒ 报ERR_EMPTY_RESPONSE。 - 🔴 两种"连不上"要分清：
ERR_EMPTY_RESPONSE＝边缘已转发但后端无数据（后端地址/端口/协议栈错）；000＝边缘不认识该域名（隧道未注册）。 - 🔴 面向用户双击的脚本：不得假设
node在 PATH（自己解析可执行文件位置）；不得把长 JS 内联进命令行（引号会被命令行解析器破坏，应写成.js文件调用）。 - 🔴
isv.insufficient-isv-permissions＝ 产品未签约，不是参数错、不是密钥错。动手前先查该应用签了哪些产品。
五、已证伪路径（不要重试）
| 尝试 | 为什么不行 |
|---|---|
| Agent 钱包付自己的服务（同账号） | 买家＝卖家，被拒 |
| 用官方收单 API 自建收款码 | 未签该产品，40006 |
| 个人收款码收款 | 不算商户收单交易 |
| Agent 付「别人的服务」 | 收款方不是本人，归属校验不过 |
| 让别人代出「通用收款码」 | 收银接口必须带买家身份，无此通道 |
六、安全红线
- 生产应用私钥绝不外发：不入对话、不入日志、不入公开仓库；只留在你自己的服务器上。
- 需要交付私钥时走「写独立文件 + 本人复制」，不由对方读取或打印。
- 交付前对密钥做指纹比对（只比指纹，不比原文）。
- 沙箱私钥一旦外泄，到平台重置一次即可作废。
常见误用与常见问题（FAQ）
常见误用（反模式）
| 误用 | 后果 | 正解 |
|---|---|---|
| 想用「个人收款码」自建一张能扫的收款码 | 个人收款码收款不构成商户收单交易，不算 | 此路不通，不要在 API 上反复试 |
| 把收银接口返回的交易号当站点认的那串 | 交易号有两套，混用必然失败 | 站点认的是支付宝 APP 里的买家侧交易号（…22001… 形态），不是脚本用的那串 |
| 把「应用公钥」与「支付宝公钥」填反 | 两者开头完全相同、肉眼无法区分，验签必失败 | 必须做指纹比对：「应用公钥」是你的（给它验你的请求）；「支付宝公钥」是它的（给你验它的响应） |
| 私钥落盘前不做校验 | 配置错极难定位 | 过三重校验：长度量级（2048 位裸 Base64 ≈1620 字符）→ DER 实解析 → 私钥↔应用公钥配对 |
把 ERR_EMPTY_RESPONSE 与 000 当同一种「连不上」 |
排查方向错 | ERR_EMPTY_RESPONSE ＝ 边缘已转发但后端无数据（后端地址/端口/协议栈错）；000 ＝ 边缘不认识该域名（隧道未注册） |
见 isv.insufficient-isv-permissions 就回头查参数或密钥 |
方向错 | 该错误 ＝ 产品未签约。动手前先查该应用签了哪些产品 |
面向用户双击的脚本假设 node 在 PATH |
在用户机器上跑不起来 | 自己解析可执行文件位置；不得把长 JS 内联进命令行（引号会被命令行解析器破坏），应写成 .js 文件调用 |
| 服务还在 HTTP 上就去接 | 付款方只接受 HTTPS 资源地址 | 作者的服务必须常驻公网 HTTPS；服务未上线时本技能不可用 |
| 想加一个「跳过验付」的分支 | 违规，且必然过不了线上验证 | 不降级 —— 不存在跳过验付的分支；凭证校验失败即拒绝交付 |
| 拿自己的账号给自己付款做验证 | 不符合验证要求 | 付款方必须是另一个账号（见「线上验证」） |
常见问题
- Q：这部技能讲概念吗？ A：不讲泛泛概念 —— 只留下一条走通过的路径和五条已证伪、不要再走的死路（见「五、已证伪路径」）。
- Q：硬前置是什么？ A：作者的服务必须常驻在公网 HTTPS 上；服务未上线时本技能不可用，且不得以任何方式绕过支付。
- Q：完整链路几步？ A：四步 —— ① 取服务地址的 402 账单 → ② 付款（Agent 钱包或扫码）→ ③ 携
Payment-Proof取资源 → ④ 发送履约回执。 - Q：密钥怎么放？ A：只走运行环境变量或本地配置文件，永不入包；不构造 SDK、不使用占位密钥、不提供任何跳过验付的路径。
- Q：为什么必须走 402 通道？ A：AI 按量付费只能走 402 通道；站点「验证交易」的唯一校验点见「四道硬约束」第①条。
- Q：付款方由什么决定？ A：由机器上的 Agent 钱包决定（见「四道硬约束」第④条）。
七、来源与净室边界
- 本技能为 2026-10-06 本人全流程实测的沉淀（一次真实的「接入成功」闭环），非对任何第三方实现的复制。
- 涉及平台接口的部分，只记录公开文档所述的能力与实测得到的行为，不收录任何竞品实现代码。
- 平台规则会变；以上线当日平台页面为准，本技能记录的是判据与踩坑，不是规则原文。
附 · 付费与授权
§〇 · 本技能定位为付费技能（Pay Skill）
| 项 | 内容 |
|---|---|
| 定位 | 付费版（Pay Skill 通道） |
| 计费形态 | 按次 |
| 已接入的服务 | serviceId API_13DCD6D650224B51 ｜ 服务地址 https://wb-workbase.app.workbuddy.host/demo/a2m/resource（无凭证时返回 402 ＋ Payment-Needed 账单）｜ 单价 0.25 元/次 |
| 🔴 单价须与注册价一致 | 平台明确警告：实际支付价与注册标价不一致会导致用户无法支付 ⇒ 向导里单价填 0.25 |
| 这条服务是复用的 | 属同一作者、同一 appId ⇒ 与「万象-SkillHub自动上架」等共用同一条已注册服务，不另注册 |
| 标识 | 付费技能加一道金色光圈（GOLD = #C8A02C） |
> 🔴 付费技能一律走完整付费路径。本技能本身讲的是「怎么把 402 接上」，
> 因此它自带 a2m/ 参考实现（见 §〇·2），既是教程也是可运行的样板。
§〇·2 · 随包提供的 402 付费链路实现
平台在提交时检测包内是否存在 402 支付链路的实现，缺失项逐条列出：
402账单下发 / 携带凭证重试 / 验付调用 / 履约确认 / 订单持久化与幂等。
该检查不阻断提交，但审核阶段会重做一次，不合规即拒。
⇒ 本包自带该实现（目录 a2m/，零密钥、可直接 npm install && npm start）：
| 平台检测项 | 位置 |
|---|---|
| 402 账单下发 | a2m/a2m.js buildPaymentRequired()；路由在 a2m/server.js |
| 携带凭证重试 | a2m/a2m.js decodePaymentProof() |
| 验付调用 | a2m/a2m.js verifyPayment() |
| 履约确认 | a2m/a2m.js confirmFulfillment() |
| 订单持久化与幂等 | a2m/orderRepository.js prepareFulfillment() |
配置边界：配置缺失即明确失败（503）；不使用占位密钥、不提供跳过验付的路径；密钥永不入包。
把「按调用收费」接到你自己的 API 上，并真正通过平台的线上验证。
这部技能不讲泛泛概念，只留下一条走通过的路径和五条已经证伪、不要再走的死路。
〇、本技能为付费技能（Pay Skill）
- 计费：按次。交付前先完成一笔 402 支付，金额＝作者在 AI 付平台注册的服务单价。
- 收款方：作者自己的按量付费服务（
service_id由作者在下方给出）。 - 付款方：调用方的 Agent 钱包 —— 必须与收款方不是同一个支付宝账号。
- 硬前置：作者的服务必须常驻在公网 HTTPS 上（付款方只接受 HTTPS）。
服务未上线时本技能不可用，且不得以任何方式绕过支付。 - 四步：① 取服务地址的 402 账单 → ② 付款（Agent 钱包或扫码）→ ③ 携
Payment-Proof取资源 → ④ 发送履约回执。 - 不降级：不存在"跳过验付"的分支；支付凭证校验失败即拒绝交付。
> 作者侧的服务注册信息（serviceId / 服务地址 / 单价）由作者在发布时填写，见 references/02-付费改造.md。
