Savings Accounts
Relevant source files
The following files were used as context for generating this wiki page:
The Savings Accounts module within the MBBank SDK provides developers with the tools to programmatically interact with a user's saving products at Military Commercial Joint Stock Bank. This functionality includes retrieving a comprehensive list of all savings accounts (both online and branch-based), fetching granular details for specific accounts, and querying current interest rates for various currencies.
The module is built upon a structured data model using Pydantic for validation and is accessible through both synchronous (MBBank) and asynchronous (MBBankAsync) client implementations. It handles the complexity of MBBank's internal API endpoints, including session management and request signing.
Sources: mbbank/sync/mbbank.py:270-305, mbbank/aio/mbbank.py:275-311, mbbank/modals/saving_list.py:100-108
System Architecture and Data Flow
The interaction with savings accounts follows a standard request-response pattern where the SDK client authenticates the user, constructs a secure JSON payload, and communicates with specific MBBank microservices.
Savings Retrieval Flow
The following sequence diagram illustrates the process of retrieving saving information using the synchronous client.
The SDK abstracts the underlying API endpoints and ensures that the raw JSON responses are mapped to typed Python objects for easier consumption.
Sources: mbbank/sync/mbbank.py:270-305, mbbank/modals/saving_list.py, mbbank/modals/saving_detail.py
Key Methods and API Endpoints
The SDK provides three primary methods for managing savings information, implemented in both mbbank.sync.MBBank and mbbank.aio.MBBankAsync.
| Method | Endpoint | Description |
|---|---|---|
getSavingList() | /api/retail-savingms/saving/v3.0/getList | Retrieves all savings accounts associated with the user. |
getSavingDetail(accNo, accType) | /api/retail_web/saving/getDetail | Fetches full details for a specific account using its number and type (OSA or SBA). |
getInterestRate(currency) | /api/retail_web/saving/getInterestRate | Queries current interest rates for a given currency (default: "VND"). |
Sources: mbbank/sync/mbbank.py:251-305, mbbank/aio/mbbank.py:256-311
Data Models
The savings module utilizes complex data structures to represent different types of saving products.
Saving Information Model
The SavingInfo class represents the core data for an individual saving account, including balances, dates, and account identifiers.
| Field | Type | Description |
|---|---|---|
savingAccountNumber | str | The unique identifier for the savings account. |
principalAmount | int | The initial/principal deposit amount. |
interestRate | float | The annual interest rate applied to the account. |
openDate | str | The date the account was opened. |
maturityDate | str | The date the saving term ends. |
accountType | str | The type of account (e.g., OSA for Online, SBA for Branch). |
remain | int | The remaining balance in the account. |
Sources: mbbank/modals/saving_list.py:34-84
Class Diagram: Savings Response Structure
The following diagram shows the relationship between the various modal classes used to parse the list of savings accounts.
Sources: mbbank/modals/saving_list.py:12-108
Account Types and Details
The system distinguishes between two primary types of savings accounts, which must be specified when querying details:
- OSA (Online Saving Account): Accounts opened via the MBBank mobile app or web portal.
- SBA (Saving Bank Account): Traditional savings accounts opened at a physical branch.
Saving Detail Fields
The SavingDetail model provides additional fields not found in the summary list, such as accrued interest and maturity instructions.
class SavingDetail(BaseModel):
accountNumber: Optional[str] = None
savingsAccountNo: str
productName: str
principalAmount: str
interestRate: str
accruedInterestAmount: str
totalMaturityAmount: str
maturityInstructions: str
beneficiaryAccount: str
Sources: mbbank/modals/saving_detail.py:8-28, mbbank/sync/mbbank.py:291-305
Implementation Example
The following snippet demonstrates how to use the synchronous MBBank client to iterate through savings accounts and display basic information.
from mbbank import MBBank
mb = MBBank(username="your_user", password="your_password")
savings_response = mb.getSavingList()
# Data is split into online and branch sections
online_savings = savings_response.data.onlineFixedSaving.data
for acc in online_savings:
print(f"Account: {acc.savingAccountNumber}")
print(f"Balance: {acc.principalAmount}")
print(f"Rate: {acc.interestRate}%")
Sources: examples/saving_list.py:10-48, mbbank/sync/mbbank.py:284-289
Summary
The Savings Accounts feature provides a robust interface for monitoring personal investments. By segregating online and branch savings and providing detailed models for interest rates and maturity data, the SDK enables comprehensive financial tracking within the MBBank ecosystem.