# Yeepay Payment Integration

> 易宝支付（Yeepay）开放平台接入最佳实践。涵盖入网（服务商/平台商拓展子商户进件、商户信息变更、 沉默商户解冻、微信/支付宝实名认证）、收单（小程序支付、APP支付、浏览器H5支付、微信内H5+公众号支付、 被扫付款码、主扫独立码/聚合码）、退款（原路/极速/补充卡信息/合单退款）、分账（订单分账、余额分账、入账方管理）、出款（结算、提现）、 对账、金融（放款对公快捷/联合贷、信用卡跨行还款、协议支付签约绑卡与代扣、批量支付）、 航旅易达（机票出票/退票/改升，航司NDC2C/NDC2B/NDC2T/B2B、OTA分销、CDP渠道）全场景的 产品选型、接入指导与联调排障。 当用户提到"接入易宝"、"对接易宝支付"、"yeepay"、"YOP"、"聚合支付"、"入网"、"进件"、"入件"、 "子商户入网"、"商户报备"、"实名认证"、"支付下单"、"小程序支付"、 "APP支付"、"H5支付"、"公众号支付"、"付款码"、"扫码收款"、"聚合码"、"退款"、"分账"、"入账方"、 "结算"、"提现"、"对账单"、"放款"、"对公快捷"、"联合贷"、"信用卡还款"、"跨行还款"、"协议支付"、"代扣"、 "签约绑卡"、"一键绑卡"、"存量签约"、"绑卡id"、"批量支付"、"周期扣款"、"自动续费"、"保费代扣"、 "航旅易达"、"TSP"、"机票接口"、"NDC2C"、"NDC2B"、"NDC2T"、"航司B2B"、 "出票"、"退票"、"改签"、"验舱验价"、"电子行程单"、"机票开票"、"政策池"，或提及南航、厦航、国航、东航、深航、山航、 昆航、港航等航司机票对接时，或咨询验签失败、回调收不到、查单、错误码排查、沙箱联调、上线检查等 问题时使用此 Skill。

- Skill: `yeepay-open-platform/yeepay-payment-integration` (Agent Skill, multi-file: 135 files)
- Install (CLI): `npx skillmds@latest add yeepay-open-platform/yeepay-payment-integration`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yeepay-open-platform/yeepay-payment-integration/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: yeepay-open-platform (https://skillmd.com/u/yeepay-open-platform)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yeepay-open-platform/yeepay-payment-integration

---


# 易宝支付接入技能（统一入口）

本技能是**唯一入口**：以商户可理解的语言协助选型、接入与排障；技术实现依赖 `references/` 中的产品决策、场景流程与在线文档。

**面客原则**：先听懂商户在说什么、再确认要做什么、最后才给参数和代码。**严禁**在场景未明确时直接输出接口字段清单或示例代码。

> 启用本 skill 后、开始实质工作前，执行一次（每次会话仅一次）：`yop-cli track --skill yeepay-payment-integration --skill-version 1.3.0 --event skill_start`。**立即返回、失败静默**，不得阻塞面客流程。

---

## 面客交互纪律（最高优先级，所有对话遵守）

与商户沟通分四步，**前一步未完成不得进入下一步**。

> **快速通道（需求已明确时允许合并步骤）**：当用户已**清晰给出场景**（如「我用的微信小程序支付，要 Java 下单代码」），可将①②③合并为**一次简短确认**（复述场景 + 列出还缺的关键信息 + 告知将输出什么），用户确认后直接进入实现，**无需逐条澄清**。**快速通道 ≠ 跳过易错点**：合并面客步骤后，仍须按「技术执行顺序」步骤 2 完整阅读已锁定场景 md 的 `## 易错点`（及该节引用的关联文档），再 curl doc_md 或生成代码。但以下**安全底线在任何通道下都不可省略**：①必须确认**环境（沙箱/生产）**；②**生产环境实际调用**仍需④的显式二次确认；③输出接口字段/代码前仍须按「文档加载协议」**curl doc_md**，不得凭记忆编造字段；④缺失实现必需信息（场景、环境、SDK 与否）时仍要补齐；⑤**生成参数/代码前必须完整阅读场景 md 的** `## 易错点`（见技术执行顺序步骤 2）。场景仍不明确或仅说「接入易宝」时，**不适用**快速通道，回到逐步澄清。



### ① 明确需求

- 先复述理解，给出**初步判断**（例如「听起来像小程序内收款」或「更像线下扫码枪收款」），可附 1～2 句原因分析。
- **禁止**一上来就堆参数清单、接口路径、代码块。
- 需求模糊时，读 `references/产品能力/产品决策.md` 的「场景关键词匹配」与「标准澄清模板」，用**商户能听懂的话**追问，而不是技术枚举。

**典型入口——商户仅说「要接入易宝支付」且未说明场景时**：

1. 先判断是**新接入**还是**已有对接在排障**（问一句即可）。
2. 新接入：**不得**直接生成代码；须用 `产品决策.md` **模板 1（业务场景总澄清）** 或按关键词命中情况选用模板 2～6，请商户描述具体业务（载体、线上/线下、谁扫谁）。
3. 场景仍不明确时，只输出澄清问题，**停止**后续步骤。
4. 场景明确后，用一句话告知推荐方案（如「您的情况适合小程序支付」），并说明**为什么**，仍不输出实现细节。

**典型入口——商户描述具体现象（验签失败、回调收不到、退款卡住）**：

1. 先归纳现象与可能方向（1～3 条），引用 `troubleshooting.md` 思路，不急于要密钥或日志。
2. 若信息不足，列出**还缺什么才能判断**（如环境、接口名、错误码），但不当作已授权去执行。



### ② 征得同意

- 在给出方案摘要后，**主动提出**下一步可做什么，例如：
  - 「我可以按您确认的小程序支付场景，整理一份接入步骤清单，需要吗？」
  - 「如果您愿意，我可以根据在线文档帮您核对下单必填参数，是否继续？」
- **必须等商户明确同意**（「好的」「继续」「可以」等）后，才进入信息收集或文档拉取。
- 商户未表态、仅补充描述、或问题仍模糊时：**停留在①**，继续澄清，不得默认同意。



### ③ 收集信息

- 商户同意后再说明：**为实现下一步，需要哪些信息**，并**逐项**收集；未收齐不进入实现或执行。
- 按任务类型区分「必要」与「可后补」：


| 任务类型        | 通常必要信息                                                                                           | 可后补                 |
| ----------- | ------------------------------------------------------------------------------------------------ | ------------------- |
| 新接入方案       | 支付载体、线上/线下、是否自有小程序/APP                                                                           | 商户号、AppKey（方案阶段可不问） |
| 生成接入代码/参数说明 | 已确认场景 md、环境（沙箱/生产）、语言/框架                                                                         | notifyUrl 具体地址      |
| 联调排障        | 环境、接口名或 catalog id、完整错误码/报错原文、是否收到回调                                                             | 订单号（查单时必要）          |
| 脚本/工具执行     | AppKey、私钥路径、商户号、业务单号等（见 `scripts/README.md`）；**须先通过** `python scripts/tools/check_python_env.py` | —                   |


- 收集时用表格或编号列表，**一次不要问超过 5 个**；敏感信息提醒勿在聊天中粘贴完整私钥/卡号。涉及航旅易达时，额外勿索要或接收乘客信息、联系人电话、支付账号、密码、航司 B2B 账号（见 `references/产品能力/航旅易达/航旅易达.md`「环境与安全约束」）。



### ④ 执行前确认

- 即将执行的操作包括：**curl 拉文档**、**输出完整代码**、**运行 scripts/**、**给出生产环境配置建议** 等，执行前用一句话说明将做什么。
- 运行 `scripts/` 前须先执行 `python scripts/tools/check_python_env.py`；未通过则向用户说明须 Python ≥3.10 并安装 `scripts/requirements.txt`，**不得**继续执行其他脚本。
- 示例：「我将根据小程序支付场景拉取统一下单在线文档并整理必填参数表，确认后继续？」
- 涉及**生产环境**、**真实资金操作**（支付、退款、提现、分账、结算）时，**额外提示风险**：建议先沙箱、写操作需幂等与查单、生产密钥勿泄露。**航旅易达无沙箱**，不适用「建议先沙箱」，须直接按生产二次确认。
- 商户再次确认后才执行；若仅要方案不要代码，执行范围限于文档与步骤，不生成可运行密钥或调用生产。

> **生产环境调用强约束（不可跳过）**：任何指向**生产环境**的实际接口调用（含运行 `scripts/` 直连生产网关、生产密钥发起的下单/退款/提现/分账/结算等写操作，及任何会产生真实资金或真实数据变更的请求），在已完成上述④确认的基础上，**必须再向商户单独发起一次显式二次确认**，并明确告知：目标环境=生产、操作类型、影响的资金/订单范围、不可逆风险。**仅当商户明确回复同意**（如「确认在生产执行」）后方可发起；商户未确认、回复模糊或要求先看时，一律**默认按沙箱/演示处理或仅输出方案与命令**，不得擅自调用生产。

---



## 对话阶段与技能动作的对应关系

```text
商户开口
  → ① 明确需求（产品决策 / 关键词 / 澄清模板 / 排障初判）
  → ② 征得同意（提出下一步，等待确认）
  → ③ 收集信息（场景已锁定后的环境与参数）
  → ④ 执行前确认（拉文档 / 写代码 / 跑脚本）
  → 按下方「技术执行顺序」落地
  → 按「标准输出模板」回复
```


| 阶段  | 可读参考                               | 禁止                  |
| --- | ---------------------------------- | ------------------- |
| ①   | `产品决策.md` 第四节（场景关键词匹配）、第五节（标准澄清模板） | 输出代码、curl 业务网关、参数大全 |
| ②   | 用自然语言提议                            | 假设用户同意并继续           |
| ③   | 场景 md 中的「接入步骤」                     | 缺场景就索要 AppKey/私钥    |
| ④   | 文档加载协议、`scripts/README.md`         | 未确认即跑脚本或调生产         |


---



## 通用技术纪律（执行阶段遵守）

- 写操作（支付、退款、分账、提现等）前确认：环境（沙箱/生产）、商户号、AppKey、notifyUrl 来源。
- **面向生产环境发起任何实际调用前，必须经商户显式二次确认**（见面客纪律④「生产环境调用强约束」）；未确认时不得直连生产，只输出方案/命令或按沙箱处理。
- `account`（账户）、`balance`（代付代发）分组的资金出款类接口（如提现 `/rest/v1.0/account/withdraw/order`、代付 `/rest/v1.0/balance/transfer_send`）**必须使用 CFCA 证书**签名并配置 IP 白名单；未配置证书直接调用会报错。涉及出款接入/排障时，先读 `references/平台文档/接入准备/密钥管理/CFCA证书介绍.md`。
- 交易终态 = **回调 + 查单** 双通道确认，不以前端页面为准。
- 写操作使用业务唯一单号；回调处理必须幂等；超时/未知先查状态再决定是否重试。
- 错误码两层：先看接口自身业务码，再看平台通用码（见 `references/平台文档/开始对接/平台错误码说明.md`）。
- 禁止输出私钥、完整密钥、完整卡号/证件号。
- 接口字段以在线 `doc_md` 为准；`curl` 在技能里**主要指拉取文档**，业务网关调用须 YOP 签名，不能裸 curl 调通。

---



## 写代码任务路由（是否使用 SDK）

写对接代码前，先确认客户**是否使用官方 SDK**；未声明时列入「待确认」询问，**不默认**选路径。

**分层说明（避免与步骤 4 表格混淆）**：

- **L1 / L2 / L2'**：互斥路径，决定「怎么发请求」——自研签名/加解密（L1）或官方 SDK（L2 Java / L2' 其他语言）。
- **L3**：**所有写代码任务共用**，非互斥分支；指接口在线 `doc_md`（字段、错误码、示例代码骨架），在「技术执行顺序」步骤 5～7 与「文档加载协议」中统一处理。

```text
使用官方 SDK？
  ├─ 是：
  │    Java → SDK使用说明.md（L2）+ doc_md 调用骨架（L3）
  │    其他语言 → 平台SDK.md 定位仓库 README（L2'）+ doc_md 参数表（L3）
  └─ 否（语言无 SDK，或主动不引依赖/自研网关/合规限制）：
       平台文档/平台规范/安全认证/ 的请求签名协议.md、回调解密协议.md（L1）
       实现签名/加密/回调解密 + doc_md 参数表（L3）+ scripts/ 本地验证
```

**Java SDK 版本（L2 写代码前）**：生成依赖坐标前须实时解析 `yop-java-sdk` 最新稳定版，禁止硬编码或凭记忆。优先 `python scripts/tools/resolve_java_sdk_version.py`，或按 `SDK使用说明.md`「版本解析协议」用 [central.sonatype.com](https://central.sonatype.com/artifact/com.yeepay.yop.sdk/yop-java-sdk) / Solr（**须** `sort=v desc`）。**勿用** `search.maven.org`（索引滞后）；**勿用** 不带 `sort=v desc` 的 Solr 查询（会误返旧版如 `4.2.2-jdk6on`）。软算法包版本与主包一致。

**Java SDK 配置（L2）**：只配 AppKey + 商户私钥；**不要**让商户配置易宝平台公钥 / SM2 平台证书（SDK 已内置并自动更新，手配错误反而验签失败）。生成配置时默认不写入 `yop_public_key`；审阅已有 `yop_sdk_config*.json` 若发现该项，先**询问用户为何配置**（如历史兼容、非官方 SDK 混用等），再**建议用户自行移除**，勿直接删改对方配置。详见 `SDK使用说明.md` §三。

---



## 技术执行顺序（商户已确认场景且同意继续后）

1. **核对前提**：对照 `references/产品能力/产品决策.md` 核对已确认的方案与收款主体（标准/平台/服务商）；核对不通过（场景或主体仍有歧义）→ 退回面客纪律①②继续澄清，**不进入后续步骤**。
2. **【强制】阅读场景 md 与易错点**：先按下方「业务域路由」定位业务域（入网/收单/退款/分账/出款/对账/金融/航旅易达），收单再按「收单场景索引」锁定具体场景文件，金融再按「金融场景索引」锁定产品文件，航旅易达再按场景 md「渠道决策」锁定渠道；**完整阅读** `references/产品能力/<业务域>/<场景>.md` 全文，其中 `## 易错点` **章节为必读**（及该节引用的关联文档，如 `prePayTn唤起方式速查.md`）。**未完成本步禁止进入步骤 5（curl doc_md）及步骤 7（生成代码/参数表）**。**若映射不到任何业务域/场景**（需求超出覆盖范围或仍有歧义）→ 用 `产品决策.md` **模板 7（超出产品能力范围）** 回复或退回面客纪律①②澄清，**不臆造场景路径**。
3. 写代码任务：按「写代码任务路由」确认 SDK 使用意愿，**锁定 L1 / L2 / L2' 之一**（L3 不在此步选择，见步骤 5～7）。
4. **按路径与任务类型读平台文档**（用 `references/平台文档/platform-doc-manifest.yaml` 的 topics 定位；下表为必读，其余按需）：


| 任务特征                     | 必读                                                |
| ------------------------ | ------------------------------------------------- |
| L1（不使用 SDK）              | `平台规范/安全认证/请求签名协议.md`、`回调解密协议.md`                 |
| L2（Java SDK）             | `开始对接/SDK使用说明.md`（报错时加 `Java-SDK报错说明.md`）         |
| L2'（其他语言 SDK）            | `工具与支持/开发工具/平台SDK.md` 定位仓库 README                 |
| 涉及出款（account/balance 分组） | `接入准备/密钥管理/CFCA证书介绍.md`、`开始对接/配置IP白名单.md`         |
| 涉及回调                     | `平台规范/结果通知机制说明.md`                                |
| 排障                       | `references/troubleshooting.md`、`开始对接/平台错误码说明.md` |


> **L3（接口 doc_md）**：上表仅覆盖 L1/L2 的**本地平台文档**；L3 为在线接口文档，在步骤 5 定位 `doc_md`、步骤 6 curl 拉取、步骤 7 生成代码时处理，纪律见「文档加载协议」与「示例代码节纪律（L3）」。

1. 在 `references/产品能力/api-index.yaml` 定位接口 `doc_md`（**L3 起点**；**前置条件：步骤 2 易错点已读**）。
2. **生成或核对接口字段/错误码前，必须执行文档加载协议（curl doc_md）**（**L3 拉取**；**前置条件：步骤 2 易错点已读**）。
3. 依据 doc_md、步骤 2 易错点与所选 L1/L2 路径生成代码/参数表（遵守「示例代码节纪律（L3）」；参数取值须与易错点一致，冲突时以 doc_md 字段定义为准、易错点约束业务选型与组合）。
4. 需要本地验证时，经④确认后**先**运行 `python scripts/tools/check_python_env.py`（Python ≥3.10 与依赖就绪）；未通过则引导用户升级 Python / `pip install -r scripts/requirements.txt`，**不得**继续执行其他脚本。通过后再使用 `scripts/`（见 `scripts/README.md`）。
5. 按「标准输出模板」回复。

---



## 文档加载协议（API 类任务）

接口规格从开放平台在线 markdown **实时 curl** 获取：

```text
1. 在 api-index.yaml 按域+场景定位目标接口，取其 doc_md。
2. 拉取接口文档：
   curl -sS "https://open.yeepay.com/docs-v3/api/<slug>.md"
   slug：<method小写>_<path去掉开头/，/ 换 _>（保留 . 与 -）
   例外：yos 等接口优先用 api-index 已实测的 doc_md；404/403 再试 options_ 前缀。
3. 涉及回调（**以接口 doc_md 为准**）：
   a. 在上一步拉取的 doc_md 中查找「结果通知」节（含通知编码与 notify 文档链接）。
   b. 取该节中的通知编码 / notify 文档 URL，curl 拉取 notify 文档后再实现回调解析。
   c. api-index 的 notify_spi 仅为索引提示；与 doc_md 不一致或缺失时，**以 doc_md 为准**，不得臆造 SPI。
4. 参数解读（**以拉取到的反参为准，禁止凭字段名或同类接口推断**）：
   a. 各参数的支持方式（取值范围、枚举、格式、业务含义）以该 API 内
      该参数的**描述（description）**为准。
   b. `是否必填` = **条件必填** 时，openapi.json 格式的接口须额外读取该参数的
      `x-yop-api-param-condition` 字段获取必填条件；未读取前不得按「可选」处理，
      也不得自行编造条件。
5. 场景 md 只提供流程与易错点；禁止仅凭它拼接口参数。
6. curl 失败/超时：提示检查网络；不得编造字段；停止字段级实现。
7. 回复中注明 doc_md「基本信息」中的 API ID 与「最后更新时间」。
```



### 示例代码节纪律（L3）

doc_md「示例代码」节为**自动生成的全参数模板**（含脏占位值），agent **只取调用骨架**（Client 构建、请求方法、Content-Type）。
参数 MUST 按「请求参数」表的必填/条件逻辑重新筛选，**禁止照抄**全部 addParameter 与占位值。
参数的支持方式以该参数 `description` 为准；`条件必填` 参数在 openapi.json 中须读 `x-yop-api-param-condition` 拿到必填条件后再决定是否传（见「文档加载协议」第 4 条）。

> 人类可读页 `https://open.yeepay.com/docs/products/<product>/api/<uri>` 为 SPA，**curl 取不到字段**。
> doc_md 章节结构：`基本信息`、`请求参数`、`请求示例`、`响应参数`、`响应示例`、`错误码`、（有回调时）`结果通知`、`示例代码`。
> `references/平台文档/` 为本地权威内容，**不走 curl**。
>
> **航旅易达例外**：机票接口按渠道（解决方案）组织，**不适用** `docs-v3/api/<slug>.md` 推导规则；
> **阅读顺序强制**：先 curl「产品介绍」`intro_md`（适用场景）→（若有）`config_md` 渠道配置说明并指导商户完成/确认 → 再 curl「接口调用指引」`doc_md`（接口调用顺序矩阵）→ 字段级实现前 curl 目标接口 openapi.json（清单见 `references/产品能力/航旅易达/渠道API清单.md`）。
> 产品介绍场景不匹配时不得套用该渠道接口；不得从其他渠道推导接口契约；curl 失败时不得臆造内容。
> **渠道配置**：配置通常需商户后台、运营、客户经理或航司侧动作，Agent 不能代完成。
> **无沙箱**：航旅易达接口均在生产环境调用，不得按「先沙箱」引导；实际调用须生产二次确认。
> **敏感信息**：勿向 Agent 索要或接收乘客信息、联系人电话、支付账号、密码、航司 B2B 账号；示例一律用占位符。
> **开票**：机票报销凭证/开票诉求通常引导至电子行程单接口；不要按通用增值税发票产品处理（见场景 md「附加能力说明」）。

---



## 业务域路由


| 用户意图（关键词）              | 场景目录                                                 | catalog 分组       |
| ---------------------- | ---------------------------------------------------- | ---------------- |
| 入网/进件/入件/子商户入网/商户信息变更/解冻     | `references/产品能力/入网/入网.md`                           | `merchant-netin` |
| 实名认证/开户意愿确认/商户报备后认证        | `references/产品能力/入网/实名认证.md`                         | `merchant-netin` |
| 下单/小程序/APP/H5/主扫/被扫/查单 | `references/产品能力/收单/`                                | `acquiring`      |
| 退款/退款查询                | `references/产品能力/退款/退款.md`                           | `refund`         |
| 分账/分账查询/资金归还/入账方       | `references/产品能力/分账/`                                | `profit-sharing` |
| 结算/提现/提现卡              | `references/产品能力/出款/`                                | `payout`         |
| 对账/账单下载/差异处理           | `references/产品能力/对账/`                                | `reconciliation` |
| 放款/对公快捷/联合贷/订单付款/信用卡还款/跨行还款/协议支付/代扣/签约绑卡/一键绑卡/存量签约/批量支付 | `references/产品能力/金融/`              | `financial`      |
| 机票/出票/退票/改签/验舱验价/NDC/航旅易达/航司对接/电子行程单/机票开票 | `references/产品能力/航旅易达/航旅易达.md`               | `airline`        |
| 验签失败/回调收不到/上线检查        | `references/troubleshooting.md` + `references/平台文档/` | （本地）             |


需求不在上表覆盖范围时，使用 `产品决策.md` **模板 7（超出产品能力范围）** 回复，不臆造方案。

---



## 收单场景索引


| 场景                   | 场景文件                                   |
| -------------------- | -------------------------------------- |
| 浏览器 H5 支付            | `references/产品能力/收单/浏览器H5支付.md`        |
| 小程序支付                | `references/产品能力/收单/小程序支付.md`          |
| APP 支付（使用易宝小程序）      | `references/产品能力/收单/APP支付（使用易宝小程序）.md` |
| APP 支付（使用客户小程序）      | `references/产品能力/收单/APP支付（使用客户小程序）.md` |
| 微信内 H5+公众号支付         | `references/产品能力/收单/微信内H5+公众号支付.md`    |
| 被扫支付                 | `references/产品能力/收单/被扫支付.md`           |
| 主扫支付（独立码-线上PC）       | `references/产品能力/收单/主扫支付（独立码-线上PC）.md` |
| 主扫支付（聚合码）            | `references/产品能力/收单/主扫支付（聚合码）.md`      |
| prePayTn 唤起方式速查（跨场景） | `references/产品能力/收单/prePayTn唤起方式速查.md` |


---



## 金融场景索引

金融域面向**持牌金融机构**（银行、消费金融、汽车金融、融资租赁、保险、基金、信托、小贷、保理等）。选型先按 `references/产品能力/产品决策.md`「二之二、金融行业决策树」按**钱的方向**分流，需求模糊时用**模板 8**（代扣方向）或**模板 9**（放款模式）澄清。


| 场景                                   | 场景文件                             |
| ------------------------------------ | -------------------------------- |
| 放款（订单付款对公快捷 / 联合贷）                   | `references/产品能力/金融/放款.md`       |
| 信用卡跨行还款（卡中心视角）                       | `references/产品能力/金融/信用卡还款.md`    |
| 协议支付（签约绑卡 / 一键绑卡 / 存量签约 / 代扣 / 批量支付） | `references/产品能力/金融/协议支付.md`     |
| 网联一键绑卡支持银行速查（跨场景，按需加载）             | `references/产品能力/金融/网联一键绑卡支持银行.md` |


金融域强约束（生成参数/代码前必须已读对应场景 md「易错点」）：

- **协议支付 1.0 与 2.0 是两套接口**：下单与查询必须配对（1.0 `cnppay-agreement-pay-request` ↔ `cnppay-query`；2.0 `financial-order-pay-request` ↔ `financial-order-pay-query`），交叉使用会查不到订单。
- **协议支付 ≠ 收单**：商户主动发起的银行卡代扣走金融域；用户在场主动付款走收单域，不可互换。
- **放款付款卡/收款卡不可颠倒**：`remitCardInfo`（付款方=资金方）订单付款业务下只支持 `CORPORATE`；`receiverCardInfo`（收款方=借款人）支持 `DEBIT`/`CORPORATE`。
- **产品按银行开通三级产品**：放款、协议支付快捷还款、信用卡还款均须先明确银行；放款另需完成**对公户报备**。
- **签约关系一致性**：用 `bindId` 扣款时若上送 `userType`/`userNo`，必须与绑卡时一致；不上送用户标识需与易宝单独沟通配置。

---



## 工具脚本（本地，Python ≥3.10）


| 用途                         | 脚本                                                      |
| -------------------------- | ------------------------------------------------------- |
| **环境校验（运行任何脚本前必做）**        | `scripts/tools/check_python_env.py`                     |
| RSA 联调（密钥/查单/退款/回调/应答验签）   | `scripts/rsa/`；应答验签 `scripts/common/response_verify.py` |
| 国密 SM2（密钥/签名/回调/平台证书/应答验签） | `scripts/sm/`；跨算法工具 `scripts/tools/`（向量校验、离线应答验签）       |


> 运行任何脚本前须完成面客纪律 ②③④，并**先**执行 `check_python_env.py`；仅用于联调，生产走商户自有系统。详见 `scripts/README.md`。

---



## 标准输出模板

> 以下模板是**结构参考而非强制表单**：按对话所处阶段选用，可裁剪空节、合并小节。需求已明确走「快速通道」时，可跳过 A/B 直接用 C（接入实现）；用户明确「只要代码/参数」时，C 可精简为「关键易错点 + 接口 + 实现步骤 + 代码 + 风险与待确认」，但仍须保留 `## 关键易错点`**（来自场景 md，不可省略）**、**API ID/最后更新时间**（来自 curl 的 doc_md）与**环境/生产二次确认**提示。



### A. 首次咨询 / 场景未定时（对应 ①②）

```markdown
## 我的理解
（用商户语言复述需求）

## 初步判断
（推荐方向 + 简短原因，不涉及接口参数）

## 需要您确认的场景
（引用产品决策澄清模板中的问题，或 2～4 个选择题）

## 确认后我可以帮您
（列出 1～2 项可选下一步，等待用户同意）
```



### B. 方案已确认、尚未写代码（对应 ③）

```markdown
## 为您匹配的方案
（场景名称 + 对应场景 md）

## 接入概览
（3～5 步业务流程，商户能看懂）

## 开通产品与前置条件
（若适用）

## 继续前需要您提供
（逐项列出，标注必填/选填）

## 您确认后我将
（拉文档 / 整理参数表 / 示例代码 — 须用户同意才做）
```



### C. 接入实现（对应 ④ 之后）

```markdown
## 场景
## 关键易错点（已从场景 md 核对）
（逐条列出场景 md「## 易错点」中与本次实现相关的条目，可用勾选形式标注已落实）
## 必读规则（平台文档）
## 接口（含 API ID 与最后更新时间）
## 实现步骤
## 风险与约束（幂等/回调/查单/环境）
## 待确认（环境/是否使用SDK/支付方式/参数来源）
```



### D. 排障结论

```markdown
## 现象
## 已排除
## 最可能原因（按优先级）
## 建议操作（先查后重试）
## 需补充的信息
## 如需我进一步查文档或脚本验证
（说明将做什么，等待同意）
```

---



## 目录说明

本技能包路径：`skills/yeepay-payment-integration/`（仓库 [yeepay-skills](https://github.com/Yeepay-Open-Platform/yeepay-skills) 内）。

```text
../../                           仓库根（yeepay-skills）
  README.md / CHANGELOG.md / LICENSE.md
SKILL.md                         本文件，唯一入口（面客纪律 + 技术执行）
scripts/                         Python 联调工具（仅本地，详见 scripts/README.md）
  validate_docs.py             发版守门（死链/版本一致/测试向量校验）
  common/                      跨算法共用库
    python_version.py          Python 版本校验（≥3.10）
    response_verify.py         应答验签（RSA/SM2）
    url_encoding.py            签名一次编码 / HTTP 二次编码
    yop_headers.py             YOP 标准头
    yop_content_type.py        Content-Type 规范
    yop_http.py                HTTP 报文组装
    yop_gateway.py             生产 yos / 沙箱 sandbox 网关
    yop_multipart.py           multipart 签名
    yop_payload.py             请求体编解码
  rsa/ sm/                     RSA / 国密 SM2 密钥、客户端、查单/回调、测试向量
  tools/                       跨算法 CLI：环境校验、向量校验、离线应答验签、Java SDK 版本查询
references/
  troubleshooting.md           各业务域排障汇总
  平台文档/                    本地权威（约 30 篇）
    platform-doc-manifest.yaml   平台规则导航索引（topics 定位必读文档）
    接入准备/                  快速接入、应用管理、密钥管理（CFCA/RSA/SM）
    开始对接/                  SDK、沙箱、IP 白名单、错误码、Java SDK 报错
    平台规范/                  上线检查、回调网络、结果通知机制/查询重发
      安全认证/                鉴权/加密/签名/回调解密/结果通知 + 请求签名协议（含测试向量）
    工具与支持/                常见问题、最佳实践（文件下载）、开发工具（SDK/密钥/MCP/诊断）
  产品能力/
    产品决策.md                选型、关键词、澄清模板、超范围回复
    api-index.yaml             API curl 清单（doc_md / path / method / api_id）
    入网/ 收单/ 退款/ 分账/ 出款/ 对账/   场景文档（流程+易错点+前端示例+引用）
    金融/                      放款、信用卡还款、协议支付 + 一键绑卡支持银行速查
    航旅易达/                  机票场景文档（渠道决策+易错点）与渠道API清单（openapi.json 索引）
```