深色模式
工银亚洲 ICBC
本页说明
讲什么：工银亚洲渠道侧接口规范 + moomoo 侧适配逻辑 适合谁：PM 了解对接细节 / 开发定位代码 / 运营理解银行特性 前置阅读：银行能力矩阵预计阅读：8 分钟 负责人：出入金产品团队
核心要点：工银亚洲是传统入金通道代表——API 定时拉取流水，仅支持手工出金和电汇，无 FPS、无 BST、无 eDDA。
能力总览
| 能力 | 支持情况 | 协议/通道 | 核心服务 |
|---|---|---|---|
| 入金流水采集 | ✅ | 银企直联 REST API | icbc_be_relay (Python) |
| 出金 | ✅ | 手工出金（运营操作企业网银） | method=manual |
| FPS 入金 | ✅ | 流水匹配 → 可自动入账 | IcbcasiaMatch |
| 网银转账入金 | ✅ | 流水匹配 → 可自动入账 | IcbcasiaMatch |
| 汇款存入 | ✅ | 流水匹配 → 可自动入账 | IcbcasiaMatch |
| ATM 入金 | ⚠️ | 流水匹配 → 不可自动入账 | 人工审核 |
| 支票入金 | ⚠️ | 流水匹配 → 不可自动入账 | 人工审核 |
| eDDA/eDDI | ❌ | — | — |
| 银证 BST | ❌ | — | — |
| 标识 | 值 |
|---|---|
| IMPORT_BANK_ID | 10（ICBCASIA） |
| TransType | 202 |
| 匹配命令 | match:main icbc-new（每 3 分钟） |
工银亚洲是中资银行中接口成熟度较高的一家——通过银企直联 API 实时采集流水，支持 FPS/网银/汇款三种方式自动入账。出金为手工模式，运营人员在企业网银操作。
渠道接口概览
工银亚洲通过"银企直联"（Bank-Enterprise Direct Connection）协议对接，这是中资银行面向企业客户的标准化接口方案。
| 维度 | 说明 |
|---|---|
| 传输协议 | HTTPS REST |
| 数据格式 | JSON |
| 认证方式 | RSA2 签名（私钥签名 biz_content，银行公钥验签） |
| 分页方式 | cursor-based（next_tag 字段） |
| 核心服务 | icbc_be_relay（Python） |
RSA2 签名机制
每个请求都需要 RSA2 签名验证，双向校验确保数据完整性：
msg_id 生成规则："futu" + 毫秒级时间戳 + 2 位随机数，确保每笔请求全局唯一。
渠道侧接口详情
流水查询接口
这是工银亚洲的核心接口，用于拉取指定日期范围和币种的交易流水。
请求参数
| 字段 | 类型 | 必填 | 描述 |
|---|---|---|---|
app_id | string | ✅ | 应用标识。生产环境配置 |
msg_id | string | ✅ | 唯一交易号。如 "futu" + 毫秒时间戳 + 2位随机数 |
sign_type | string | ✅ | 签名类型。取值 "RSA2" |
sign | string | ✅ | 签名值。RSA 私钥对 biz_content 签名 |
timestamp | string | ✅ | 请求时间。格式 "YYYY-MM-DD HH:MM:SS" |
biz_content.account_no | string | ✅ | 银行账号。moomoo 在工银的收款账户号 |
biz_content.bank_code | string | ✅ | 银行代码。工银亚洲银行代码 |
biz_content.begin_date | string | ✅ | 起始日期。格式 "YYYYMMDD" |
biz_content.end_date | string | ✅ | 结束日期。格式 "YYYYMMDD" |
biz_content.currency | string | ✅ | 币种。取值 HKD / USD / CNH |
biz_content.min_amount | string | ❌ | 最小金额。过滤小额流水 |
biz_content.trans_code | string | ✅ | 交易类型码。硬编码（生产环境特定值） |
biz_content.cis | string | ✅ | 客户端系统 ID。硬编码 |
biz_content.login_id | string | ✅ | 登录 ID。硬编码 |
biz_content.next_tag | string | ❌ | 分页标记。首次请求为空；后续传银行返回的 next_tag 值 |
响应参数
| 字段 | 类型 | 描述 |
|---|---|---|
debit_amount | decimal | 借方金额（单位：分，无小数点） |
credit_amount | decimal | 贷方金额（单位：分，无小数点） |
balance | decimal | 当笔交易后的余额（单位：分） |
th_currency | string | 币种（由账户类型决定） |
busi_time | string | 交易时间 HHMMSS（用于排序和去重） |
remarks | string | 交易备注（含交易类型、付款人信息） |
date | string | 交易日期 YYYYMMDD |
time | string | 时间 HHMMSS |
金额单位注意
工银亚洲返回的金额以**"分"为单位**，没有小数点。例如 100 元实际返回 10000。系统在解析时必须除以 100 转换为元。这与大多数银行直接返回元/小数点格式不同，是工银对接中最容易出错的地方。
错误码
| 错误码 | 含义 | 处理方式 |
|---|---|---|
622394 | HTTP 请求错误 | 自动重试，记录日志 |
625565 | 公钥签名验证失败 | 检查 RSA 密钥对是否正确，核对密钥文件 |
622395 | msg_id 不匹配 | 技术排查，检查请求/响应 msg_id 一致性 |
622396 | 异常 return_code | 检查银行响应体中的具体错误信息 |
错误码配置位置
icbc_be_relay 中的监控指标 ID 与错误码一一对应，触发时会向监控系统上报。详见 统一错误码中心。
数据流
数据库表
| 表 | 用途 | 关键字段 |
|---|---|---|
raw_icbc_bank_flow | 原始银行响应，完整保留 | 银行返回的全量 JSON |
icbc_bank_flow | 解析后的标准化流水 | credit/debit（已转为元）、date、time、remarks |
icbc_balance | 余额快照（期初/期末结余） | balance、date |
icbc_be_next_tag | 分页标记，记录上次拉取位置 | next_tag、account_no、currency |
moomoo 侧适配
流水标准化映射
从工银亚洲原始字段到 moomoo 统一 BankFlow 格式的转换：
| 银行原始字段 | BankFlow 字段 | 转换逻辑 |
|---|---|---|
credit_amount | credit | 分 → 元（除以 100） |
debit_amount | debit | 分 → 元（除以 100） |
th_currency | ccy | 由账户类型映射（HKD/USD/CNH） |
date | date | 直接映射 YYYYMMDD |
busi_time | time | 直接映射 HHMMSS |
remarks | remarks | 直接映射（含交易类型中文标签） |
特殊处理规则
金额单位转换
工银亚洲是目前唯一以"分"为单位返回金额的银行。所有金额字段（credit_amount、debit_amount、balance）在写入 icbc_bank_flow 表前都必须除以 100。
卡号处理
工银亚洲卡号共 12 位，其中最后一位是币种标识符。匹配用户银行卡号时，需要去掉最后一位再比较。
工银卡号: 123456789010 （12位，末位"0"为币种标识）
匹配时用: 12345678901 （去掉末位，取前11位）卡号前缀处理
此外，匹配时还会自动去除 00 前缀——工银卡号格式特殊，部分流水中卡号前带有 00 填充。
去重逻辑
基于以下四个字段组合进行去重，相同组合的流水只入库一次：
去重键 = date + time + remarks + credit + debit匹配规则 (IcbcasiaMatch)
工银亚洲的匹配逻辑分为子账户路径和普通路径两条完全不同的链路。
双路径分发
| 路径 | 触发条件 | 自动入账？ | 金额容差与特殊要求 |
|---|---|---|---|
| 子账户路径 | 流水来自子账户 | ❌ 仅辅助匹配 | 子账户 SDK 校验 |
| 普通路径 — 精确 | 金额精确 + 姓名 EN+CN 双匹配 | ✅ | 0（FPS）/ -20 HKD / -3 USD。卡号（去末位）+ 日期窗口 |
| 普通路径 — 辅助 | 金额容差内 + 姓名相似 | ❌ | -20 HKD / -3 USD。卡号（去末位）+ 日期窗口 |
完全匹配条件（可自动入账）
所有条件必须同时满足：
| 维度 | 规则 | 说明 |
|---|---|---|
| 币种 | 精确匹配 | 流水币种 = 申请币种 |
| 金额 | CRM - 20 ≤ 流水 ≤ CRM（HKD/CNH）；CRM - 3 ≤ 流水 ≤ CRM（USD） | FPS 要求金额精确匹配（容差=0） |
| 姓名 | EN 和 CN 姓名双重校验都通过 | 比其他银行更严格 |
| 日期窗口 | -3 ~ +2 天 | 标准 daySimilar 窗口 |
| 卡号 | 去掉末位后精确匹配 | 工银 12 位卡号特殊处理 |
辅助匹配条件（需人工审核）
| 维度 | 规则 | 说明 |
|---|---|---|
| 币种 | 精确匹配 | — |
| 金额 | CRM - 20 ≤ 流水 ≤ CRM（HKD/CNH）；CRM - 3 ≤ 流水 ≤ CRM（USD） | 同自动入账容差 |
| 姓名 | 相似匹配（nameSimilar） | 非精确匹配也可进入人工审核 |
| 日期窗口 | -3 ~ +2 天 | — |
各入金方式匹配能力
| 入金方式 | 流水标签（remarks 中的中文标签） | 可自动入账 | 说明 |
|---|---|---|---|
| FPS 转账 | FPS 轉賬 | ✅ | 金额必须精确匹配（容差=0） |
| 网银转账 | 網上轉賬存款 | ✅ | 允许标准容差 |
| 汇款存入 | 匯款存入 | ✅ | 允许标准容差 |
| ATM 存款 | ATM 相关 | ❌ | 仅辅助匹配，需人工审核 |
| 支票存入 | 支票相关 | ❌ | 仅辅助匹配，需人工审核 |
| 子账户转账 | 子账户路径 | ❌ | 仅辅助匹配，经子账户 SDK 校验 |
金额容差汇总
| 币种 | 自动入账 / 辅助匹配容差 | ATM 特殊容差 | 汇款特殊容差（USD） |
|---|---|---|---|
| HKD/CNH | CRM - 20 ≤ 流水 ≤ CRM | CRM - 10 ~ CRM | — |
| USD | CRM - 3 ≤ 流水 ≤ CRM | — | CRM - 55 ~ CRM |
为什么 ATM 有特殊容差？ ATM 存款可能产生小额手续费（约 10 HKD），所以 ATM 容差设为 CRM-10 ~ CRM。
为什么 USD 汇款容差更大？ 美元跨行汇款经过中转行，中转行可能扣除高达 55 美元的手续费，因此 USD 汇款的容差远大于本地转账的 -3。
对应代码
deposit/src/app/Business/Match/IcbcasiaMatch.php — 包含子账户路径分发和普通路径的完整匹配逻辑。流水类型通过 remarks 字段中的中文标签进行正则匹配分发到不同规则。
余额连续性追踪
系统每天跟踪工银账户的余额变动，确保流水数据完整无遗漏：
校验公式
balance[今日起始] + SUM(credit - debit) == balance[今日结束]排序与取值
- 每天的流水按
busi_time ASC升序排列 - 首条记录的 balance = 当天起始余额
- 末条记录的 balance = 当天结束余额
- 如果等式不成立 → 流水数据不完整，触发告警
日期切换逻辑
| 时间 | 拉取策略 | 说明 |
|---|---|---|
| 00:00 ~ 00:35 | 拉取前一天的数据 | 银行日终结算可能延迟，确保前一天数据完整 |
| 00:35 之后 | 拉取当天的数据 | 切换到当天实时流水 |
为什么是 00:35？ 工银亚洲的日终批处理通常在 00:30 左右完成，留 5 分钟缓冲后切换到新的一天。
异步任务
| 任务 | 触发方式 | 说明 |
|---|---|---|
icbc_be_relay | cron 定时 | 定期从工银 API 拉取流水，存入 raw 表和解析表 |
| 每日补全 | 00:00:10 | 每天凌晨拉取前一天完整流水，确保无遗漏 |
match:main icbc-new | 每 3 分钟 | 执行工银流水匹配，尝试自动入账或辅助匹配 |
出金
工银亚洲目前不支持 API 自动化出金，采用手工方式处理。
| 维度 | 说明 |
|---|---|
| 方法码 | manual（手工出金） |
| 操作方式 | 运营人员登录工银企业网银，手动执行转账操作 |
| 跟进时间 | 3 天（比标准 1 天长） |
| 跟进时间较长原因 | 工银亚洲的流水到达速度较慢，出金后银行处理和流水反映需要更多时间 |
入金超时规则
当用户提交入金申请后，系统会设定通知和驳回的超时天数。超时后系统会通知用户或自动驳回。
| 入金方式 | 同行（通知天数 + 驳回天数） | 跨行 HKD/CNH | 跨行 USD |
|---|---|---|---|
| FPS | 1 天 + 1 天 | 2~4 天 + 1 天 | 1~4 天 + 1 天 |
| 网银转账 | 1 天 + 1 天 | 2~4 天 + 1 天 | 同左 |
| ATM / 支票 | 2 天 + 1 天 | 2 天 + 1 天 | 同左 |
"通知天数 + 驳回天数" 含义：超过通知天数仍未匹配到流水 → 系统通知用户确认；再过驳回天数仍无匹配 → 系统自动驳回入金申请。
双方功能对应矩阵
| 功能域 | 渠道侧（工银亚洲） | moomoo 侧 | 状态 |
|---|---|---|---|
| 流水查询 | 银企直联 REST API + RSA2 签名 | icbc_be_relay 定时拉取 | ✅ 已上线 |
| 分页 | next_tag cursor 机制 | icbc_be_next_tag 表记录进度 | ✅ 已上线 |
| 余额 | 每笔交易返回 balance | icbc_balance 表 + 连续性校验 | ✅ 已上线 |
| FPS 入金 | 流水标签 FPS 轉賬 | 精确匹配 → 自动入账 | ✅ 已上线 |
| 网银入金 | 流水标签 網上轉賬存款 | 精确匹配 → 自动入账 | ✅ 已上线 |
| 汇款入金 | 流水标签 匯款存入 | 容差匹配 → 自动入账 | ✅ 已上线 |
| ATM 入金 | ATM 交易流水 | 辅助匹配 → 人工审核 | ⚠️ 不可自动入账 |
| 支票入金 | 支票交易流水 | 辅助匹配 → 人工审核 | ⚠️ 不可自动入账 |
| 出金 | 企业网银手工操作 | method=manual | ✅ 手工模式 |
| eDDA/eDDI | 不支持 | — | ❌ |
| 银证 BST | 不支持 | — | ❌ |
需求变更指引
如果需要修改工银亚洲相关的业务规则，以下是具体的改动位置：
| 变更需求 | 改动位置 | 说明 |
|---|---|---|
| 修改流水拉取频率 | icbc_be_relay cron 配置 | 调整定时任务间隔 |
| 更换 RSA 密钥 | icbc_be_relay/conf/API_GATEWAY.pub | 替换公钥文件，重启服务 |
| 修改日期切换时间 | relay.py → 00:35 判断逻辑 | 调整日终切换阈值 |
| 新增币种查询 | relay.py → biz_content.currency 枚举 | 添加新币种并配置对应收款账号 |
| 修改匹配金额容差 | IcbcasiaMatch.php → localTransferSimilarAmount | 调整 HKD -20 / USD -3 阈值 |
| 修改 FPS 精确匹配规则 | IcbcasiaMatch.php → FPS 分支 | 调整 FPS 容差（当前=0） |
| 修改匹配日期窗口 | IcbcasiaMatch.php → daySimilar | 调整 -3~+2 天参数 |
| 新增可自动入账的流水类型 | IcbcasiaMatch.php → remarks 正则 | 添加新的中文标签匹配规则 |
| 修改卡号处理规则 | IcbcasiaMatch.php → 卡号比较逻辑 | 调整去末位/去前缀策略 |
| 修改匹配频率 | deposit/doc/crontab.sh → match:main icbc-new | 调整 cron 间隔 |
| 修改出金跟进天数 | 出金配置 → manual 方法参数 | 调整 3 天跟进期 |
常见客诉 Top 3
| # | 用户反馈 | 原因 | 客服话术 |
|---|---|---|---|
| 1 | "工银入金没到账" | 银企直联查询超时或流水未采集 | "您的入金正在处理中，请耐心等待匹配" |
| 2 | "入金金额不对" | 工银以"分"为单位，可能存在转换差异 | "系统正在核实金额，如有差异我们会尽快处理" |
| 3 | "为什么不能用工银出金" | 工银仅接入入金，不支持出金 | "工银目前仅支持入金，出金请使用其他银行通道" |
读完之后
| 我想... | 去看 |
|---|---|
| 看工银在各银行中的位置 | 银行能力矩阵 |
| 了解匹配引擎的完整逻辑 | 匹配与自动入账 |
| 查 TransType 和 Bank ID 对照 | 入金规则速查 |
| 看 BST 银行（招行/民生/天星） | 内银系 BST |
| 了解系统架构中流水采集的位置 | 系统架构与数据流 |
这个页面有帮助吗？