Skip to content

Bank Card & Authorization

About This Page

What: Bank card lifecycle (statuses & verification), data model core fields, currency & account type bitmaps, card-channel capability matrix, card binding/unbinding rules & system flows, BST authorization model (CMB/Minsheng vs Airstar Mandate), eDDA authorization flow & extension fields, online account opening 3-in-1 flow, bank card API overview, and common exception scenarios with troubleshooting guide Audience: Product managers and Operations staff who need to understand bank card management business rules Prerequisites: Getting Started GuideReading time: 12 minutes Owner: Deposit Product Manager


Bank Card Lifecycle

Card Status

Status CodeNameMeaningTypical ScenarioOperations Notes
0Pending ApprovalCard added but not yet active; cannot be used for deposits or withdrawalsCard added during online account opening, awaiting first deposit verificationIf stuck for >24 hours, check whether the user completed the first deposit
1ActiveCard is functioning normallySuccessful standard card binding; or activated after completing first deposit during online account openingNormal state; usable for all deposit and withdrawal operations
2DeletedCard deactivated/deleted, irreversibleUser unbinds or Operations deletesTerminal state. User must re-bind the card; BST/eDDA authorizations are voided simultaneously

Card Verification

Verification confirms the identity of the bank card holder — it is independent of "status." An active card can be unverified.

Verification CodeMeaningTrigger ScenarioImpact on Deposits/Withdrawals
0UnverifiedDefault stateDeposits unaffected; first withdrawal to this card will be blocked
1Verification in ProgressCredentials submitted, awaiting reviewDeposits unaffected; withdrawal waits for verification to complete
2VerifiedVerification passedNo restrictions

Verification Sources & Trigger Conditions:

SourceCodeTrigger ScenarioVerification MethodUser Action Required?
HK Online Account Opening Deposithk_onlineUser deposits via online account openingAuto-verified upon successful depositNo (automatic)
First WithdrawalwithdrawUser's first withdrawal to this cardMust upload bank statement/transfer screenshotYes
BST BindingbstBST Authorization/Mandate completedIdentity verified by bank; auto-verifiedNo (automatic)
eDDA BindingeddaeDDA authorization completedIdentity verified by bank; auto-verifiedNo (automatic)
Manual VerificationmanualOperations approves manually in CRMOperations reviews credentials and marks verifiedNo (Operations action)

Verification Flow (First Withdrawal Scenario)

The first withdrawal to an unverified card is the most common verification trigger:

Lifecycle State Transitions

"Pending Approval" cards from online account opening: Created via the CheckSave API (operation=1 account opening in progress / operation=0 deposit in progress). Only after the first deposit succeeds does the system call TakeEffect to transition the card from Pending Approval to Active.

Storage Location & Database Tables

Bank card data is stored in the web_account database, managed by bankcard_service/ (PHP, port 20005).

TableContentsKey FieldsNotes
bank_cardBank card master recordsid, uid, number, status, verify, account_typeOne row = one bank card
bank_card_operation_logOperation logscard_id, operation, operator, created_atEvery bind/unbind/status change is logged; cannot be deleted
bank_card_certificateVerification credentialscard_id, file_url, statusBank statements/transfer screenshots uploaded by users
bank_infoPreset bank informationid, bank_name, bank_code, swift_codeBank name/code/SWIFT/logo etc. (read-only)
bank_card_asb_bstAirstar BST extensioncard_id, mandate_id, statusAirstar Mandate authorization information
bank_card_eddaeDDA extension (Hang Seng)card_id, limit_amount, statusHang Seng eDDA authorization information
bank_card_hsbc_eddaeDDA extension (HSBC)card_id, mandate_identification, statusHSBC eDDA authorization information

Operations troubleshooting tip: When investigating deposit/withdrawal issues, first check the card's status and verification (verify) in the bank_card table, then look up the corresponding extension table based on the channel type.


Bank Card Data Model

Core Fields

FieldBusiness MeaningExampleCommon Operations Use
idCard unique ID12345Primary key for CRM bank card queries
uidUser ID (moomoo ID)800001234Links to the user
numberBank account number012-345-678-901Match bank statements, verify card numbers
bank_idPreset bank ID (0 = custom bank)23bank_id > 0 uses preset info; = 0 requires manual entry
bank_codeInternal bank codeCMBHKInternal routing for deposit/withdrawal channels
bank_swiftSWIFT code (required for HK cards)CMBCHKHHRequired for international transfers
areaCard regionhk / cn / us / otherDifferent regions have different required fields
currency_typeCurrency bitmap (see below)7Determines which currencies the card supports for deposits/withdrawals
account_typeAccount type bitmap (see below)2Determines which deposit/withdrawal channels the card supports
statusCard status: 0/1/210=Pending Approval, 1=Active, 2=Deleted
verifyVerification status: 0/1/220=Unverified, 1=Verification in Progress, 2=Verified
third_party_flagThird-party card flag00=Own card, 1=Third-party card (additional withdrawal restrictions)
address_statusAddress status00=Normal, 1=Abnormal (may affect withdrawals)

Required Fields by Region

Regionarea ValueRequired FieldsOptional FieldsTypical Banks
Hong Konghkbank_swift, bank_namebank_addressHSBC, Hang Seng, BOC, CMB(HK), Minsheng
Mainland Chinacnopening_address (branch address)bank_province, bank_cityCMB, ICBC, CCB
United Statesusrouting_numberbank_addressBank of America, Chase
Otherotherbank_namebank_swift, bank_addressSingapore, UK, and other overseas banks

Currency Bitmap (currency_type)

The system uses a bitmap to represent which currencies a card supports — each bit represents one currency:

BitValueCurrencyDescription
01HKD (Hong Kong Dollar)HK stock trading, HKD deposits/withdrawals
12USD (US Dollar)US stock trading, USD deposits/withdrawals
24CNH (Offshore RMB)A-share connect trading, RMB deposits/withdrawals

Combination examples:

currency_typeBinarySupported CurrenciesCommon For
1001HKD onlySingle-currency HKD cards
3011HKD + USDDual-currency cards
7111HKD + USD + CNHMost common — majority of Hong Kong bank cards

Operations tip: If a user reports "cannot deposit/withdraw in a certain currency," first check whether the bank card's currency_type includes the corresponding currency bit. For example, currency_type = 3 does not support CNH deposits/withdrawals.

Account Type Bitmap (account_type)

Also uses a bitmap to represent which transfer capabilities the card supports:

BitValueTypeMeaningHow to Obtain
01RegularStandard bank card; supports manual transfer methods such as online banking/FPSAutomatically assigned at card binding
12BSTBST channel bound (CMB/Minsheng/Airstar)Automatically added by the system after BST Authorization is completed
24eDDADirect Debit (eDDA) authorized (Hang Seng/HSBC)Automatically added by the system after eDDA authorization is completed

Combination examples:

account_typeBinaryMeaningAvailable Channels
1001Regular onlyOnline banking deposit, online banking/FPS withdrawal
3011Regular + BSTAbove + BST deposit/withdrawal
5101Regular + eDDAAbove + Direct Debit (eDDA) deposit
7111Full capabilityAll deposit/withdrawal channels

Account Type Is Set Automatically

account_type is not user-selected — it is set automatically by the binding/authorization flow. When a user completes BST Authorization, the card's account_type automatically gains the BST bit (|= 2); when eDDA authorization is completed, it gains the eDDA bit (|= 4). When unbound, the corresponding bit is cleared (&= ~2 or &= ~4).

Operations quick reference (no bitwise math needed):

  • Values containing the BST bit: 2, 3, 6, 7 → BST channel available
  • Values containing the eDDA bit: 4, 5, 6, 7 → Direct Debit (eDDA) available
  • Regular only (no BST): 1, 5 → No BST channel
  • Regular only (no eDDA): 1, 2, 3 → No Direct Debit (eDDA)

Operations troubleshooting: When a user reports "BST/eDDA deposit option not visible," check whether the account_type value is in the lists above.

Transfer Methods (methods)

Each card carries a list of transfer methods indicating available deposit/withdrawal channels:

method ValueTypeMeaningCorresponding BankCorresponding account_type Bit
normalRegularStandard transfer (online banking/FPS/ATM, etc.)All banksbit 0 (Regular)
bst_cmbhkBSTCMB BSTChina Merchants Bank (Hong Kong)bit 1 (BST)
bst_cmbchkBSTMinsheng BSTMinsheng Bankbit 1 (BST)
bst_asbBSTAirstar BSTAirstar Bankbit 1 (BST)
edda_haseeDDAHang Seng Direct Debit (eDDA)Hang Seng Bankbit 2 (eDDA)
edda_hsbceDDAHSBC Direct Debit (eDDA)HSBCbit 2 (eDDA)

Card-Channel Capability Matrix

The bank card's account_type determines which deposit/withdrawal channels are available:

Account TypeOnline Banking DepositBST DepositeDDA DepositBST WithdrawalOnline Banking WithdrawalFPS Withdrawal
Regular (1)
BST (2)
eDDA (4)
BST + eDDA (6)

Channel Filtering Logic

Users can bind multiple cards of different types. When initiating a deposit or withdrawal, the system filters available deposit methods or withdrawal channels based on the selected card's account_type and methods list.

App display rules:

  • User selects a Regular card → App only shows "Online Banking Deposit"; BST/eDDA options are hidden
  • User selects a BST card → App shows both "Online Banking Deposit" and "BST Deposit" options
  • User selects an eDDA card → App shows both "Online Banking Deposit" and "eDDA Deposit" options

Withdrawal display rules follow the same logic: the card's account_type determines which withdrawal channel buttons are shown.


Card Binding / Unbinding Rules

Binding Rules

RuleDescriptionBehavior When Violated
HK cards must have SWIFTbank_swift is required when binding a Hong Kong bank card (except "Other Bank")Card binding API returns a parameter validation error
Mainland cards must have branch addressopening_address is required when area = cnSame as above
US cards must have routing numberrouting_number is required when area = usSame as above
Card number uniquenessThe same uid + number combination cannot be bound twicePrompt: "This card is already bound"
Preset banks take priorityWhen bank_id > 0, preset bank information (name/code/SWIFT) is used; when bank_id = 0, manual entry is requiredCustom banks require users to confirm information accuracy themselves
Online account opening cardsCreated via CheckSave, status = 0 (Pending Approval); transitions to status = 1 after first deposit succeedsCannot be used for deposits/withdrawals while pending
Deleted cards can be re-boundFor the same uid + number, if the old card has status=2, a new binding record can be createdThe new card is a fresh record (new id); BST/eDDA authorizations from the old card are not inherited

Card Binding System Flow

Unbinding Rules

ScenarioStepsPrerequisitesOperations Notes
Regular card unbindingSet status = 2No in-progress deposits/withdrawalsConfirm no pending Procedures
BST card unbinding1. Cancel BST Authorization (CancelBst) → 2. account_type &= ~2 → 3. Set status = 2CMB/Minsheng require bank-side authorization cancellation; Airstar requires Mandate cancellationBST Authorization voided; BST channel becomes unavailable. Complete any outstanding withdrawals first
eDDA card unbinding1. Cancel eDDA authorization → 2. account_type &= ~4 → 3. Set status = 2Hang Seng/HSBC eDDA authorization must be invalidated firstDirect Debit (eDDA) channel becomes unavailable
BST + eDDA card unbindingCancel both authorizations separately as above, then delete the cardBoth authorizations must be invalidated firstAll channel authorizations voided

Unbinding Is Irreversible

status = 2 is a terminal state — deleted cards cannot be recovered; the user must re-bind the card. Unbinding BST/eDDA means the corresponding BST Authorization or Direct Debit authorization is also voided.

Common user question: "I accidentally unbound my bank card — what do I do?" — The only option is to re-bind the card. For BST cards, the user also needs to go through the BST Authorization flow again. For eDDA cards, the user needs to complete eDDA authorization again.

Operations note: Before unbinding, always check whether the card has any in-progress deposit/withdrawal Procedures. When there is an in-progress withdrawal (especially in pending(transfer_manual) status), do not unbind — wait for the withdrawal to complete before proceeding.


BST Authorization & Bank Cards

In the BST channel, bank card management and BST authorization (Mandate) are tightly coupled — a user cannot bind a card without authorization, nor authorize without binding a card.

Authorization Model Differences

DimensionCMB / MinshengAirstar
Core IdentifierBank card numbermandate_id
Binding FlowBank-side BST Authorization completed → notifies moomoomoomoo initiates Mandate authorization → bank confirms
Authorization InitiatorBank-side onlymoomoo can initiate
Unbinding ImpactCanceling authorization = BST unavailableCanceling Mandate = BST unavailable
Multi-marketEach market requires separate authorization (HK/US/HKCC)Single authorization auto-maps to 3 markets (HK/US/HKCC)
CommunicationSM2 Socket bidirectional link (real-time push)REST API (requires polling for results)
Authorization States2 states (Active/Inactive)6 states (including WAITING, FAIL, CANCEL)
Auto-verificationSuccessful authorization → card auto-verified (verify=2)Successful authorization → card auto-verified (verify=2)

CMB/Minsheng BST Authorization Flow

CMB and Minsheng BST Authorization is initiated on the bank side; moomoo passively receives it:

CMB vs Minsheng differences:

DimensionCMBMinsheng
Service namecmb_stock_transms_stock_bank_transaction
Market granularityEach market authorized separately (HK/US/HKCC each require individual setup)Each market authorized separately
Withdrawal payeeChinese nameEnglish name (payee_name must be in English)
Transaction reference fieldbank_tx_seqOrgRefNo
Error recoverysync_bst_data_helper compensationAuto-reconnect + re-pull

Airstar Mandate Deep Dive

Airstar uses mandate_id rather than the bank card number as the core identifier for the BST relationship. This means:

  • Deposits: Linked to the corresponding bank card and user via mandate_id
  • Withdrawals: Authorization validity is confirmed via mandate_id before sending withdrawal instructions
  • Queries: All BST-related status queries use mandate_id as the primary key

3-market auto-mapping: After a user completes a single Mandate authorization, the system automatically creates BST bindings for HK (Hong Kong stocks), US (US stocks), and HKCC (Stock Connect) markets. When the user trades HK stocks, US stocks, or A-shares on moomoo, deposits and withdrawals all go through the same BST channel.

Airstar Authorization Flow (User Perspective)

StepUser ActionUser ExperienceExpected Duration
1Select Airstar bank deposit in moomooBST deposit option displayed
2Tap "Authorize"Redirected to Airstar authorization page
3Confirm authorization on Airstar pageEnter bank password/verification code1–2 minutes
4Authorization complete, return to moomoo"Authorization Successful" displayedSeconds
5Ready to deposit/withdrawBST channel available

Airstar Authorization Flow (System Perspective)

Airstar BST Card Extension Fields (BankCardAsbBst)
FieldMeaningOperations Use
account_nameCustomer nameVerify cardholder identity
account_numberCustomer bank account numberVerify bank account number
mandate_idBST authorization IDCore identifier — primary key for querying BST status and troubleshooting
statusAuthorization status (see table below)Determine whether BST channel is available
reject_codeAuthorization rejection codeInvestigate authorization failure reasons
created_atAuthorization creation timeConfirm authorization timeline
updated_atLast updated timeConfirm status change time

Mandate Status Codes:

Status CodeMeaningCan Deposit/Withdraw?Operations Notes
0Unauthorized (CLOSE)NoInitial state or canceled. User must re-initiate authorization
1Processing (PROCESSING)NoAwaiting bank confirmation; typically completes in seconds to minutes. If still PROCESSING after 5 minutes → check airstar_service logs
2Authorized (OPEN)YesNormal state; BST channel available
3Waiting (WAITING)NoOnline account opening only — awaiting first deposit. Automatically transitions to OPEN(2) upon successful deposit
4Authorization Failed (FAIL)NoCheck reject_code for failure reason. Common causes: bank-side Risk Control block, user information mismatch
5Authorization Canceled (CANCEL)NoUser or Operations canceled. User can re-initiate authorization

Only status=2 (OPEN) allows deposits/withdrawals — this is the first step when Operations investigates "BST not working."

For the detailed Mandate state machine → Internal BST Overview § BST Authorization


eDDA Authorization & Bank Cards

For the deposit-focused view of eDDA authorization (how authorization enables Direct Debit deposits) → Card Binding & Deposit Authorization § eDDA

eDDA Authorization Flow

The eDDA authorization flows for Hang Seng and HSBC are similar with minor differences:

eDDA Card Extension Fields

Hang Seng and HSBC eDDA authorization information is bound to the bank card:

FieldMeaningHang SengHSBCOperations Use
limit_amountPer-transaction/period limit capYesYesCheck whether limit was exceeded when a user reports "Direct Debit failed"
limit_periodicityLimit periodYesYesY=Year / H=Half-year / Q=Quarter / M=Month / P=Per-transaction
expiry_dateExpiration dateYesYes9999999=Permanent; check for expiration
statusEnabled status0=Disabled / 2=Enabled0=Disabled / 1=Authorizing / 2=Enabledstatus=2 required for Direct Debit
mandate_identificationBank-side unique identifierN/AYesUsed when cross-referencing with HSBC

Hang Seng vs HSBC eDDA differences:

DimensionHang SengHSBC
Service namesba_hase_eddisba_hsbc_eddi
Authorization confirmationSynchronous (seconds)Asynchronous SFTP report (T+0 to T+1)
Status values2 states (0/2)3 states (0/1/2 — includes "Authorizing")
Report downloadNot requiredRequires hsbc_edda_report service to periodically fetch
Limit modificationRequires re-authorizationRequires re-authorization

eDDA Is for Deposits Only

eDDA/eDDI is a Direct Debit channel that can only be used for deposits (debiting from the user's bank account into the Securities Account). Withdrawals do not use eDDA — Hang Seng/HSBC withdrawals go through the corporate online banking channel (hase / hsbc), where Operations completes the manual transfer via the bank's online banking portal.


Bank Card API Overview

Core APIs exposed by the bank card service — corresponding to CRM and App operations:

App-Facing APIs

APITrigger ScenarioEffectNotes
AddBankCardUser adds a bank card in AppCreates bank_card record, status=1Includes parameter validation (SWIFT/address/uniqueness)
GetBankCardListUser views bank card listReturns all cards with status≠2Includes methods list for frontend to display available channels
DeleteBankCardUser unbinds a bank cardstatus → 2 (Deleted)First checks for no in-progress deposits/withdrawals
CheckSaveCard added during online account opening flowCreates bank_card record, status=0 (Pending Approval)operation=1 account opening in progress / operation=0 deposit in progress
TakeEffectFirst deposit succeeds during online account openingstatus 0→1 (Pending Approval → Active)Called automatically by the deposit service

CRM-Facing APIs

APIOperations ActionEffectUse Case
GetBankCardInfoView bank card detailsReturns all card fields + extension infoGet complete card information during troubleshooting
UpdateBankCardModify bank card informationUpdates specified fieldsCorrect erroneous SWIFT/address, etc.
ManualVerifyManually approve verificationverify → 2Operations marks as verified after reviewing credentials
UpdateThirdPartyFlagModify third-party card flagthird_party_flag updatedCorrect misidentification
BatchTakeEffectBatch-activate Pending Approval cardsMultiple cards status 0→1Online account opening batch processing

Bank Card Exception Scenarios

#ScenarioSymptomPossible CauseTroubleshooting StepsOperations Action
1BST not workingUser reports BST deposit/withdrawal unavailableMandate is not in OPEN status1. Check bank_card_asb_bst.status = 2 (OPEN) 2. Check account_type is 2/3/6/7 (contains BST bit)Not OPEN → guide user to re-authorize
2eDDA Direct Debit failedError prompt during depositeDDA not enabled or limit exceeded1. Check eDDA status = 2 2. Check limit_amount for limit breach 3. Check expiry_date for expirationNot enabled → re-authorize; limit exceeded → wait for limit reset or increase limit
3Channel not showing after bindingBST/eDDA options not displayed in App after card bindingaccount_type not set correctly1. Check account_type value: BST needs 2/3/6/7, eDDA needs 4/5/6/7 2. Check methods listMissing account_type → check whether authorization flow completed
4Online account opening card unusablePending Approval card cannot deposit/withdrawFirst deposit not completed1. Check status = 0 2. Check whether first deposit succeeded 3. Check whether TakeEffect was executedDeposit succeeded but card not activated → manual BatchTakeEffect
5Verification failure blocking withdrawalFirst withdrawal to unverified card blockedCard unverified (verify=0)1. Check verify field 2. Check for pending credential reviewGuide user to upload bank statement; or Operations uses ManualVerify
6Third-party card restrictionsthird_party_flag=1 card has withdrawal restrictionsSystem identified as non-owner card1. Check third_party_flag 2. Confirm whether it is actually a third-party cardMisidentified → correct with UpdateThirdPartyFlag
7Missing SWIFT causing withdrawal failureBank error during withdrawalHK card bound without SWIFT (legacy data)1. Check whether bank_swift is emptyOperations uses UpdateBankCard to add SWIFT
8Currency not supportedUser's selected currency cannot be deposited/withdrawncurrency_type does not include the corresponding currency1. Check currency_type bitmapGuide user to bind a bank card that supports the currency

Online Account Opening

For the deposit-focused view of online account opening (including user journey and exception handling) → Card Binding & Deposit Authorization § Airstar Online Account Opening 3-in-1

Airstar 3-in-1 Flow

Airstar Bank supports online account opening — new customers can complete the entire zero-to-trading flow within the moomoo App:

StepActionDescriptionSystem OperationsData Changes
1Open Securities AccountComplete KYC identity verificationAccount system creates trading account
2Mandate AuthorizationAuthorize Airstar for BSTCreateAuth → bank confirmsBankCardAsbBst.status = 3 (WAITING)
bank_card.status = 0 (Pending Approval)
3First DepositComplete first deposit into Securities AccountDeposit succeeds → TakeEffectbank_card.status 0→1 (Active)
BankCardAsbBst.status 3→2 (OPEN)

Value: The traditional flow requires users to switch between multiple systems (moomoo for account opening → bank branch or online banking for authorization → back to moomoo for deposit). The 3-in-1 flow compresses these three steps into a seamless in-app experience, significantly reducing new customer drop-off rates.

Online Account Opening vs Standard Activation

DimensionOnline Account Opening (New Users)Standard Activation (Existing Airstar Account)
PrerequisitesNo Airstar bank account neededMust already have an Airstar bank account
WhereEntirely within moomoo AppInitiated in moomoo App; may require bank-side confirmation
FlowAccount opening → Authorization → First deposit, all in oneAuthorization → Deposit, two steps
Initial card statusstatus = 0 (Pending Approval)status = 1 (Active)
Initial Mandate statusstatus = 3 (WAITING)status = 2 (OPEN)
Minimum depositRequired (see table below)No minimum
Acquisition valueHigh — lowers barriers for new customersMedium — only for existing Airstar customers

First Deposit Requirements

The first deposit for online account opening has a minimum amount requirement, higher than standard deposits:

CurrencyOnline Account Opening MinimumStandard Deposit MinimumBehavior When Not Met
HKD10,000No minimumApp prompts "First deposit must be ≥ 10,000 HKD"
USD1,500No minimumApp prompts "First deposit must be ≥ 1,500 USD"
CNH10,000No minimumApp prompts "First deposit must be ≥ 10,000 CNH"

The purpose is to ensure new customers have sufficient funds to trade, avoiding ineffective conversions where users "open accounts but never trade."

Online Account Opening User Journey

Online Account Opening Exception Handling

#Exception ScenarioStuck AtData StateOperations Action
1Account opened but authorization failedMandate Authorizationbank_card.status=0, BankCardAsbBst.status=4(FAIL)Guide user to re-initiate authorization (no need to re-open account)
2Authorization succeeded but deposit failedFirst Depositbank_card.status=0, BankCardAsbBst.status=3(WAITING)Guide user to re-initiate deposit (must meet minimum amount)
3Deposit succeeded but card not activatedTakeEffectbank_card.status=0 (should be 1)Manual BatchTakeEffect or investigate TakeEffect API
4Stuck in Pending Approval for a long timeUser did not complete depositbank_card.status=0, BankCardAsbBst.status=3Contact user to remind them to complete the first deposit

Airstar Only

CMB and Minsheng do not support the online account opening 3-in-1 flow — BST Authorization must be completed on the bank side. Online account opening is an Airstar BST-exclusive acquisition feature, particularly well-suited for marketing campaigns (e.g., "Deposit and get commission-free trades").

For full limits → Withdrawal Rules Handbook § Three-Tier Limit System


After Reading

I want to...Go to
Learn about card binding & authorization from the deposit perspectiveCard Binding & Deposit Authorization
Learn about BST Mandate state machineInternal BST Overview
Learn about SBA orchestration modelSBA Fund Orchestration
See overall architecture and data flowSystem Architecture & Data Flow
Look up bank card-related error codesUnified Error Code Center
Was this page helpful?

内部业务文档 · 仅限 moomoo 团队使用