Card Management

Relevant source files

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

• mbbank/modals/card_list.py
• mbbank/modals/card_transactions.py
• mbbank/sync/mbbank.py
• mbbank/aio/mbbank.py
• mbbank/modals/userinfo.py
• examples/card_list.py

Introduction

Card Management in the MBBank library provides developers with the tools to retrieve card details, monitor card status, and access transaction histories for debit and credit cards associated with an MBBank account. The system interfaces with MBBank's internal APIs to provide a structured representation of card data, categorized by active, closed, or other states.

Sources: mbbank/modals/card_list.py, mbbank/sync/mbbank.py:284-294

The module supports both synchronous and asynchronous operations through the MBBank and MBBankAsync classes, allowing for integration into various application architectures. It utilizes Pydantic models to ensure type safety and structured data handling for complex card attributes like credit limits, internet usage status, and primary card associations.

Sources: mbbank/sync/mbbank.py:284-294, mbbank/aio/mbbank.py:307-317

Architecture and Data Flow

The Card Management module follows a request-response pattern where the library authenticates the session and then queries specific card-related endpoints.

Request Flow

The system ensures that a valid sessionId exists before dispatching requests to the card service. If the session is invalid or expired (indicated by a "GW200" response code), the library automatically re-authenticates using the provided credentials and CAPCHA processing.

Sources: mbbank/sync/mbbank.py:84-118, mbbank/sync/mbbank.py:284-294

Class Relationship

The following diagram illustrates the relationship between the core API clients and the data models used for card management.

Data Models

Card Details

The Card model is the primary data structure representing a physical or virtual card. It contains comprehensive metadata returned by the MBBank API.

Field	Type	Description
cardNo	str	The unique identifier/number of the card.
cardNm	Optional[str]	The name printed on the card or assigned to it.
cardTyp	Optional[str]	The category of the card (e.g., DEBIT, CREDIT).
stsCard	Optional[str]	The current operational status of the card.
creditLmt	Optional[int]	The maximum credit limit allowed (for credit cards).
stsInetUsage	Optional[str]	Status of internet/online usage permissions.
cardLvl	Optional[str]	The tier or level of the card (e.g., PLATINUM, GOLD).

Sources: mbbank/modals/card_list.py:7-38

Card Transactions

Transaction history for specific cards is handled through the CardTransaction model, which provides granular detail on individual entries.

Field	Type	Description
transactionDate	str	The date the transaction was initiated.
postingDate	str	The date the transaction was officially posted to the account.
creditAmount	str	Amount credited to the card.
debitAmount	str	Amount debited from the card.
description	str	Detailed description or memo of the transaction.

Sources: mbbank/modals/card_transactions.py:7-23

Key Functions and API Endpoints

Retrieving Card Lists

The library provides two primary methods for obtaining card information depending on the desired detail level:

1. getCardList(): Queries the dedicated card management endpoint. This returns a CardListResponseModal which separates cards into cardList (active), cardClosed, and cardOther.

   • Endpoint: https://online.mbbank.com.vn/api/retail_web/card/getList
   • Sources: mbbank/sync/mbbank.py:293, mbbank/modals/card_list.py:41-46

2. userinfo(): Includes a cardList dictionary within the CustModel as part of the broader user profile.

   • Endpoint: https://online.mbbank.com.vn/api/retail_web/internetbanking/v2.0/doLogin (cached after login)
   • Sources: mbbank/modals/userinfo.py:175, mbbank/sync/mbbank.py:483-494

Card Transaction History

The getCardTransactionHistory method allows for date-ranged queries of transactions for a specific card.

def getCardTransactionHistory(
    self, 
    cardNo: str, 
    from_date: datetime.datetime, 
    to_date: datetime.datetime
) -> CardTransactionsResponseModal:

• Logic: The method formats dates as dd/mm/yyyy and sets the type parameter to "CARD". It supports a maximum range of 3 months per request.
• Endpoint: https://online.mbbank.com.vn/api/retail_web/common/getTransactionHistory
• Sources: mbbank/sync/mbbank.py:339-366

Implementation Example

The following example demonstrates how to retrieve and display card information using the synchronous API.

import mbbank

mb = mbbank.MBBank(username="user", password="pass")
cards_response = mb.getCardList()

for card in cards_response.cardList:
    print(f"Number: {card.cardNo} | Type: {card.cardTyp} | Status: {card.stsCard}")

Sources: examples/card_list.py:22-35

Conclusion

Card Management within the MBBank library provides a robust interface for accessing sensitive card data. By abstracting the underlying REST API and handling session maintenance, encryption, and data validation via Pydantic, the module enables secure and efficient integration of MBBank card services into third-party Python applications.