Copyright © 2026 浙江商盟支付有限公司 (SUM PAYMENT SERVICES CO.,LTD). All rights reserved. 本 Skill 包含商盟收结汇4.0产品 SDK、证书及开发规范，仅供授权商户集成使用，禁止未经授权的传播或商用。

sumpay-fx-settle-4

在现有 Java Spring Boot 项目中集成 Sumpay 收结汇4.0（跨境收结汇）产品。

使用时机

触发条件：

• 用户使用 /sumpay-fx-settle-4 触发
• 用户要求在项目中接入/对接/集成收结汇4.0
• 用户提到 "收结汇"、"FX Settle"、"crossborder settlement" 并需要写代码

不触发条件：

• 用户只是讨论收结汇业务逻辑而不需要写代码
• 用户要求对接其他支付产品（收单、代付等）

前置条件

执行本 Skill 前，商户需已获取：

测试环境默认值：商户号 200104913781，应用ID s100000040，证书密码 sumpay。生产环境替换为真实值。

SDK、Demo、证书、在线接口文档均通过文档系统动态获取，详见 resource-download.md。

关键规则

以下规则在整个 Skill 执行过程中必须遵守，违反将导致编译失败或运行时错误：

1. sign_type 绝对不能设在 bizRequest 上 — SDK 通过 Request.setCertType("CERT") 处理签名类型，设在 bizRequest 上会导致 sign_type 参与签名，服务端返回 888888
2. domain 仅在文件上传接口设置 — 非文件上传接口设置 domain 同样导致 888888
3. setter 方法必须通过 javap 验证后才能调用 — 在线文档字段 ≠ SDK 实际方法签名，必须先 javap 反编译确认，再写 setXxx() 调用
4. classpath 证书路径必须 URLDecoder.decode() — 中文路径场景会 FileNotFoundException
5. verifyMsgNew() 抛 checked exception — 必须用 try-catch 包裹，否则编译失败
6. 响应 Map 的 key 以 SDK 实际返回为准 — 首次调试时打印完整 resp 确认
7. 永远不要在 bizRequest 上设置 FileContext 类型的 file 字段 — 会导致 FileContext 被 JSON.toJSONString 序列化进 content，破坏报文。文件必须通过 targetRequest.setFileParams() 传递
8. 包含 List 子参数的接口（如 files）必须通过 subParams 传递 — key 名和传递方式以 Demo 为准，不能用 req.setXxx() 代替

核心工作流程

第一步：前置确认

获取文档 Token（必须）

在线接口文档是对接的前置依赖。使用 AskUserQuestion 要求用户提供 Token：

• 用户提供了 Token → 继续，拉取目录树和接口文档
• 用户未提供 Token → 终止流程，提示联系商盟技术支持获取 Token

用户提供 Token 后，按 resource-download.md 拉取目录树，识别各资源对应的 catalogId。

分析现有项目

扫描当前工作目录，了解：项目结构、构建工具（Maven/Gradle）、Spring Boot 版本、现有配置格式、代码风格。

如果当前目录不是 Java 项目，使用 AskUserQuestion 确认目标项目路径。

确认对接参数 [确认节点]

向用户确认：商户号、App ID、目标环境、证书路径、证书密码、域名、需要接入的接口列表。

核心接口（默认全选）：2.1 个人客户信息上传、2.3 企业客户信息上传、2.2 查询个人客户信息、2.4 查询企业客户信息、2.9 文件上传、2.10 文件查询、2.40 收款材料上送、2.41 收款材料异步通知、2.42 直接下发、2.43 直接下发查询、2.44 直接下发异步通知、2.45 收结汇4.0材料查询

可选接口：2.46 收结汇财务明细下载、2.29 下发电子回单下载

业务流程与接口依赖

① 客户报备(2.1/2.3) → customer_no
② 客户查询(2.2/2.4) → 客户状态信息
③ 文件上传(2.9) → sumpay_batch_no
④ 文件查询(2.10) → 文件处理状态
⑤ 收款材料上送(2.40) ← 引用 customer_no + sumpay_batch_no
⑥ 直接下发(2.42) ← 引用 customer_no
⑦ 确认结果 ← 异步通知(2.44) + 主动查询(2.43)
⑧ 材料审核结果 ← 异步通知(2.41) + 主动查询(2.45)
⑨ 对账(2.46) — 每日财务明细下载
⑩ 电子回单(2.29) — 下发成功后下载回单

快速验证：查询类接口（2.2/2.4/2.10/2.43/2.45）无需前置数据，用不存在的单号查询，只要不是 888888 或 EG000001 就说明签名通信正常。

第二步：集成 SDK

按 resource-download.md 下载 SDK 和 Demo，解压 SDK JAR 到项目 lib/，解压 Demo 到临时目录。集成到项目详见 sdk-integration.md。

第三步：SDK 验证（硬性门禁）

详见 sdk-reference.md 中的「Demo 映射表」和「已验证接口模式」

代码生成前的强制性验证步骤。 具体流程：

读取每个目标接口对应的 Demo 源码

Demo 已在第二步下载并解压到临时目录。每个接口都有对应的 Demo 文件（见 sdk-reference.md 的映射表）。读取 Demo 是获取正确调用模式（文件上传方式、subParams key、序列化行为）的唯一可靠来源。

javap 反编译所有目标接口的 SDK Request 类

对每个目标接口对应的 SDK Request 类执行 javap，提取所有实际存在的 setter 方法签名：

javap -p -cp lib/merchant-integration-api-core.jar {完整类路径}

同时反编译所有被 Demo 引用的 entity 类（如 CollectDetailFile）。

交叉比对，生成「已验证方法清单」

将以下三者交叉比对，生成每个接口的已验证方法清单：

• 在线文档字段（按 resource-download.md 拉取各接口页面详情）→ 确认字段含义、必填性、响应外层 key 名和响应内层字段名
• javap 实际方法（第三步）→ 确认 setter 是否存在、参数类型
• Demo 调用方式（第三步）→ 确认正确的调用模式

⛔ 如果文档字段在 javap 中找不到对应 setter → 该字段不生成 setter 调用，记录到 TODO
⛔ 如果 Demo 的调用方式与文档不一致 → 以 Demo 为准
⛔ 如果 Demo 使用了 javap 中不存在的 entity 类 → 先 javap 该 entity 类确认

验证完成标志： 每个接口都有一个「已验证方法清单」，列明：哪些 setter 可以调用、哪些字段走 subParams、文件上传走 fileParams 还是 req.setFile()、响应外层 key（如 sumpay_distribute_response）和响应内层字段映射。清单作为第四步代码生成的唯一输入。

第四步：生成集成代码

详见 code-generation.md

硬性门禁：必须完成第三步验证后才能生成代码。 每一个 setXxx() 调用都必须能追溯到 javap 输出和 Demo 源码。

在现有项目包结构下生成收结汇模块代码（config/client/model/service/exception），遵循项目已有的包命名规范和代码风格。

第五步：编译与测试

按 resource-download.md 下载测试证书到 src/main/resources/cert/。

编译与测试详见 testing-and-deployment.md

硬性要求：为本次接入的所有接口生成单元测试，且测试必须通过。

Step 1: 建议用户执行 mvn clean compile              → 编译通过
Step 2: 为所有接口生成单元测试           → 查询类启用，写入类/通知类 @Disabled
Step 3: 建议用户执行 mvn test                       → 查询类测试必须全部通过（硬性门禁）
Step 4: 向用户报告完整测试结果           → 列出每个测试的状态和响应码

查询类（6 个测试）不通过 = 集成失败，必须排查后重跑。写入类/通知类生成框架代码标注 TODO，提醒用户替换数据后启用。

技术参考

详见 sdk-reference.md — 环境规格、签名机制、SDK 类路径、service 枚举、错误排查。