渣打 SCB Push 模式 Direct 模式
本頁說明
講什麼：渣打銀行的 FPS 出金通道、Book Transfer（加密資產轉賬）、Webhook 事件機制 適合誰：需要了解渣打對接細節的產品經理 前置閱讀：銀行能力矩陣預計閱讀：2 分鐘 負責人：出金產品經理
核心要點：渣打的核心能力是 FPS 出金 API + Webhook 事件推送，是出金半自動化的代表性通道——無需運營登錄網銀操作。
能力總覽
| 能力 | 支持情況 | 協議/通道 | 核心服務 |
|---|---|---|---|
| 入金流水 | ❌ | — | — |
| 出金 FPS | ✅ | REST API + Webhook | scb_service (Go) |
| Book Transfer | ✅ | REST API | scb_service (Go) |
| 子賬戶 | ✅ | — | 子賬戶入金匹配 |
| eDDA/eDDI | ❌ | — | — |
| 銀證 BST | ❌ | — | — |
渣打是出金專用銀行——不採集入金流水，主要提供 FPS 出金和 Book Transfer 兩個通道。
出金：FPS
出金方法
| 維度 | 說明 |
|---|---|
| 方法碼 | TRANSFER_METHOD_SC = 'sc' |
| 分類 | 電子銀行方法（allEBankMethod） |
| 中文名 | 渣打網銀出金 |
數據流
Webhook 事件
渣打通過 Webhook 異步回調通知交易狀態變更，不需要輪詢：
| Webhook 類型 | 含義 | 觸發場景 |
|---|---|---|
payment_status | 支付狀態變更 | 出金指令處理結果 |
credit_debit_advice | 借記/貸記通知 | 資金到賬/扣款確認 |
Webhook 處理狀態：
| 狀態碼 | 含義 |
|---|---|
| 0 | 新建（待處理） |
| 1 | 處理中 |
| 2 | 已處理 |
FPS 出金流水查詢
系統可通過 API 查詢流水記錄：
- 支持分頁（cursor-based，默認每頁 20 條）
- 返回字段：TransactionID、BankStatementID、ValueTime、ValueDate、金額、幣種
- 包含 Payer/Payee 信息：收款卡號、付款行名、SWIFT 代碼
Book Transfer（加密資產轉賬）
Book Transfer 是渣打的內部賬戶間轉賬能力，用於特定場景下的資金調撥：
| 維度 | 說明 |
|---|---|
| 用途 | 子賬戶間資金轉移 |
| 請求參數 | RequestID、Amount、Debtor（付款方）、Creditor（收款方） |
| 金額校驗 | 必須 ≥ 0 |
| ID 生成 | Snowflake 算法生成 ReferenceID |
| 隊列事件 | QueueEventTransferCreate |
子賬戶入金
雖然渣打沒有獨立的入金流水採集服務，但支持子賬戶入金匹配。用戶通過渣打子賬戶轉入資金，系統通過 SubAccountSDK 驗證子賬戶歸屬後自動匹配。
渠道接口詳情
渠道接口概覽
| 維度 | 說明 |
|---|---|
| 協議類型 | HTTPS REST + JSON |
| 認證方式 | TLS 雙向認證 + JWT Token（30 秒有效期） |
| 加密方式 | AES256Signed（響應加密） |
| 簽名算法 | RS256（RSA） |
| 核心服務 | scb_service（Go） |
HTTP Headers（所有請求必需）
每個發往渣打 API 的請求都必須攜帶以下 Headers：
| Header | 值 | 說明 |
|---|---|---|
Content-Type | Application/JSON | 請求體格式 |
ResponseEncryptionType | AES256Signed | 響應加密方式 |
Routing-Identifier | ZZ | 路由標識 |
GroupId | GHK54005 | 集團 ID |
Authorization | Bearer [JWT_TOKEN] | JWT 令牌（30 秒有效期） |
注意：messageSender 和 countryCode 是請求體 JSON 中的字段（見下方 PaymentInitRequest），不是 HTTP Header。
證書配置
渣打使用 TLS 雙向認證 + RS256 簽名的 JWT Token，涉及多組密鑰：
| 證書 | 路徑 | 用途 |
|---|---|---|
| 客戶端證書 | conf/keys/client.cer | TLS 雙向認證 |
| 客戶端私鑰 | conf/keys/clientcertsslprivatekey.pem | 簽名 / 解密 |
| 客戶端公鑰 | conf/keys/clientpubkey.pem | 銀行驗證我方身份 |
| JWT 簽名密鑰 | conf/keys/scbapibankingprivatekey.pem | JWT RS256 簽名 |
JWT Token 參數：
| 參數 | 值 |
|---|---|
| Issuer | "SCB" |
| Audience | "SCB-APIBanking" |
| 有效期 | 30 秒 |
JWT 有效期極短
JWT Token 僅 30 秒有效，系統每次請求前需重新生成。如果時鐘偏差超過數秒可能導致認證失敗，需確保伺服器 NTP 同步。
接口 1：Payment Initialization（出金發起）
POST /openapi/payments/v2/initiate
請求 PaymentInitRequest：
| 字段 | 類型 | 必填 | 描述 |
|---|---|---|---|
header.messageSender | string(≤246) | ✅ | 發送方 |
header.messageId | string(≤35) | ✅ | 消息 ID，唯一標識 |
header.countryCode | string(2) | ✅ | 國家代碼。取值 "HK" |
header.timestamp | int64 | ✅ | Unix 時間戳 |
instruction.paymentTimestamp | int64 | ✅ | 支付時間戳 |
instruction.requiredExecutionDate | string(≤10) | ✅ | 執行日期。格式 "YYYY-MM-DD" |
instruction.amount.currencyCode | string(3) | ✅ | 幣種。取值 "HKD" / "USD" |
instruction.amount.amount | string | ✅ | 金額。如 "1000.00" |
instruction.referenceID | string(≤16) | ✅ | 參考號 |
instruction.purpose | string(≤10) | ❌ | 用途 |
instruction.paymentType | string(≤4) | ❌ | 支付類型 |
instruction.chargerBearer | string(≤4) | ❌ | 手續費承擔方 |
instruction.debtor.name | string(≤140) | ✅ | 付款方名稱 |
instruction.debtorAccount.id | string(≤34) | ✅ | 付款方賬號 |
instruction.debtorAccount.identifierType | string | ✅ | 賬號類型。取值 "BBAN" / "IBAN" / "Other" |
instruction.creditor.name | string(≤140) | ✅ | 收款方名稱 |
instruction.creditorAccount.id | string(≤34) | ✅ | 收款方賬號 |
instruction.creditorAgent.financialInstitution.BIC | string(≤11) | ❌ | 收款行 BIC。如 "SCBLHKHHXXX" |
instruction.remittanceInfo.multiUnstructured | array[string] | ❌ | 匯款附言信息 |
響應 PaymentInitResponse：
| 字段 | 類型 | 描述 |
|---|---|---|
paymentIdentifier | string | 渣打支付標識 |
internalTrackingId | string(≤35) | 內部追蹤 ID |
clientReferenceId | string(≤35) | 客戶參考 ID |
referenceId | string(≤35) | 參考號 |
statusString | string(≤10) | 狀態 |
timestamp | ISO-8601(≤24) | 時間戳 |
接口 2：Payment Status Query（出金狀態查詢）
POST /openapi/payments/v2/status
請求：
json
{
"clientReferenceIds": ["ref1", "ref2", "..."]
}支持批量查詢多筆出金狀態。
響應（每條記錄）：
| 字段 | 類型 | 描述 |
|---|---|---|
statusString | string | 狀態描述 |
statusCode | string | ISO 20022 狀態碼 |
reasonCode | string | 原因碼 |
valueDate | YYYY-MM-DD | 值日期 |
debitDate | YYYY-MM-DD | 扣款日期 |
debitAmount | string | 扣款金額 |
調度規則：系統每 30 秒輪詢一次未完成的出金狀態。
接口 3：Webhook Credit/Debit Advice（入金通知）
POST /credit-debit-advice
渣打通過 Webhook 主動推送貸方/借方通知，Payload 完整字段如下：
| 字段 | 類型 | 描述 |
|---|---|---|
groupId | string | 組 ID |
accountIdentifier.accountId | string | 賬號 |
accountIdentifier.currencyCode.isoCode | string | 幣種 |
eventDate | YYYY-MM-DD | 事件日期 |
adviceType | string | "CRDT"=貸方（入金）/ "DBIT"=借方（扣款） |
valueDate | YYYY-MM-DD | 值日期 |
transactionAmount.currencyCode | string | 交易幣種 |
transactionAmount.amount | decimal | 交易金額 |
transactionFreeText | array[string] | 交易說明（自由文本） |
payerDetails.name | string | 付款人姓名 |
payerDetails.account.id | string | 付款人賬號 |
timestamp | ISO-8601 | 時間戳 |
配置的收款賬戶
| 幣種 | 賬號 | BIC | 用途 |
|---|---|---|---|
| HKD | 44700993333 | SCBLHKHHXXX | 證券 |
| HKD | 91701015121 | SCBLHKHHXXX | 加密 / Hash Key |
| HKD | 91701015121 | SCBLHKHHXXX | PantherTrade |
| USD | 44700993333 | SCBLHKHHXXX | 證券 |
| USD | 91701015121 | SCBLHKHHXXX | 加密 / Hash Key |
| USD | 91701015121 | SCBLHKHHXXX | PantherTrade |
moomoo 側適配
Webhook → BankFlow 映射：收到渣打 Webhook 後，系統將 Webhook Payload 轉換為內部 BankFlow 記錄：
| Webhook 字段 | BankFlow 字段 | 說明 |
|---|---|---|
transactionAmount.amount | amount | 金額 |
transactionAmount.currencyCode | currency | 幣種 |
payerDetails.name | payer_name | 付款人姓名 |
payerDetails.account.id | payer_account | 付款人賬號 |
adviceType | direction | CRDT→入金, DBIT→出金 |
eventDate | transaction_date | 交易日期 |
狀態碼映射（ISO 20022 → 內部狀態）：
| ISO 20022 狀態碼 | 含義 | 內部狀態 |
|---|---|---|
ACCC | Accepted Settlement Completed | 成功 |
RJCT | Rejected | 失敗 |
CANC | Cancelled | 已取消 |
ACSP | Accepted Settlement in Process | 處理中 |
ACCP | Accepted Customer Profile | 已接受 |
需求變更指引
| 變更需求 | 改動位置 | 說明 |
|---|---|---|
| 新增 Webhook 事件類型 | scb_service → webhook handler | 添加新事件處理邏輯 |
| 修改 FPS 出金參數 | scb_service → 出金請求構建 | 調整 API 請求字段 |
| Book Transfer 新增校驗 | scb_service → book_transfer.go | 修改金額/賬戶校驗規則 |
| 修改子賬戶匹配規則 | SubAccountSDK 配置 | 調整子賬戶歸屬驗證 |
| 修改出金審批模板 | Task.php → $stepTemplates | 調整渣打出金審批流程 |
常見客訴 Top 3
| # | 用戶反饋 | 原因 | 客服話術 |
|---|---|---|---|
| 1 | "FPS 出金沒到銀行卡" | Webhook 推送延遲或出金仍在處理中 | "FPS 出金通常幾分鐘內到賬，如超過 30 分鐘請聯繫客服" |
| 2 | "FPS 出金被退回" | 收款信息有誤 | "轉賬已被銀行退回，請核對收款銀行卡信息後重新發起" |
| 3 | "出金狀態一直顯示處理中" | 渣打 Webhook 未收到 | "您的出金正在處理中，我們正在確認銀行狀態，請稍候" |
監控與告警
| 告警項 | 觸發條件 | 嚴重度 | 處理步驟 |
|---|---|---|---|
| Webhook 接收失敗 | 渣打推送通知未收到 | 🔴 高 | 檢查 Webhook endpoint 可用性，主動調 status 接口查詢 |
| JWT Token 過期 | 認證失敗（30 秒有效期） | 🟡 中 | 檢查伺服器 NTP 時鐘同步，確保偏差 < 5 秒 |
| FPS 支付長時間 PENDING | 出金超過 30 分鐘未到終態 | 🟡 中 | 主動調用 Payment Status 接口查詢，確認銀行側狀態 |
讀完之後
| 我想... | 去看 |
|---|---|
| 看渣打在各銀行中的位置 | 銀行能力矩陣 |
| 了解渣打出金的完整審批流程 | 出金生命週期 |
| 對比另一家 FPS 出金銀行 | 廣發 CGB |
| 查出金通道的執行細節 | 通道執行手冊 |
這個頁面有幫助嗎？