Supported Banks
Relevant source files
The following files were used as context for generating this wiki page:
The Supported Banks module in the MBBank library provides the necessary infrastructure to retrieve, cache, and utilize information about financial institutions compatible with MBBank's transfer services. This system is critical for inter-bank transfers, allowing the library to resolve bank codes, names, and specific routing identifiers like SML or CITAD codes.
The module facilitates both internal MBBank transfers and external transfers to other domestic banks. It supports synchronization through a caching mechanism to minimize redundant API calls and provides models to ensure type-safe handling of bank metadata.
Bank Data Architecture
The library represents bank entities through a structured data model and provides methods in both synchronous and asynchronous clients to fetch this data from MBBank's backend.
The Bank Data Model
The Bank class is a Pydantic-based model that encapsulates all metadata required for a transaction.
| Field | Type | Description |
|---|---|---|
bankId | str | Unique internal identifier for the bank. |
bankName | str | Full name of the bank in Vietnamese. |
bankCode | str | Standardized short code (e.g., "MB"). |
smlCode | str | Smartlink code used for card-based routing. |
citadCode | Optional[str] | CITAD code for electronic interbank payments. |
typeTransfer | str | Defines the transfer protocol used for the bank. |
Sources: mbbank/modals/bank_list.py:7-22
Fetching and Caching Logic
Both MBBank (Sync) and MBBankAsync (Async) implement a getBankList() method. To optimize performance, the library implements a simple in-memory cache using a _temp dictionary.
The diagram shows the logic flow for retrieving the bank list, ensuring network calls are minimized.
Sources: mbbank/sync/mbbank.py:348-358, mbbank/aio/mbbank.py:326-337
Integration in Transfer Flows
Supported banks are integral to the TransferContext and TransferContextAsync objects, which manage the lifecycle of a money transfer.
Bank Resolution
When a transfer is initiated, the system must resolve the provided bank_code into a full Bank object to determine the transferType.
ATM Card Bank Identification
The library supports identifying a bank based on the prefix of an ATM card number. This is handled by comparing the start of the cardNumber with the smlCode of banks in the supported list.
bank_list = self.getBankList()
bank_info = None
for bank in bank_list.listBank:
if cardNumber.startswith(bank.smlCode):
bank_info = bank
break
Sources: mbbank/sync/mbbank.py:461-468, mbbank/aio/mbbank.py:439-446
API Endpoints and Parameters
The system interacts with specific MBBank retail web endpoints to maintain the bank registry and perform inquiries.
Bank-Related Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/common/getBankList | POST | Retrieves the complete list of supported domestic banks. |
/transfer/v1.0/inquiry-account-name | POST | Validates an account number at a specific bank. |
/transfer/inquiryAccountName | POST | Validates an ATM card number at a specific bank. |
Sources: mbbank/sync/mbbank.py:356, mbbank/sync/mbbank.py:417, mbbank/sync/mbbank.py:479
Transfer Type Mapping
The typeTransfer field in the bank model is used to construct service codes for authentication and verification. For example, a transfer might use a service code formatted as GCM_FTR_DOM_{typeTransfer}.
Sources: mbbank/sync/transfer.py:117, mbbank/sync/transfer.py:151
Conclusion
The "Supported Banks" system within the MBBank library acts as a bridge between user-provided identifiers (like bank codes or card prefixes) and the technical requirements of the MBBank API. By combining Pydantic models for data integrity with a caching layer in the core clients, the library provides a reliable way to navigate the Vietnamese banking landscape for automated transfers and account inquiries.