深色模式
渣打 SCB
本页说明
讲什么：渣打银行的 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 |
| 查出金通道的执行细节 | 通道执行手册 |
这个页面有帮助吗？