Loyalty Points

Relevant source files

The following files were used as context for generating this wiki page:

• mbbank/modals/balance_loyalty.py
• mbbank/aio/mbbank.py
• mbbank/sync/mbbank.py
• mbbank/modals/init.py
• mbbank/init.py

The Loyalty Points system within the MBBank library provides a programmatic interface to retrieve a user's loyalty account status, membership rank, and accumulated points. This feature is integrated into both the synchronous and asynchronous core clients, allowing developers to query the "Military Commercial Joint Stock Bank" (MBBank) loyalty program details associated with a personal account.

The system primary functions by interfacing with the bank's retail loyalty API, returning structured data models that detail total balances, redeemable points, and customer identification information. This information is typically used to display user rewards or verify eligibility for specific banking benefits.

Sources: mbbank/modals/balance_loyalty.py, mbbank/aio/mbbank.py:246-256, mbbank/sync/mbbank.py:228-238

System Architecture

The loyalty system is built upon a request-response pattern using Pydantic models for data validation. The core logic resides in the MBBank (sync) and MBBankAsync (async) classes, which handle authentication and the underlying HTTP communication with the MBBank API endpoints.

Data Flow

The following diagram illustrates the flow of a loyalty balance request from the client to the bank's API and the subsequent transformation into a structured Python object.

The request requires a valid sessionId and uses standard headers including device identification and request tracking IDs.
Sources: mbbank/aio/mbbank.py:157-198, mbbank/sync/mbbank.py:228-238

Data Structures

The loyalty system utilizes specific Data Transfer Objects (DTOs) and response models to represent the bank's loyalty data.

Model Hierarchy

Model Field Descriptions

Class	Field	Type	Description
BalanceDTO	totalHoldingBalance	str	Points currently held/locked in the account.
	totalRedeemableBalance	str	Points available for immediate redemption.
	totalBalance	str	The sum of all points in the specific pool.
	poolId	str	Identifier for the loyalty point pool.
BalanceLoyalty	cif	str	Customer Information File number.
	fullName	str	Full name of the account holder.
	loyaltyAccountStatus	str	Current status of the loyalty account (e.g., Active).
	balanceDTO	List	A list containing detailed point balances across different pools.

Sources: mbbank/modals/balance_loyalty.py:7-31

API Implementation

The loyalty functionality is exposed via the getBalanceLoyalty method in both synchronous and asynchronous implementations.

Endpoint Details

• URL: https://online.mbbank.com.vn/api/retail_web/loyalty/getBalanceLoyalty
• Method: POST
• Authentication: Requires sessionId in the JSON payload and Deviceid in headers.

Code Implementation (Async)

async def getBalanceLoyalty(self) -> BalanceLoyaltyResponseModal:
    """
    Get Account loyalty rank and Member loyalty point
    """
    data_out = await self._req(
        "https://online.mbbank.com.vn/api/retail_web/loyalty/getBalanceLoyalty"
    )
    return BalanceLoyaltyResponseModal.model_validate(data_out, strict=True)

Sources: mbbank/aio/mbbank.py:246-256, mbbank/sync/mbbank.py:228-238

Usage Example

The library provides a straightforward way to access these details after initializing the bank client.

from mbbank import MBBank

mb = MBBank(username="your_username", password="your_password")
loyalty_info = mb.getBalanceLoyalty()

print(f"Customer: {loyalty_info.bodyBalanceLoyalty.fullName}")
for balance in loyalty_info.bodyBalanceLoyalty.balanceDTO:
    print(f"Redeemable Points: {balance.totalRedeemableBalance}")

Sources: mbbank/init.py:108-116

Summary

The Loyalty Points module provides a structured interface for querying user rewards data within the MBBank ecosystem. By utilizing Pydantic models like BalanceLoyaltyResponseModal, the library ensures that loyalty data (including redeemable balances and account statuses) is validated and easily accessible for both synchronous and asynchronous Python applications.