Overview
This document details all system changes required for the ZAND IBAN migration, organized by functional modules for development planning and task assignment.
flowchart LR
subgraph Features["Feature Modules"]
F1[Auto Open ZAND]
F2[Upload Migrate Files]
F3[Customer Migration]
F4[Notification & ToDo]
F5[Merchant Enrollment]
F6[Mini-program API]
F7[Retry Scheduler]
F8[Counter Retry Page]
F9[Metrics & Monitors]
end
F1 --> F3
F2 --> F3
F2 --> F5
F3 --> F4
F5 --> F4
F3 --> F7
F5 --> F7
F7 --> F8
F3 --> F6
F5 --> F6
F3 --> F9
F5 --> F9
style F1 fill:#E6F3FF,stroke:#4A90D9
style F2 fill:#E6FFE6,stroke:#4A9D4A
style F3 fill:#FFF3E6,stroke:#D99A4A
style F4 fill:#FFE6E6,stroke:#D94A4A
style F5 fill:#F0E6FF,stroke:#9A4AD9
style F6 fill:#E6FFFF,stroke:#4A9D9D
style F7 fill:#FFFDE6,stroke:#9D9A4A
style F8 fill:#F5F5F5,stroke:#666666
style F9 fill:#FFE6F3,stroke:#D94A9D
Feature 1: After KYC finished Auto Open ZAND Iban
Purpose: KYC完成后自动开户
MQ notification Changes(Visii)
| Exchange | Route Key | Description | Change |
|---|---|---|---|
| exchange.kyc.finish | kyc.eid.finish | KYC finish | |
| exchange.kyc.finish | kyc.eid.finish.vip | VIP KYC finish |
logic: recieved the notification and open ZAND Iban immediately.
have a switch to control the percent of new kyc users will be enrolled. (10% 30% 50% 100%)
Configuration
| Config Key | Type | Default | Description |
|---|---|---|---|
visii.zand.customer.autoOpen | Varchar | Y | Master switch for auto IBAN opening |
visii.zand.customer.openPercent | Integer | 10 | Percentage of new KYC users to enroll (10/30/50/100) |
Reconciliation
| Source | Targe | Description |
|---|---|---|
| member.tm_member | visii.t_va | if not exists, then call openAccount api |
Implemented CSC compensation api.
Reconciliation SQL:
SELECT m.user_id, m.mobile, m.email
FROM member.tm_member m
LEFT JOIN visii.t_va v ON m.user_id = v.user_id
WHERE m.kyc_status = 'PASSED'
AND m.created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
AND (v.zand_iban IS NULL OR v.zand_status = 'FAILED');Feature 2: Upload Migrate Files to import
Purpose: Upload Migrate File
Counter
Upload Migrate Files for both Customer and Merchant
Vis
Save the file info
Save file content to vis.t_migrate_record table
Idempotent process
Service Changes (VIS)
| Service | Component | Change | Description |
|---|---|---|---|
| VIS | MigrateFileService | NEW | Handle file upload and storage |
| VIS | MigrateRecordService | NEW | Save and manage migration records |
Feature 3: Customer Migration Engine
Purpose: Handle individual user migration from FAB VAM to PayBy VAM
Migration Flow
sequenceDiagram
participant Engine as Migration Engine
participant DB as Database
participant ZAND as ZAND API
participant FAB as FAB API
participant MQ as Message Queue
Engine->>DB: Fetch PENDING records
loop For each record
Engine->>DB: Update status = IN_PROGRESS
Engine->>Engine: Validate user eligibility
alt Valid User
Engine->>ZAND: Call Open Account API
alt ZAND Success
ZAND-->>Engine: Return new IBAN
Engine->>FAB: Update IBAN mapping
Engine->>DB: Update status = COMPLETED
Engine->>MQ: Publish MigrationCompletedEvent
else ZAND Failure
Engine->>DB: Update status = FAILED
Engine->>MQ: Publish MigrationFailedEvent
end
else Invalid User
Engine->>DB: Update status = SKIPPED
end
end
Configuration
| Config Key | Type | Default | Description |
|---|---|---|---|
migration.customer.enabled | Boolean | true | Master switch for customer migration |
migration.customer.batch_size | Integer | 100 | Records per batch |
migration.customer.parallel_threads | Integer | 5 | Parallel processing threads |
migration.customer.retry.enabled | Boolean | true | Enable auto-retry for failed records |
Feature 4: Send in-app notification + ToDo section
Purpose: Route AANI transactions based on user's VAM provider and migration status
Service Changes
| Service | Component | Change | Description |
|---|---|---|---|
| Notification Service | MigrationNotificationListener | NEW | Listen to migration events |
| Notification Service | NotificationTemplateService | MODIFY | Add migration notification templates |
| Notification Service | InAppPushService | MODIFY | Support migration push notifications |
| Notification Service | ToDoService | NEW | Create and manage ToDo items |
| Notification Service | ToDoReminderScheduler | NEW | Send reminders for pending ToDos |
API Changes
| Endpoint | Method | Change | Description |
|---|---|---|---|
/api/v1/notification/migration/list | GET | NEW | List migration notifications for user |
/api/v1/notification/migration/{id}/read | POST | NEW | Mark notification as read |
/api/v1/todo/list | GET | NEW | List ToDo items for user |
/api/v1/todo/{id}/complete | POST | NEW | Mark ToDo as completed |
Message Queue Subscriptions
| Exchange | Routing Key | Action |
|---|---|---|
exchange.migration | migration.customer.complete | Send success notification + ToDo |
exchange.migration | migration.customer.failed | Send failure notification + Support ToDo |
exchange.migration | migration.merchant.complete | Send merchant success notification |
exchange.migration | migration.merchant.failed | Send merchant failure notification |
Notification Templates
| Template ID | Trigger | Title | Content Summary |
|---|---|---|---|
migration_started | Migration begins | "IBAN Upgrade in Progress" | "We're upgrading your payment account..." |
migration_complete | Migration succeeds | "New IBAN Ready!" | "Your new IBAN {new_iban} is now active..." |
migration_failed | Migration fails | "Action Required" | "We couldn't complete your IBAN upgrade..." |
migration_reminder | 3 days after incomplete | "Complete Your Migration" | "Please complete your account upgrade..." |
ToDo Templates
| ToDo Type | Title | Description | Action |
|---|---|---|---|
CONFIRM_MIGRATION | Confirm New IBAN | Please verify your new IBAN is correct | Open IBAN details page |
UPDATE_BENEFICIARY | Update Payment Info | Inform your payers about your new IBAN | Share IBAN button |
VERIFY_IBAN | Verify Account | Complete verification for your new account | Open verification flow |
CONTACT_SUPPORT | Need Help? | Migration encountered an issue | Open support chat |
Configuration
| Config Key | Type | Default | Description |
|---|---|---|---|
notification.migration.enabled | Boolean | true | Enable migration notifications |
notification.migration.channels | List | IN_APP,PUSH | Enabled notification channels |
todo.migration.reminder.days | Integer | 3 | Days before sending reminder |
todo.migration.expiry.days | Integer | 30 | Days until ToDo expires |
Feature 5: Merchant Enrollment
Purpose: Handle merchant IBAN migration from FAB VAM to ZAND VAM for AANI payment acceptance.
New Merchant Enrollment (Vis)
Configuration
| Config Key | Type | Default | Description |
|---|---|---|---|
vis.zand.merchant.fullSwitch | Varchar | Y | Enable full merchant enrollment |
cmsii -> VIS_ZAND_MER_ID_WHITELIST
Merchant Migration Flow (Visii)
Counter Upload
Finish the Migrate
Counter Retry
Feature 6: Query Api provided to Mini-program
Purpose: Provide query APIs for Mini-Program to display user's IBAN migration status and new IBAN information.
Service Changes (VIS)
| Service | Component | Change | Description |
|---|---|---|---|
| VIS | MigrateFacade#queryAccounts | NEW | Handle Mini-Program migration queries, return old/new/duration |
Feature 7: Retry scheduler (3-attempt cap with increasing intervals)
Purpose: Automatically retry failed migrations with exponential backoff strategy, capped at 3 attempts.
Retry Strategy
| Attempt | Delay | Total Wait | Action |
|---|---|---|---|
| 1 | 0 min | 0 min | Immediate first attempt |
| 2 | 5 min | 5 min | First retry after 5 minutes |
| 3 | 30 min | 35 min | Final retry after 30 more minutes |
| 4+ | - | - | Mark as FINAL_FAILED, require manual intervention |
Service Changes
| Service | Component | Change | Description |
|---|---|---|---|
| VIS | MigrationRetryScheduler | NEW | Scheduled job to scan and retry |
Feature 8: Counter Retry Open Account Page
Purpose: Provide Counter staff with a page to manually retry ZAND account opening for failed cases.
Counter App UI Changes
| Page/Component | Change | Description |
|---|---|---|
| Retry Accounts List | NEW | Retry Accounts |
Feature 9: Metrics and Alerts
Purpose: Metris and Alerts
Metrics
| Metric Name | Type | Description |
|---|---|---|
migration_batch_progress | Gauge | Current batch progress (0-100%) |
migration_total_progress | Gauge | Overall migration progress (0-100%) |
migration_success_rate | Gauge | Success rate per batch |
migration_refund_count | Counter | Number of migration refunds |
migration_error_rate | Gauge | Error rate per time window |
migration_duration_seconds | Histogram | Time taken per user migration |
vam_provider_distribution | Gauge | User count by VAM provider |
iban_lookup_latency | Histogram | IBAN lookup response time |
Alerts
| Alert Name | Condition | Severity |
|---|---|---|
| MigrationFailureSpike | Error rate > 1% in 5 min | Critical |
| MigrationRefundRateHigh | Refund rate > 0.5% in batch | Warning |
| MigrationBatchTimeout | Batch exceeds 2x expected duration | Warning |
| MigrationBatchStalled | No progress for 10 minutes | Critical |
| IbanLookupLatencyHigh | P99 latency > 500ms | Warning |
Dashboard Panels
| Panel | Visualization | Data |
|---|---|---|
| Migration Progress | Progress Bar | Total migrated / Total users |
| Batch Status | Table | Recent batch statuses |
| Migration Timeline | Time Series | Migrations per hour |
| Error Distribution | Pie Chart | Errors by type |
| Refund Tracking | Counter + Trend | Refund count and trend |