小豆支付开放平台 · 商家接入 Skill
本 Skill 与同仓
docs/是同一份内容源的两个形态：docs/给人读，本目录给 AI 编码助手直接消费。两者同属一个skillVersion——但两个下载包各有各的contentHash（文档包 ≠ Skill 包），且 Skill 包内不含MANIFEST.json。核对版本请以门户下载页/发布记录登记的那一对（包 ↔ hash）为准，不要拿一个包的 hash 去对另一个包。 术语：本 Skill 是给商家开发者用的接入资料；「支付机构官方 Skill」是另一件东西，不要混用。
何时用
商家要「把开放平台支付接进自己的服务端/页面」时用。典型任务：
- 写一个能通过验签的下单请求（六头 + 规范串）。
- 决定收款页怎么呈现（自渲染官方收款码 / 渲染收银页二维码 / 302 跳转）。
- 接平台事件通知并做去重与幂等落账。
- 排一个
401/403/409/422/429/503。 - 上线前逐条自检；或轮换签名密钥。
- 系统里已经装了易支付 / 彩虹支付类插件（Sub2API、New API 等），只填网关地址 / 商家 ID / 商户密钥，不想改代码。
已有易支付 / 彩虹支付插件（Sub2API、New API 等）
如果商家系统里已经装了易支付/彩虹支付类插件，不要按本 Skill 的 RSA2 七接口重写，走协议兼容面即可：
- 建单：
submit.php（GET/POST 表单）或mapi.php（GET/POST，JSON）。 - 查单：
api.php，act=order查单笔、act=query查商户状态；GET/POST 表单均可，参数放 query、body 或同值镜像到两处（同键不同值会被拒绝）。 - 通知：平台用 GET 请求商家
notify_url；商家返回纯文本success（大小写不敏感，SUCCESS也接受）。 - 签名：MD5（剔除
sign/sign_type/空值 → ASCII 排序 →k=v&…→ 直接接密钥 → 小写 hex）。 - 明确不做：
act=orders批量、act=change、qrcode.php、JSON body 建单。 - 实测客户端：独角数卡（GET submit）、V2Board（GET submit）、Sub2API（POST mapi / POST api，参数镜像 query+body）、New API（go-epay v0.0.5，POST submit 表单、
device=pc，notify_url/return_url必须是 https 完整地址）。 - 人读版：
docs/13-epay-compat-integration.md（不在 Skill 包内，按本文「路径基准」另取）。
铁律（先记这七条，能避免绝大多数事故）
- 签名只认规范串：请求 11 行、响应 8 行、事件 7 行，三套不同，不要复用同一段拼串代码。请求与响应两侧的
Content-Type都取「小写去;参数」后的值——没带这个头时该行是空行（GET且无请求体就是这样）；所有POST必须带Content-Type: application/json（含无请求体的重拉起/关单）。 - 重试复用同一个
requestId与同一份请求体（body 逐字节相同，含「不传 body」本身），但 nonce 必须换新；409的正确动作是查单，不是换单号重下单。业务摘要成员见references/api-workflow.md§2——returnUrl在摘要内，改了再重试就是409。 - 收银页打开 / 回跳 / 用户点完成都不是支付终态；终态只认查单与经验签的事件。
UNKNOWN不判死：不重新下单、不重发退款、不提示买家失败，等事件或查单收敛。- 收款材料只从响应取：
payUrl/qrCode用原值，不拼接、不转发第三方、不进日志；查询接口两者恒为空，需要新码走重拉起。 - 事件必须用原始字节验签 + 按
eventId去重，成功才回 2xx 且 body 字节正好是success。 - 私钥永不进浏览器、不进仓库、不进日志；费率不要写死进代码：入账以每单
feeProjection为准（对外统一档与手续费见仓库README.md），单独约定过的费率与限额以门户「费率说明」页/平台答复为准。
能力事实（2026-10-17 口径）：微信 JSAPI 已开放——仅限买家在微信内打开收银页时调起；微信外手机浏览器与商家 App 内没有「直接拉起」形态。比例分账已支持：SINGLE / ROUND_ROBIN / RATIO 三种方式，RATIO 为 2–4 个参与账号、配置面每项 0 < shareBps < 10000、合计 10000bps，RENORMALIZE 后单笔生效腿可只剩 1 条；查询接口只读返回 routing.ratios 配置快照，写面在商家后台。
工作流
text① 读 references/signature-spec.md → 用 examples/ 里对应语言实现签名，先跑通 golden 向量 ② 读 references/api-workflow.md → 下单 → （需要新材料时）重拉起 → 查单；幂等三层怎么用 ③ 读 references/terminal-matrix.md → 决定收款页形态（PC 扫码 / 手机分端 / 微信推荐路径 / 宿主内跳浏览器） ④ 读 references/webhook-verification.md → 接事件、验签、去重、幂等落账、返回 success ⑤ 读 references/error-codes.md → 按 code 分派错误，不要按 message 判错 ⑥ 读 references/go-live-checklist.md → 上线前逐条自检（平台不提供沙箱） ⑦ 读 references/key-management.md → 生成/轮换/停用/应急吊销；注意轮换是原子的
资产
| 资产 | 路径 | 在 Skill 包里可取到？ | 说明 |
|---|---|---|---|
| 四语言签名示例 | examples/{node,java,php,python}/（索引见 examples/README.md） | ✅ 在包内 | 与 docs/ 同源的参考实现：请求签名四语言 + 事件验签 / 响应验签（Node），含 golden 向量 |
| 人读文档（14 篇） | docs/ | ❌ 不在包内 | 含 API 参考与终端能力矩阵；用门户「开发者文档」页的「下载文档包」或公开仓的 docs/ |
| 本地收银 demo | demo/h5-cashier/ | ❌ 不在包内 | 零依赖，loopback + mock，全链可跑（含负向用例）；用公开仓全量目录 |
路径基准（别踩这个坑）：本 Skill 有两种落地形态，可用路径不一样——
- Skill 下载包（门户「开发者文档」页的「下载接入包（含示例与 Skill）」按钮打出的
.tar.gz）：按登记文件集只含skill/**与examples/**，docs/、demo/与仓库根README.md不在包内。所以本文档、references/与examples/README.md里所有指向docs/…、demo/…、README.md的引用在这个形态下都取不到——请如实告诉用户「人读文档要另外下载」，不要凭路径猜文件位置、更不要因此编造内容。- 公开仓（完整目录）：
skill/与examples/、docs/、demo/同级存在，三者都能取到。- 只把
skill/目录单独拷进编码助手的技能目录时，连examples/也会取不到（skill/examples/里的相对引用按包根解析）；这时把examples/一并带上。不要把示例代码复制进
skill/内形成第二份源——那一定会漂移。
边界（不要做的事）
- 不要照抄 demo 的样式去仿造平台收银页；真实收银页由平台承载且品牌中立。
- 不要为「微信在手机浏览器直接拉起支付」「微信 PC 原生扫码直出付款码」写代码——平台没有这些形态（微信支付只能在微信内调起；PC 扫码是中转链）。
- 不要在自有 App 的 WebView 内嵌收银页；必须跳系统浏览器。
- 不要把 mock 全绿当成「生产可用」：mock 只证明签名与解析没错，生产首单必须真实验证。
- 不要把易支付兼容面当成 RSA2 七接口：两者的端点、签名（MD5 vs RSA2）与回调形态不同；已有插件走兼容面，不要重写。
- 平台暂不提供沙箱/测试应用/回调模拟器；替代路径=本地 demo + 上线检查清单 + 首单人工陪跑（不承诺 SLA）。
