Beneficiary Lists
Relevant source files
The following files were used as context for generating this wiki page:
The Beneficiary Lists module in the mbbank-lib library provides the data structures and API interactions required to manage and retrieve lists of payees for banking transactions. This system categorizes beneficiaries into two primary types: transfer-based beneficiaries (for bank-to-bank movements) and payment-based beneficiaries (for bill services).
This module is essential for the Money Transfer workflow, allowing users to select pre-saved or frequently used accounts rather than manually inputting account details for every transaction. It integrates with both synchronous and asynchronous core clients to provide real-time retrieval of favored and saved contact lists.
Sources: mbbank/modals/beneficiary_list.py, mbbank/sync/mbbank.py:246-267
Architecture and Data Models
The system relies on Pydantic models to validate and structure the data returned from the MBBank API. The models distinguish between different transaction contexts (Transfer vs. Payment) and storage contexts (Favored vs. Saved).
Class Diagram
The following diagram illustrates the relationship between the base response models and the specific beneficiary entities.
Data Structure Details
| Model | Description | Key Fields |
|---|---|---|
BeneficiaryTransfer | Used for standard bank transfers. | accountNo, name, bankCode, isCard, domesticFastCode |
BeneficiaryPayment | Used for bill payments (utilities, services). | serviceCode, providerCode, custId, paymentDateLatest |
BeneficiaryListResponseModal | Generic container for "Favor" lists. | favorBeneficiaryList (Union of Transfer/Payment) |
SavedBeneficiaryListResponseModal | Container for saved contact lists. | baseFtList, billPayeeList |
Sources: mbbank/modals/beneficiary_list.py:7-87
Retrieval Logic
The library provides two distinct methods for retrieving beneficiaries based on their status in the user's account: "Favor" (frequent/recent) and "Saved" (explicitly bookmarked).
Favored Beneficiaries
The getFavorBeneficiaryList method retrieves accounts based on transaction frequency or recency.
- Endpoint:
https://online.mbbank.com.vn/api/retail_web/internetbanking/getFavorBeneficiaryList - Parameters:
transactionType: Either"TRANSFER"or"PAYMENT".searchType: Either"MOST"(frequently used) or"LATEST"(recently used).
Sources: mbbank/sync/mbbank.py:246-267, mbbank/aio/mbbank.py:252-273
Saved Beneficiaries
The getSavedBeneficiary method retrieves the user's static list of saved contacts.
- Endpoint:
https://online.mbbank.com.vn/api/retail_web/common/getBeneficiary - Payload: Hardcoded to
{"type": "TRANSFER"}within the library implementation.
Sources: mbbank/sync/mbbank.py:431-444, mbbank/aio/mbbank.py:439-452
Transaction Flow
When a user initiates a transfer, the beneficiary list acts as a data provider to populate destination details.
Implementation Example
The following snippet demonstrates how to retrieve and iterate through favored beneficiaries using the synchronous API.
from mbbank import MBBank
mb = MBBank(username="...", password="...")
# Get the most frequently used transfer beneficiaries
favors = mb.getFavorBeneficiaryList(
transactionType="TRANSFER",
searchType="MOST"
)
for ben in favors.favorBeneficiaryList:
# ben is an instance of BeneficiaryTransfer
print(f"Name: {ben.name}, Account: {ben.accountNo}")
Sources: mbbank/sync/mbbank.py:246-267, mbbank/init.py:118-126
Conclusion
The Beneficiary Lists module provides a structured approach to managing transaction endpoints within the MBBank ecosystem. By separating data models for transfers and payments, and providing specialized endpoints for favored and saved contacts, the library enables developers to build intuitive transfer interfaces that mirror the official MBBank mobile experience.