工銀亞洲 ICBC Push 模式
本頁說明
講什麼：工銀亞洲渠道側接口規範 + 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 |
| 了解系統架構中流水採集的位置 | 系統架構與數據流 |