Card Transactions
Relevant source files
The following files were used as context for generating this wiki page:
The Card Transactions module provides the infrastructure for retrieving and modeling historical transaction data associated with MBBank payment cards. It enables users to query specific cards for transaction history within a defined date range, supporting both synchronous and asynchronous execution flows. This module is a subset of the broader account management features, allowing for detailed auditing of card-specific debits and credits.
This feature interacts closely with the Card List and User Information modules to identify valid card numbers and authenticate requests.
Data Models
The system uses Pydantic-based models to ensure type safety and structured validation of API responses.
CardTransaction Model
Represents a single financial entry in a card's history.
| Field | Type | Description |
|---|---|---|
postingDate | str | The date the transaction was officially posted. |
transactionDate | str | The date the transaction occurred. |
accountNo | str | The card number associated with the transaction. |
creditAmount | str | Amount credited to the card. |
debitAmount | str | Amount debited from the card. |
currency | str | Currency code (e.g., VND). |
description | str | Transaction narrative or memo. |
availableBalance | Optional[str] | Balance remaining after the transaction. |
refNo | Optional[str] | Reference number for the transaction. |
Sources: mbbank/modals/card_transactions.py:7-24
CardTransactionsResponseModal
The container for the list of transactions returned by the MBBank API.
| Field | Type | Description |
|---|---|---|
transactionHistoryList | List[CardTransaction] | Collection of transaction records. |
result | Result (inherited) | Status of the API request (ok/error). |
Sources: mbbank/modals/card_transactions.py:27-30
Request Flow and Implementation
Retrieving card transactions requires an authenticated session and a valid card number, which is typically obtained via the getCardList method.
Request Logic
The request is sent to the getTransactionHistory endpoint with a JSON payload specifying the date range and type.
The system mandates a type of "CARD" and a historyType of "DATE_RANGE" when querying card-specific data.
Sources: mbbank/sync/mbbank.py:344-365, mbbank/aio/mbbank.py:356-377
Implementation Methods
The library provides two primary methods for accessing transaction data:
- Synchronous:
MBBank.getCardTransactionHistory(cardNo, from_date, to_date)
Sources: mbbank/sync/mbbank.py:344 - Asynchronous:
MBBankAsync.getCardTransactionHistory(cardNo, from_date, to_date)
Sources: mbbank/aio/mbbank.py:356
Endpoint Configuration
The API interactions utilize the following parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
accountNo | str | Yes | The card number (Card ID). |
fromDate | str | Yes | Format: dd/mm/yyyy. |
toDate | str | Yes | Format: dd/mm/yyyy (Max 3 months range). |
historyType | str | Yes | Fixed as "DATE_RANGE". |
type | str | Yes | Fixed as "CARD". |
Sources: mbbank/sync/mbbank.py:361-368
Class Relationships
The following diagram illustrates the relationship between the card models and the transaction models.
Usage Overview
To successfully fetch card transactions, developers must first identify the card number from the user's profile.
- Retrieve Cards: Call
getCardList()to find availablecardNovalues.
Sources: mbbank/sync/mbbank.py:321 - Define Range: Transactions are limited to a maximum range of 3 months per request.
Sources: mbbank/sync/mbbank.py:363 - Execute Query: The resulting
CardTransactionsResponseModalprovides a validated list ofCardTransactionobjects.
Sources: mbbank/modals/card_transactions.py:27
The Card Transactions module serves as a critical component for monitoring card usage, providing a structured and validated interface to the MBBank transaction records. It abstracts the complexities of the underlying API, such as specific date formatting and internal type flags, into a standard Pythonic interface.