Transaction History
Relevant source files
The following files were used as context for generating this wiki page:
The Transaction History feature provides the capability to retrieve historical financial records for a specific MBBank account. This system allows users to query transactions within a defined date range, returning detailed information including amounts, descriptions, and account balances at the time of the transaction. It is integrated into both the synchronous (MBBank) and asynchronous (MBBankAsync) client implementations of the library.
Sources: mbbank/sync/mbbank.py:214-245, mbbank/aio/mbbank.py:215-245, examples/transaction_history.py:10-58
System Architecture
The transaction history functionality is built upon a request-response pattern using MBBank's internal REST API. It utilizes Pydantic models for data validation and standardizes the exchange of information between the MBBank servers and the library.
Core Components
| Component | Responsibility |
|---|---|
MBBank / MBBankAsync | Core client classes that provide the getTransactionAccountHistory method. |
Transaction | A Pydantic model defining the structure of an individual transaction record. |
TransactionHistoryResponseModal | A container model for the list of transactions returned by the API. |
MBBankAPI | The external endpoint: https://online.mbbank.com.vn/api/retail-transactionms/transactionms/get-account-transaction-history. |
Sources: mbbank/modals/transaction_history.py:1-41, mbbank/sync/mbbank.py:214-245, mbbank/aio/mbbank.py:215-245
Data Flow
The following sequence diagram illustrates the flow of data when requesting transaction history:
The system ensures that a valid session exists before making the request. If the sessionId is missing or expired (returning code GW200), the library automatically triggers a re-authentication flow.
Sources: mbbank/sync/mbbank.py:65-102, mbbank/aio/mbbank.py:164-213
Technical Implementation
Query Parameters
The getTransactionAccountHistory method accepts the following parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
accountNo | str | No | The specific account number. Defaults to the main account (userId). |
from_date | datetime.datetime | Yes | The start date of the query range. |
to_date | datetime.datetime | Yes | The end date of the query range. |
Note: The MBBank API imposes a maximum limit of 3 months for the date range query.
Sources: mbbank/sync/mbbank.py:236-238, mbbank/aio/mbbank.py:237-239
Transaction Data Model
Individual transactions are mapped to the Transaction class, which contains the following key fields:
| Field | Type | Description |
|---|---|---|
transactionDate | str | The date the transaction occurred. |
postingDate | str | The date the transaction was recorded in the system. |
creditAmount | str | The amount credited (incoming funds). |
debitAmount | str | The amount debited (outgoing funds). |
description | str | The primary transaction description or remark. |
availableBalance | str | The remaining balance after the transaction. |
refNo | str | Internal reference number for the transaction. |
benAccountName | str | Name of the beneficiary or sender. |
Sources: mbbank/modals/transaction_history.py:6-34
Implementation Example
The library supports both synchronous and asynchronous execution. Below is the standard synchronous usage for fetching the last 30 days of history:
import datetime
import mbbank
mb = mbbank.MBBank(username="user", password="pwd")
to_date = datetime.datetime.now()
from_date = to_date - datetime.timedelta(days=30)
history = mb.getTransactionAccountHistory(
accountNo="123456789",
from_date=from_date,
to_date=to_date
)
for transaction in history.transactionHistoryList:
print(f"{transaction.transactionDate}: {transaction.description}")
Sources: examples/transaction_history.py:10-58, mbbank/init.py:31-41
Error Handling
The system raises MBBankAPIError if the API response indicates a failure (where ok is False in the result object). Common issues include invalid session IDs (handled via automatic re-authentication) and network timeouts.
Sources: mbbank/sync/mbbank.py:96-102, mbbank/aio/mbbank.py:207-213
Summary
The Transaction History module provides a robust interface for accessing historical account data. By utilizing Pydantic models for response parsing and supporting dual-mode (sync/async) operations, it allows developers to integrate banking records into their applications while the library handles complex tasks like session management and data validation.