Account Balances & Queries
Relevant source files
The following files were used as context for generating this wiki page:
The Account Balances & Queries module provides the core functionality for retrieving financial state information from MBBank personal accounts. This system encompasses the retrieval of current balances for primary and international accounts, loyalty points, transaction histories, and detailed lists of specialized accounts such as savings and loans.
The module is implemented with parity across both synchronous (mbbank.sync.MBBank) and asynchronous (mbbank.aio.MBBankAsync) architectures. It utilizes Pydantic models (modals) to ensure strict data validation and type safety when processing responses from the internal MBBank retail banking APIs.
Core Balance Retrieval
The system provides two primary methods for checking financial holdings: standard account balances and loyalty-based balances.
Standard Account Balance
The getBalance() method communicates with the retail-accountms service to retrieve a comprehensive list of all associated accounts. The response includes both domestic and international account lists, along with a calculated total balance equivalent in a specific currency.
Loyalty and Rewards
The getBalanceLoyalty() method queries the retail_web/loyalty endpoint to retrieve the user's membership status and redeemable points. This includes a BalanceDTO which tracks holding versus redeemable balances.
| Field | Type | Description |
|---|---|---|
totalHoldingBalance | str | Total points currently held |
totalRedeemableBalance | str | Points available for immediate use |
loyaltyAccountStatus | str | Status of the loyalty program account |
poolId | str | Identifier for the loyalty reward pool |
| Sources: mbbank/modals/balance_loyalty.py:8-33, mbbank/sync/mbbank.py:293-305 |
Transaction History Queries
Transaction history retrieval is categorized into standard account transactions and card-specific transactions. Both query types require a specific date range, typically limited to a maximum of 3 months.
Account Transaction History
The getTransactionAccountHistory method allows filtering by a specific sub-account number. If no account number is provided, it defaults to the main account associated with the user ID.
Card Transaction History
Card history is retrieved through the retail_web/common service. Unlike account history, this request requires a historyType set to DATE_RANGE and a type identifier set to CARD.
Sources: mbbank/sync/mbbank.py:382-411, mbbank/aio/mbbank.py:355-384
Specialized Account Queries
The module facilitates deep inspection into various account types beyond standard checking/current accounts.
Savings and Deposits
The SDK supports fetching a high-level list of all saving accounts and drilling down into specific account details.
- Saving List: Queries
retail-savingmsfor all active saving contracts. - Saving Detail: Requires an account number (
accNo) and an account type (accType), which can beOSA(Online Saving Account) orSBA(Saving Bank Account). - Interest Rates: Users can query current saving interest rates using
getInterestRate, which defaults to VND currency.
Sources: mbbank/sync/mbbank.py:339-370, mbbank/aio/mbbank.py:311-342
Loan and Card Lists
- Loan List: Retrieved via the
retail-onlineloanmsservice, providing details on active credit facilities. - Card List: Provides a comprehensive list of physical and virtual cards via
retail_web/card/getList.
Sources: mbbank/sync/mbbank.py:328-337, mbbank/aio/mbbank.py:284-293
Data Models for Queries
All responses are mapped to Pydantic models to ensure the application layer receives structured, validated data.
| Modal Class | API Source Service | Primary Data Fields |
|---|---|---|
BalanceResponseModal | retail-accountms | acct_list, totalBalanceEquivalent |
TransactionHistoryResponseModal | retail-transactionms | transactionHistoryList |
SavingListResponseModal | retail-savingms | savingList |
UserInfoResponseModal | retail_web/internetbanking | cust, acct_list, cardList |
BalanceLoyaltyResponseModal | retail_web/loyalty | bodyBalanceLoyalty |
| Sources: mbbank/modals/balance.py, mbbank/modals/userinfo.py:192-205, mbbank/modals/balance_loyalty.py:36-40 |
Conclusion
The Account Balances & Queries module serves as the primary data retrieval layer of the MBBank SDK. By abstracting complex REST interactions with specialized microservices (accountms, savingms, transactionms) into simple method calls, it provides a consistent interface for developers to monitor financial assets and historical activities across both synchronous and asynchronous Python environments.