Deposit Change Guide
About This Page
What: The 10 most common deposit change requests for PMs — each tells you what to change, where to change it, what it impacts, and who to get approval from Audience: Product managers who need to drive deposit-related requirement changes Prerequisites: Deposit Methods OverviewReading time: 5 minutes Owner: Deposit Product Manager
Key Takeaways: Deposit changes fall into four categories — code constants, configuration files, database, and operations backend. Different types of changes have vastly different cycle times and impact chains — code changes require releases, configuration changes may take effect immediately.
How to Use This Page
When you have a deposit-related change request:
- Find the corresponding change scenario below
- Look at "Configuration Type" to assess change difficulty and cycle
- Look at "Impact Chain" to evaluate risk
- Look at "Approval Requirements" to determine who to get sign-off from
- Look at "Verification Method" to confirm how to validate
Configuration Type Quick Reference
| Type | Meaning | How It Takes Effect | Change Cycle |
|---|---|---|---|
| Code constant | Hardcoded in PHP/Go/Python code | Requires release process | 1~3 days (including dev+test+release) |
| Configuration file | config/*.php or .env | Requires release process | 1~2 days |
| Database configuration | Stored in DB config tables | Takes effect immediately after change | Same day |
| Operations backend | Adjustable in OA/CRM backend | Operations self-service | Immediate |
| Cron configuration | Scheduled task expressions | Requires ops deployment | 0.5~1 day |
| Bank-side | Requires bank cooperation | Goes through business+technical integration | Weeks~months |
Change Approval Process
Regardless of the change scenario, the following general process should be followed:
Staging Verification General Guide
All changes requiring release (code constants, configuration file types) should be verified in Staging environment before going live.
Step-by-Step Guide: How to Verify Deposit Changes in Staging
Prerequisites: Staging environment has deployed latest code (including changes)
Step 1 — Prepare test data
- Create a test user in Staging (or use existing test account)
- Confirm Staging's bank mock service is running normally (Staging doesn't connect to real banks, uses mock to simulate statements)
Step 2 — Trigger test scenarios 3. Prepare different tests based on change type:
- Tolerance change: Construct statements with differences exactly at new/old tolerance boundaries, verify matching behavior change
- Limit change: Construct applications with amounts exactly at new/old limit boundaries, verify auto-credit decision
- Timeout change: Create application then fast-forward time (modify DB time), verify notification and rejection triggers
- Risk control change: Add/remove from blacklist then trigger deposit, verify DepositType marking
- New bank: End-to-end test complete chain (mock statement -> matching -> crediting -> reconciliation)
Step 3 — Verify results 4. Check DB status (Apply/Flow/Task/Match tables) matches expectations 5. Check notifications triggered correctly (Push/in-app message) 6. Check reconciliation report has no anomalies
Step 4 — Record 7. Screenshot/screen-record verification results 8. Mark "Staging verified" in requirements document
Scenario 1: Adjust a Bank's Matching Tolerance
Example: Change HSBC's auto-credit tolerance from HKD 65 to HKD 100
| Dimension | Description |
|---|---|
| What to change | Tolerance constants in the corresponding bank's Matcher class |
| Where to change | deposit/src/app/Business/Match/HsbcMatch.php (HSBC), BocMatch.php (BOCHK), HangSengMatch.php (Hang Seng), IcbcNewMatch.php (ICBC), DbsMatch.php (DBS), EwbMatch.php (EWB) |
| Configuration type | Code constant — requires release |
| Impact chain | Tolerance loosened -> More statements enter auto-matching -> Mismatching risk increases (different applications with similar amounts may be incorrectly paired) -> Possible incorrect crediting. Tolerance tightened -> More statements downgraded to assisted matching -> Operations manual confirmation workload increases |
| Verification method | Pre-release: Pull 1 week of that bank's historical statements, simulate backtest matching results with new tolerance. Post-release: Monitor that bank's "auto-match rate" and "assisted match volume" changes |
| Approval requirements | Product confirmation + Operations awareness (workload may change) |
| Rollback | 1. Restore original tolerance constant -> Re-release (~1 hour) 2. Deposits already incorrectly matched by new tolerance need case-by-case review 3. If mismatch found -> Follow reversal process (Reversal Guide) |
Core Risk of Tolerance Adjustment
Every 1 unit of tolerance loosening theoretically increases the probability of "different applications with similar amounts being incorrectly paired." Especially when the same bank has multiple users simultaneously applying for similar amounts. Must backtest with historical data before going live.
Current bank tolerances -> Deposit Quick Reference - Matching Tolerance
Scenario 2: Adjust Auto-Credit Limits
Example: Change HKD auto-credit limit from 2 million to 5 million
| Dimension | Description |
|---|---|
| What to change | Currency limit constants in DepositConfigNew |
| Where to change | deposit/src/app/Business/DepositConfigNew.php |
| Configuration type | Code constant — requires release |
| Impact chain | Limit raised -> More large deposits go through auto-channel -> Reduces operations workload, but large abnormal deposits may also be auto-released. Limit lowered -> More deposits require manual confirmation -> Operations workload increases, but security is higher |
| Verification method | Post-release: Monitor "deposits requiring manual confirmation percentage" changes |
| Approval requirements | Risk Control team sign-off (mandatory) + Product confirmation + Operations awareness |
| Rollback | 1. Restore original limit constant -> Re-release (~1 hour) 2. Check whether deposits exceeding original limit were auto-processed during change period 3. If abnormal large amounts found -> Joint risk control team case-by-case review |
Current Limits
HKD 2,000,000 / USD 300,000 / CNH 2,000,000 / JPY 40,000,000 / SGD 350,000. Full table -> Deposit Quick Reference - Currency Limits
Scenario 3: Modify Timeout Days
Example: Change FPS notification days from 1 day to 2 days
| Dimension | Description |
|---|---|
| What to change | Timeout configuration (notification days, rejection days) |
| Where to change | deposit/src/app/Business/DepositConfigNew.php — timeout configuration section |
| Configuration type | Code constant — requires release |
| Impact chain | Notification days extended -> User waits longer before receiving reminder -> May lead to more "money hasn't arrived" complaints. Notification days shortened -> Normal but slower bank transfers may be prematurely notified -> User confusion |
| Special note | Days are calculated in HKEX trading days (excluding weekends and public holidays). Changes only affect new applications, not existing applications' timeout calculations |
| Verification method | Post-release: Create test application, wait for timeout notification to trigger |
| Approval requirements | Product confirmation |
| Rollback | Restore original days, re-release |
Current timeout configuration -> Deposit Quick Reference - Timeout Configuration
Scenario 4: Adjust 2412 Suspension Window
Example: Change the 16:05~16:10 suspension window to 16:00~16:15
| Dimension | Description |
|---|---|
| What to change | 2412 suspension window start/end times |
| Where to change | deposit/src/app/Business/DepositConfigNew.php:603-641 |
| Configuration type | Code constant — requires release |
| Impact chain | Window expanded -> More deposits downgraded to assisted matching during suspension -> Operations workload increases, but reconciliation safety is higher. Window shrunk -> Auto-deposits may execute during reconciliation period -> May cause account balance inconsistencies |
| Why it can't be changed arbitrarily | The 2412 window ensures that account reconciliation at market open/close is not disturbed by fund movements. The window start/end times align with the exchange's pre-open settlement and post-close settlement times. If the window is shortened, "account balance being changed by a deposit at the moment of reconciliation" may occur, causing accounting imbalance |
| Verification method | Joint Settlement team verification that reconciliation reports show no discrepancies |
| Approval requirements | Settlement team sign-off (mandatory) + Product confirmation |
| Rollback | Restore original window, re-release |
Scenario 5: Modify Risk Control Rules
Example: Add/remove a user from the blacklist
| Dimension | Description |
|---|---|
| What to change | Blacklist/whitelist data |
| Where to change | hk-deposit-blacklist-go / hk-deposit-whitelist-go service management interfaces |
| Configuration type | Database configuration — takes effect immediately after change |
| Impact chain | Added to blacklist -> All subsequent deposits from that user automatically marked as HIGH_RISK(5) -> Requires manual review before crediting. Removed from blacklist -> That user returns to normal auto-crediting. Blacklist supports setting expiration time (temporary observation) |
| Special note | Blacklist affects the deposit step. If the user already has an application being matched, the blacklist takes effect in the next matching cycle (within 3 minutes). Already completed deposits are not affected |
| Verification method | After adding, trigger a test deposit, confirm deposit_type is marked as 5 |
| Approval requirements | Risk Control team sign-off (mandatory) |
| Rollback | Remove from blacklist, takes effect immediately |
Scenario 6: Adjust Matching Engine Frequency
Example: Change matching engine from every 3 minutes to every 1 minute
| Dimension | Description |
|---|---|
| What to change | Matching Cron task execution frequency |
| Where to change | Cron expressions for each match:* task in deposit/doc/crontab.sh |
| Configuration type | Cron configuration — requires ops deployment |
| Impact chain | Frequency increased -> Users perceive faster deposit speed. But database query frequency increases proportionally -> May affect DB performance, especially for high-volume banks (BOCHK, HSBC) |
| Why currently 3 minutes | At current daily statement volumes, 3 minutes is the balance point between "user experience" and "database load." The matching engine scans all pending records (status=0) in flows and applys tables each run; higher frequency means more frequent scanning. If a bank only has dozens of statements per day, increasing frequency adds little value; if thousands per day, it creates significant DB pressure |
| Verification method | First verify DB load changes in stress test environment; monitor DB slow query alerts during canary period |
| Approval requirements | Technical lead confirmation (DB load assessment) + Product confirmation |
| Rollback | Restore original cron expressions, redeploy |
Scenario 7: Add New Bank Deposit Channel
Example: Integrate a new bank (e.g., Dah Sing Bank) with Push mode deposit
This is the most complex change scenario, involving multiple services and configurations.
Development Checklist
| Step | Work Content | Services/Files Involved |
|---|---|---|
| 1 | Assign TransType code | deposit/proto/server/cash_deposit.proto — add new value to enum |
| 2 | Develop statement collection service | Create new Go/Python service (reference dbs_service or icbc_be_relay) |
| 3 | Implement Matcher class | Create new XxxMatch.php under deposit/src/app/Business/Match/, inheriting MatchBase |
| 4 | Configure matching Cron task | Add match:xxx every 3 minutes to deposit/doc/crontab.sh |
| 5 | Configure tolerance and time windows | Define in Matcher class (reference similar banks) |
| 6 | Configure timeout days | Set by deposit method in DepositConfigNew.php |
| 7 | Frontend deposit method display | App deposit page configure new method visibility |
| 8 | Reconciliation configuration | Add new bank in bank_reconciliation task |
| 9 | Integration testing | End-to-end test: statement collection -> matching -> crediting -> reconciliation |
Prerequisites
| Condition | Description | Responsible Party |
|---|---|---|
| Bank technical integration protocol | Determine statement acquisition method (API/file/Webhook) | Business + Technical |
| Company receiving account | Open corporate receiving account at that bank | Finance |
| Bank card identification rules | BIN number range identification, for frontend display and matching | bankcard_service |
Approval Requirements
Business team (bank partnership) + Technical lead + Product confirmation
Reference Timeline
| Statement Integration Method | Reference Timeline | Reference |
|---|---|---|
| API real-time push | 3~4 weeks | Reference SCB scb_service |
| API scheduled pull | 2~3 weeks | Reference ICBC icbc_be_relay |
| File batch pull | 4~6 weeks | Reference BOCHK bochk_flow_go (most complex) |
Task Dependencies & Parallelism
The 9 steps for new bank integration are not all sequential. Below are dependencies and parallelizable work:
Parallelizable work (marked in green):
- Steps 2 (collection), 3 (Matcher), 6 (timeout config), 7 (frontend display) can proceed simultaneously
- Steps 4 (Cron) and 5 (tolerance/windows) depend on 2 and 3, but can be parallelized after 2/3 complete
- Step 9 (integration testing) is the final convergence point, depending on all other steps
Critical path: Prerequisites -> TransType -> Statement collection service -> Integration testing. Statement collection service development is typically the longest-duration task.
Rollback Strategy
If rollback needed after new bank goes live:
- Disable frontend display (users can't see that bank's deposit method) -> Takes effect immediately
- Stop
match:{bank}Cron task -> New statements no longer matched - Stop statement collection service -> No longer receiving new statements
- Already completed deposits are unaffected, no reversal needed
Scenario 8: Add eDDA Support for New Bank
Example: Want DBS to also support eDDA deposit
Conclusion: Not feasible short-term; need to assess bank-side support.
| Prerequisite | Description | Controllability |
|---|---|---|
| Bank supports eDDA protocol | Bank must implement eDDA functionality within HKMA's FPS system | Entirely depends on bank |
| Business partnership signed | Bank agrees to grant moomoo eDDA debit authorization | Requires business negotiation |
| Technical integration | Integrate bank's eDDA/eDDI API (each implementation differs) | Estimated 4~8 weeks |
| SBA orchestration service | Create new sba_xxx_eddi orchestration service | Reference sba_hsbc_eddi |
| deposit service adaptation | Add new bank branch in Eddi.php | 1~2 weeks |
Why currently only HSBC and Hang Seng? eDDA is part of HKMA's (Hong Kong Monetary Authority) FPS system. Although technical standards are unified, each bank's API implementation, review process, and business terms differ. Currently only HSBC and Hang Seng have completed full integration (business signing + technical integration + production go-live).
If you really want to push forward: First step is to contact the bank relationship team to confirm whether the target bank supports the eDDA protocol, then assess business and technical workload.
Scenario 9: Add New Currency Support
Example: Add GBP (British Pound) deposit
| Step | Work Content | Files Involved |
|---|---|---|
| 1 | Proto definition | deposit/proto/server/cash_deposit.proto — add Currency enum |
| 2 | Tolerance configuration | Add GBP tolerance in each Matcher class (reference exchange rate conversion with HKD) |
| 3 | Limit configuration | DepositConfigNew.php — add GBP auto-credit limit |
| 4 | Timeout configuration | DepositConfigNew.php — add GBP timeout days |
| 5 | Frontend display | Add GBP to deposit page currency selector |
| 6 | SBA configuration | SBA system supports GBP balance account |
| 7 | Reconciliation | Add GBP reconciliation task |
Prerequisites: Company needs a GBP account at receiving banks. Not all banks support all currencies — first confirm which banks can receive GBP.
Approval requirements: Product confirmation + Settlement team confirmation + Technical lead
Scenario 10: Modify Deposit Notification Logic
Example: Change the push notification copy after successful deposit
| Dimension | Description |
|---|---|
| What to change | Notification copy and trigger logic |
| Where to change | Notification service configuration (not under deposit service jurisdiction; deposit only sends notification events) |
| Configuration type | Depends on notification service implementation — typically configuration file or database |
| Impact chain | Copy changes only affect user-side display; trigger logic changes may affect notification timing and frequency |
| Special note | The deposit system defines 4 notification type codes (standard deposit=1, online account opening card binding=2, post-card-binding deposit=3, mainland pre-account-opening=4); the specific copy and channels (Push/SMS/in-app message) are controlled by the notification service |
| Verification method | Trigger a deposit in test environment, confirm notification content and channel |
| Approval requirements | Product confirmation |
Scenario 11: Modify Reversal Process
Example: Add secondary approval before reversal / Don't auto-unbind bank card after reversal
| Dimension | Description |
|---|---|
| What to change | Deposit reversal execution logic, precondition validation, post-processing actions |
| Where to change | deposit/src/app/Business/Deposit.php:877-935 (deposit reversal reverse() method) |
| Configuration type | Code constant — requires release |
| Impact chain | Reversal process changes directly affect the ability to withdraw funds from completed deposits. Modifying precondition validation may prevent reversals that should be executed; modifying post-processing actions may miss unbinding/notification steps |
| Verification method | Create test deposit in Staging -> Complete crediting -> Execute reversal -> Verify Apply.status=5, SBA Procedure success, bank card unbinding status, notification trigger |
| Approval requirements | Risk Control team sign-off (mandatory) + Product confirmation + Operations awareness |
| Rollback | Restore original code -> Re-release. Reversals already processed by new logic are unaffected (reversals are irreversible) |
Common change scenarios:
| Change | Change Location | Notes |
|---|---|---|
| Add approval step before reversal | Add approval check at reverse() method entry | Currently reversal executes directly without secondary approval. Adding approval extends reversal turnaround time |
| Don't auto-unbind bank card after reversal | Unbinding logic in reverse() | Not unbinding may cause next deposit to still go through card-binding channel |
| Add reversal amount cap | Pre-validation in reverse() | Over-cap reversals need escalated approval (e.g., large amounts go to supervisor) |
| Modify reversal notification template | Notification service message template configuration | Not under deposit service jurisdiction |
| Batch reversal limits | /deposit/batch interface | Currently no batch quantity limit; can add to prevent mis-operations |
Related Code Locations
- Deposit reversal:
deposit/src/app/Business/Deposit.php:877-935—reverse()core logic - SBA reverse:
deposit/src/app/Business/SOA/SBA/Deposit.php:309—turnAround('CashDepositReverse') - Reversal middleware:
deposit/src/app/Business/Tasks/Deposit.php:276-287 - Withdrawal reversal (reference):
withdraw/src/app/Business/Tasks/Handler/Reverse.php
Refund mechanism product description -> Refund & Reversal Operations reversal manual -> Reversal/Refund Guide
Change Risk Matrix
| Change | Technical Risk | Business Risk | Change Cycle | Suggested Canary Approach |
|---|---|---|---|---|
| Adjust tolerance | Low | High (mismatching) | 1~3 days | Backtest with historical data first |
| Adjust limits | Low | High (large amount anomalies) | 1~3 days | Adjust by bank in batches |
| Modify timeout | Low | Medium | 1~3 days | Adjust by bank in batches |
| Adjust 2412 | Low | High (reconciliation anomalies) | 1~3 days | Canary not recommended; must verify fully |
| Risk control rules | Low | Medium | Immediate | Operate at user granularity |
| Matching frequency | Medium (DB load) | Low | 0.5~1 day | Increase frequency by bank incrementally |
| New bank | High | Medium | 3~6 weeks | New bank launches independently |
| New eDDA | High | Low | Months | New bank launches independently |
| New currency | Medium | Low | 2~3 weeks | Open by currency incrementally |
| Modify notification | Low | Low | 1~2 days | Canary push |
| Modify reversal process | Medium | High (fund safety) | 1~3 days | Must verify fully |
After Reading
| I want to... | Go to |
|---|---|
| Understand the panorama of 10 deposit methods | Deposit Methods Overview |
| See matching tolerance and limit detailed rules | Matching & Auto-Credit |
| Look up a specific parameter value | Deposit Quick Reference |
| Understand eDDA protocol and error codes | eDDA Direct Debit Deposit |
| See what change scenarios exist on withdrawal side | Withdrawal Change Guide |
| Understand refund and reversal mechanisms | Refund & Reversal |