CMBC (Minsheng Bank) MS
About This Page
What: CMBC BST channel-side Protobuf/SRPC protocol specification + moomoo-side adaptation logic Audience: PMs understanding integration details / developers locating code / operations understanding bank characteristics Prerequisites: BST Overview, Bank Capability MatrixReading time: 8 minutes Owner: Deposit & Withdrawal Product Team
Key takeaway: CMBC uses Protobuf/SRPC protocol in Socket mode, sharing the bidirectional link architecture with CMB but with a different serialization approach.
Capability Overview
| Capability | Supported | Protocol/Channel | Core Service |
|---|---|---|---|
| BST Deposit | ✅ | Protobuf/SRPC (SM2 National Crypto) | ms_stock_bank_transaction |
| BST Withdrawal | ✅ | auto_bs automated withdrawal | ms_stock_bank_transaction |
| eDDA Authorization | ❌ | — | — |
| eDDI Direct Debit | ❌ | — | — |
| FPS | ❌ | — | — |
| Deposit Statement Matching | ❌ | — | — |
CMBC is the second BST bank integrated by moomoo — together with CMB, they form the dual BST channel system, but use completely different protocol stacks (Protobuf/SRPC vs binary Socket).
Core Identifiers
| Identifier | Value | Description |
|---|---|---|
| IMPORT_BANK_ID | 13 | CMBC, unique bank ID in the system |
| TransType | 101 (BST), 204 (Standard) | 101 for BST transfers, 204 for standard deposits |
| AUTO_SETTING_ID | 1 | Auto-withdrawal configuration ID |
| Service Name | ms_stock_bank_transaction | Core BST service |
| Code Directory | ms_sb_trans_python/ | Service code root directory |
Channel Interface Overview
| Dimension | Description |
|---|---|
| Protocol Type | Protobuf serialization + SRPC framework |
| Encryption | SM2 National Crypto Algorithm (China's commercial cryptography standard) |
| Data Format | Protobuf binary serialization (not JSON/XML) |
| Communication Mode | RPC request-response (synchronous calls) |
| Encoding | GB18030 (Chinese name fields use bytes type) |
| Signature Algorithm | SM2 National Crypto signature, ensuring data integrity |
Protocol Difference from CMB
CMB uses a custom binary Socket protocol, while CMBC uses Google Protobuf + a proprietary SRPC framework. Both use SM2 encryption, but the serialization differs — CMB uses manual binary encoding, CMBC uses Protobuf auto-serialization. The Protobuf approach is superior in maintainability.
Channel-Side Interface Details — 9 RPC Methods
CMBC provides 9 RPC interfaces, identified by Request ID for different business operations:
| Method Name | Request ID | Request / Response Type | Purpose (Direction) |
|---|---|---|---|
| OpenApproval | 0x01 | OpenApprovalReq / Rsp | Account opening approval (CMBC → moomoo) |
| SyncData | 0x02 | CrmReq / CrmRsp | Sync customer/transaction data (CMBC → moomoo) |
| WithDrawApproval | 0x03 | WithDrawApprovalReq / Rsp | Withdrawal approval (CMBC → moomoo) |
| Reconciliate | 0x04 | ReconciliationReq / Rsp | Daily reconciliation (CMBC → moomoo) |
| ChangePassword | 0x05 | ChangePasswordReq / Rsp | Change transaction password (CMBC → moomoo) |
| WithDrawAck | 0x06 | WithDrawAckReq / Rsp | Withdrawal confirmation — bank confirms receipt (CMBC → moomoo) |
| LoginIn | 0x07 | LoginInReq / Rsp | Teller login (CMBC → moomoo) |
| LoginOut | 0x08 | LoginOutReq / Rsp | Teller logout (CMBC → moomoo) |
| CreateWithdrawFutu | 0x09 | WithdrawFutuReq / Rsp | Create withdrawal — moomoo-initiated (moomoo → CMBC) |
Method Call Flow Summary
- Account Opening Flow: User signs agreement at bank → Bank calls OpenApproval → moomoo approves → Returns result
- Deposit Flow: User initiates at bank → Bank pushes deposit data via SyncData → moomoo processes crediting
- Withdrawal Flow: User initiates on moomoo → CreateWithdrawFutu sends withdrawal request → Bank processes → WithDrawAck confirms
- Reconciliation Flow: Bank initiates daily Reconciliate → Both parties verify transaction data → Discrepancies handled manually
Core Interface Field Details
CrmReq — Data Sync Request
The request body of the SyncData method, serving as CMBC's unified entry point for pushing various business data to moomoo:
| Field | Type | Description | Notes |
|---|---|---|---|
| date | string | Data date | Format YYYYMMDD |
| type | ReqType enum | Request type (10 types) | Determines the data category being pushed |
ReqType Enum — 10 Data Types
| Enum Value | Name | Description | Trigger Timing |
|---|---|---|---|
| 1 | OPEN | Account opening data | User completes BST authorization at bank |
| 2 | OPENRES | Account opening result | moomoo approval result returned to bank |
| 3 | DEPOSIT | Deposit data | User initiates deposit transfer |
| 4 | WITHDRAW | Withdrawal data | Withdrawal request reaches bank |
| 5 | WITHDRAWRES | Withdrawal result | Bank returns result after processing |
| 6 | CLOSE | Account closure data | User terminates BST relationship |
| 7 | OPENRC | Account opening reconciliation | Daily reconciliation — single account opening |
| 8 | BATCHOPENRC | Batch account opening reconciliation | Daily reconciliation — batch account opening |
| 9 | WITHDRAWRC | Withdrawal reconciliation | Daily reconciliation — single withdrawal |
| 10 | BATCHWITHDRAWRC | Batch withdrawal reconciliation | Daily reconciliation — batch withdrawal |
Push vs Polling
Unlike Airstar (REST API polling), CMBC uses a push model — the bank proactively pushes data to moomoo via SyncData. moomoo does not need to poll the bank's interface.
DepositItem — Deposit Data Fields
Each deposit pushed by the bank is represented as a DepositItem:
| Field | Type | Description | Value Range/Format |
|---|---|---|---|
| TraDat | string | Transaction date | YYYYMMDD |
| TraTim | string | Transaction time | HHMMSS |
| RefNo | string | Reference number | Bank-side unique identifier, key for reconciliation |
| SDNo | string | Broker number | Fixed value, identifies moomoo |
| SecAc | string | Securities account | moomoo account (maps to CID) |
| CusAc | string | Customer account | Bank card number |
| Ccy | string | Currency | HKD / USD (CNH not supported) |
| Amt | string | Amount | String format, e.g. "50000.00" |
| AcCkDt | string | Reconciliation date | YYYYMMDD, used during reconciliation |
WithDrawItem — Withdrawal Data Fields
| Field | Type | Description | Value Range/Format |
|---|---|---|---|
| TraDat | string | Transaction date | YYYYMMDD |
| RefNo | string | Reference number | Bank-side unique identifier |
| SDNo | string | Broker number | Fixed value |
| SecAc | string | Securities account | moomoo account |
| CusAc | string | Customer account | Bank card number |
| Ccy | string | Currency | HKD / USD |
| Amt | string | Amount | String format |
| AcCkDt | string | Reconciliation date | YYYYMMDD |
| SucFlg | string | Success flag | Y = success / N = failure |
| TraTime | string | Transaction time | HHMMSS |
OpenApprovalReq — Account Opening Approval Request
Bank pushes account opening approval, moomoo decides whether to approve:
| Field | Required | Type | Description |
|---|---|---|---|
| AgrNo | ✅ | string | Agreement number. Unique identifier for BST authorization agreement |
| SDNo | ✅ | string | Broker number. Fixed value |
| SecAc | ✅ | string | Securities account. Must exist in moomoo system |
| CusAc | ✅ | string | Customer account. Bank card number |
| AprSts | ✅ | string | Approval status. Bank-side pre-review result |
| RejRsn | ❌ | string | Rejection reason. Only has value when approval fails |
| CusEnm | ❌ | string | Customer English name. Used for name verification |
| CusCnm | ❌ | bytes | Customer Chinese name. bytes type (GB18030 encoding) |
CusCnm Uses bytes Type
The Chinese name field CusCnm is bytes rather than string type. This is because Protobuf's string requires UTF-8 encoding, but CMBC transmits Chinese using GB18030 encoding — using string type would cause decoding errors. Special attention to encoding conversion is needed during development.
WithDrawApprovalReq — Withdrawal Approval Request
| Field | Required | Type | Description |
|---|---|---|---|
| OrgRefNo | ✅ | string | Original reference number. Links to original withdrawal request |
| SDNo | ✅ | string | Broker number. Fixed value |
| SecAc | ✅ | string | Securities account. moomoo account |
| CusAc | ✅ | string | Customer account. Bank card number |
| Ccy | ✅ | string | Currency. HKD / USD |
| Amt | ✅ | string | Amount. String format |
| AprSts | ✅ | string | Approval status. Approved / Rejected |
| RejRsn | ❌ | string | Rejection reason. Only filled when rejected |
Key Differences from CMB
CMBC and CMB both belong to the BST system, but have significant protocol and implementation differences:
| Dimension | CMB | CMBC MS |
|---|---|---|
| IMPORT_BANK_ID | 12 | 13 |
| AUTO_SETTING_ID | 2 | 1 |
| Protocol | Custom binary Socket protocol | Protobuf/SRPC framework |
| Serialization | Manual binary encoding/decoding | Protobuf auto-serialization |
| Encryption Algorithm | SM2 National Crypto | SM2 National Crypto |
| CNH Support | HK bank card holders only | Not supported at all |
| Processing Hours | 08:40 ~ 15:59 | 08:40 ~ 15:59 |
| Margin Hours | 08:40 ~ 10:59 | 08:40 ~ 10:59 |
| Error Code System | Socket response codes (0/-5/-6) | Protobuf error enum (2001~2006) |
| Reconciliation Method | Daily file reconciliation | SyncData (type=7~10) push reconciliation |
| Service Name | cmb_stock_trans | ms_stock_bank_transaction |
| Code Language | Python | Python |
| Interface Count | — | 9 RPC methods |
One-sentence summary: CMB uses a "raw" binary protocol (flexible but hard to maintain), CMBC uses a Protobuf standard protocol (well-structured but dependent on proto file synchronization).
CNH Restriction
CMBC does not support CNH (Renminbi) currency at all. This is a hard-coded restriction at the code level:
checkCurrency() → Detects CNH → Directly rejects → Returns error code 2001 (MsBsRejRsn::LOCK_OF_CASH)| Currency | Supported | Description |
|---|---|---|
| HKD | ✅ | Fully supported |
| USD | ✅ | Fully supported |
| CNH | ❌ | checkCurrency() directly rejects |
CNH Deposits Show as "Insufficient Funds"
Since the CNH rejection uses error code 2001 (LOCK_OF_CASH = insufficient funds), users may see an "insufficient funds" error message, but the actual reason is currency not supported. Operations should note this distinction when troubleshooting.
Comparison:
- CMB: CNH limited to HK bank card holders only (conditional support)
- Airstar: Full support for HKD / USD / CNH
- CMBC: CNH completely unsupported
Error Code System
CMBC-Specific Error Codes (MsBsRejRsn Enum)
| Error Code | Enum Name | Meaning | Handling |
|---|---|---|---|
| 2001 | LOCK_OF_CASH | Insufficient funds / Currency not supported. Account balance insufficient, or CNH deposit blocked | Notify user to check balance/currency |
| 2002 | ACCOUNT_ABNORMAL | Account status abnormal. Account frozen, closed, etc. | Contact CMBC to confirm account status |
| 2003 | OTHER_REJECTION | Other rejection reasons. Bank-side risk control interception, etc. | Manual investigation, contact bank for details |
| 2004 | NSS_ISSUE | NSS issue. Network security subsystem error | Technical investigation of network/certificate configuration |
| 2005 | GDCA_ISSUE | GDCA issue. Guangdong Digital Certificate Authority error | KYC/certificate-related investigation |
| 2006 | INVALID_BANKCARD | Invalid bank card. Card number incorrect, cancelled, or inactive | Guide user to re-bind card |
Mapping to Generic BST Error Codes
| CMBC Error Code | Corresponding Generic Status | User-Facing Display |
|---|---|---|
| 2001 | FAILED (deposit failed) | "Insufficient funds, please check your bank account balance" |
| 2002 | FAILED (account abnormal) | "Bank account status abnormal, please contact your bank" |
| 2003 | FAILED (rejected) | "Bank rejected processing, please contact customer service" |
| 2004 | FAILED (system error) | "System error, please try again later" |
| 2005 | FAILED (KYC error) | "Identity verification error, please contact customer service" |
| 2006 | FAILED (invalid card) | "Bank card invalid, please use a different bank card" |
Deposit Flow
CMBC BST Deposit Flow
CMBC deposits are bank-initiated — users initiate BST transfers from CMBC Bank App/counter to their securities account:
Deposit Time Restrictions
| Period | Time Range | Allowed Operations |
|---|---|---|
| Normal Trading Hours | 08:40 ~ 15:59 | Deposit + Withdrawal |
| Margin Deposit Hours | 08:40 ~ 10:59 | Margin-type deposits only |
| Non-Trading Hours | 16:00 ~ next day 08:39 | No deposit/withdrawal requests accepted |
Off-Hours Deposits
Deposit requests initiated by CMBC during non-trading hours will be rejected by the moomoo side. Unlike Airstar (which queues requests until trading hours), CMBC requires users to re-initiate during trading hours.
Withdrawal Flow
Standard Withdrawal Flow
CMBC withdrawals support two modes:
| Mode | Trigger Method | Interface | Description |
|---|---|---|---|
| moomoo-initiated | User clicks withdrawal in moomoo App | CreateWithdrawFutu (0x09) | moomoo proactively calls bank interface |
| Bank-initiated | Bank pushes withdrawal request | WithDrawApproval (0x03) | CMBC pushes, moomoo approves |
moomoo-Initiated Withdrawal Flow
Bank-Initiated Withdrawal Approval Flow
When a user initiates withdrawal from the CMBC bank side:
- Bank sends
WithDrawApproval(0x03) to moomoo - moomoo performs risk control checks (balance, limits, blacklist, etc.)
- Approved: Returns AprSts = Approved → Bank executes transfer
- Rejected: Returns AprSts = Rejected + RejRsn (rejection reason)
auto_bs Automated Withdrawal
CMBC withdrawals use the auto_bs automated withdrawal channel, AUTO_SETTING_ID = 1. Automated withdrawal requires all of the following conditions:
| Condition | Description |
|---|---|
| Account status normal | Not frozen, not closed |
| Not blacklisted | Withdrawal blacklist check passed |
| Single transaction within limit | Amount within limit range |
| Daily circuit breaker not triggered | Daily cumulative hasn't triggered circuit breaker |
| Within trading hours | 08:40 ~ 15:59 |
| Currency supported | HKD or USD (not CNH) |
If any condition is not met, it falls through to manual approval.
Reconciliation Mechanism
Daily Reconciliation Flow
CMBC implements daily reconciliation through 4 reconciliation types in the SyncData interface:
| ReqType | Reconciliation Type | Description |
|---|---|---|
| 7 (OPENRC) | Single account opening reconciliation | Verify account opening records one by one |
| 8 (BATCHOPENRC) | Batch account opening reconciliation | Verify account opening records in batch |
| 9 (WITHDRAWRC) | Single withdrawal reconciliation | Verify withdrawal records one by one |
| 10 (BATCHWITHDRAWRC) | Batch withdrawal reconciliation | Verify withdrawal records in batch |
Reconciliation Discrepancy Handling
| Discrepancy Type | Description | Handling |
|---|---|---|
| Long (moomoo has, bank doesn't) | moomoo has an extra transaction | Verify if bank missed a push, reverse if necessary |
| Short (bank has, moomoo doesn't) | Bank has an extra transaction | Verify if moomoo missed processing, supplement if necessary |
| Amount mismatch | Same transaction with different amounts | Use bank-side as source of truth, adjust moomoo-side record |
| Status mismatch | Same transaction with different statuses | Manual judgment and correction |
Security & Encryption
SM2 National Crypto Algorithm
CMBC uses China's National Commercial Cryptography Standard SM2 Algorithm for communication encryption:
| Dimension | Description |
|---|---|
| Algorithm Type | SM2 Elliptic Curve Public Key Cryptography |
| Key Length | 256 bits |
| Equivalent Security | Approximately RSA-3072 |
| Purpose | Request/response data encryption + Digital signature |
| Compliance Requirement | Chinese mainland banks must use National Crypto algorithms |
Encryption Flow
- Sender: Encrypts Protobuf-serialized binary data with SM2 public key
- Transmission: Encrypted data transmitted via SRPC framework
- Receiver: Decrypts with SM2 private key, then Protobuf deserialization
- Signature Verification: Each request carries an SM2 digital signature, receiver verifies to ensure data integrity
Exception Scenarios
Deposit Exceptions (4 Types)
| # | Exception | Symptom | Cause & Handling |
|---|---|---|---|
| 1 | Deposit rejected (2001) | Bank returns LOCK_OF_CASH | CNH currency blocked / Insufficient balance. Confirm currency; if CNH, inform user it's not supported |
| 2 | Account abnormal (2002) | Bank returns ACCOUNT_ABNORMAL | Bank card frozen/closed. Contact CMBC to confirm status |
| 3 | SyncData not received | moomoo didn't receive deposit push | Network interruption/SRPC communication error. Check network connectivity, review SRPC logs |
| 4 | Data decryption failed | Protobuf deserialization error | SM2 key mismatch/data corruption. Check key configuration, contact bank technical team |
Withdrawal Exceptions (5 Types)
| # | Exception | Symptom | Cause & Handling |
|---|---|---|---|
| 1 | CreateWithdrawFutu failed | Withdrawal request rejected by bank | Parameter error/bank-side risk control. Check request parameters and error codes |
| 2 | WithDrawAck not received | No confirmation for a long time after withdrawal | Bank processing delay/communication interruption. Manually query bank-side status |
| 3 | Freeze not released | Funds still frozen after withdrawal failure | Release flow error. Manually release freeze |
| 4 | Approval timeout | No response to WithDrawApproval | moomoo approval service error. Check approval service logs |
| 5 | Duplicate withdrawal | Same withdrawal executed multiple times | RefNo deduplication failed. Investigate duplicates via OrgRefNo |
Reconciliation Exceptions (3 Types)
| # | Exception | Symptom | Cause & Handling |
|---|---|---|---|
| 1 | Reconciliation data missing | No reconciliation received for a day | Reconciliate call failed. Manually trigger reconciliation |
| 2 | Long/Short discrepancy | Records inconsistent between parties | Network packet loss/processing timing difference. Manual verification and adjustment |
| 3 | Batch reconciliation timeout | BATCHOPENRC/BATCHWITHDRAWRC processing slow | Data volume too large. Process in batches or scale up |
Teller System
CMBC has an independent teller login/logout mechanism managed through LoginIn/LoginOut interfaces:
| Interface | Request ID | Purpose | Description |
|---|---|---|---|
| LoginIn | 0x07 | Teller login | Bank teller logs in before operations |
| LoginOut | 0x08 | Teller logout | Bank teller logs out after operations |
Business Significance of Teller System
Some CMBC operations (such as account opening approval, withdrawal approval) require bank teller participation. Tellers must be logged in to perform approval operations, and the system logs operations after logout. This is a traditional banking system-specific flow; virtual banks like Airstar don't need this mechanism.
Password Management
The ChangePassword (0x05) interface is used for changing BST transaction passwords:
| Dimension | Description |
|---|---|
| Trigger Scenario | User requests password change at bank side |
| Impact Scope | All BST operations require the new password after change |
| Security Requirement | Password is SM2-encrypted in transit, moomoo side does not store plaintext |
Code Location & Service Deployment
| Dimension | Description |
|---|---|
| Service Name | ms_stock_bank_transaction |
| Code Directory | ms_sb_trans_python/ |
| Language | Python |
| Proto File | CMBC-provided .proto definition file |
| Dependencies | SM2 National Crypto library, Protobuf runtime, SRPC framework |
Key Code Modules
| Module | Responsibility |
|---|---|
ms_sb_trans_python/handler/ | Request handlers for 9 RPC methods |
ms_sb_trans_python/crypto/ | SM2 encryption/decryption and signature verification |
ms_sb_trans_python/proto/ | Protobuf-generated message classes |
ms_sb_trans_python/service/ | Business logic (crediting, withdrawal, reconciliation) |
ms_sb_trans_python/config/ | Bank connection configuration, key configuration |
Change Guide
| Change Requirement | Modification Location | Description |
|---|---|---|
| Add CNH support | checkCurrency() + bank-side negotiation | Bank side must also support CNH, modify currency validation logic |
| Modify error code mapping | handler/ error handling | Adjust MsBsRejRsn to user prompt mapping |
| Modify processing hours | Time period validation logic | Synchronize front-end and back-end time period checks |
| Add new RPC method | Bank provides new proto → generate code → implement handler | Bank side must publish proto file first |
| Replace SM2 keys | config/ key configuration | Coordinate key rotation time window with bank |
| Modify reconciliation rules | service/reconciliation.py | Adjust discrepancy judgment thresholds or handling strategies |
| Modify auto-withdrawal conditions | auto_bs config + AUTO_SETTING_ID | Refer to Withdrawal Rules Manual |
| Adjust limits | Limit configuration (SQL seed) | Modify per-transaction max/alarm/circuit breaker thresholds |
Common Customer Complaints Top 3
| # | User Feedback | Cause | CS Script |
|---|---|---|---|
| 1 | "BST withdrawal timeout" | Socket connection jitter, callback code -5 | "Your withdrawal is being processed, the system has automatically retried, please check the result shortly" |
| 2 | "Why doesn't CMBC support CNH" | CMBC BST doesn't support offshore RMB | "CMBC currently supports HKD and USD for deposits and withdrawals, RMB is not available at this time" |
| 3 | "Withdrawal rejected by bank" | Callback code -6 or insufficient balance | "Please confirm your account has sufficient balance; if still rejected, please contact customer service" |
Monitoring & Alerts
Key Monitoring Items
| # | Monitor Item | Trigger Condition | Handling |
|---|---|---|---|
| 1 | SRPC connection interrupted (Critical) | SRPC connection to CMBC disconnected | Check network, auto-reconnect |
| 2 | SM2 decryption failed (High) | Received data cannot be decrypted | Check if key configuration is consistent |
| 3 | Deposit failure rate spike (High) | Failure count exceeds threshold in time window | Investigate specific error code distribution |
| 4 | Withdrawal confirmation timeout (High) | No WithDrawAck after CreateWithdrawFutu | Manually query bank-side status |
| 5 | Reconciliation discrepancy (Medium) | Daily reconciliation finds long/short | Operations verification and handling |
| 6 | Abnormal teller login (Medium) | LoginIn frequency abnormal or during non-working hours | Security team investigation |
After Reading
| I want to... | Go to |
|---|---|
| See the overall comparison of 3 BST banks | BST Overview |
| Understand CMB's binary Socket protocol | CMB |
| See Airstar's REST API approach | Airstar |
| Look up BST error codes | Unified Error Code Center |
| See auto-withdrawal approval conditions | Withdrawal Rules Manual |
| See capability comparison of all banks | Bank Capability Matrix |
Was this page helpful?