Money Transfers

Relevant source files

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

• mbbank/base/transfer.py
• mbbank/modals/transfer.py
• examples/transfer_money.py
• mbbank/sync/transfer.py
• mbbank/aio/transfer.py
• mbbank/sync/mbbank.py
• mbbank/aio/mbbank.py

The Money Transfers module in the MBBank library provides a structured interface for performing financial transactions between accounts. It supports both synchronous and asynchronous operations, managing the multi-step process required by the Military Commercial Joint Stock Bank (MBBank) API, including bank lookup, account name inquiry, transaction verification, and OTP-based authentication.

The system uses a "Context" pattern (via TransferContext and TransferContextAsync) to maintain state throughout the lifecycle of a single transfer. This state includes source/destination details, generated transaction IDs, and timestamps required for secure request crafting.
Sources: mbbank/sync/transfer.py, mbbank/aio/transfer.py

Transfer Architecture and Workflow

The transfer process is divided into several stages to ensure security and accuracy. It begins with identifying the destination bank and account, followed by a verification step, and concludes with an authenticated execution.

Transfer Lifecycle Flow

The following diagram illustrates the standard sequence of operations when performing a transfer:

Core Components

Component	Description	File Path
TransferContextBase	Base class containing shared attributes like amount, src_account, and message.	mbbank/base/transfer.py:12-42
TransferContext	Synchronous manager for handling the transfer lifecycle.	mbbank/sync/transfer.py:23-56
TransferContextAsync	Asynchronous manager for handling the transfer lifecycle.	mbbank/aio/transfer.py:23-57
TransferResponseModal	Data model for responses from verification and execution endpoints.	mbbank/modals/transfer.py:14-41

Execution Logic

Initialization and Verification

A transfer is initiated using the makeTransferAccountToAccount method on the main MBBank or MBBankAsync class. This creates a context and automatically calls start(), which performs the initial bank lookup and account name inquiry.
Sources: mbbank/sync/mbbank.py:383-404, mbbank/aio/mbbank.py:408-430

Authentication Handling

The library supports multiple authentication methods (e.g., Digital OTP, SMS). Users must retrieve the available methods and provide a code which is then "crafted" into a specific format required by the MBBank API.

The _craft_otp method combines the OTP, authentication type, timestamp, and transaction ID:

def _craft_otp(self, otp: str, auth_type: AuthListItem) -> str:
    return f"ibr|{auth_type.code}||{otp}||{self.timestamp}|{self.transaction_authen.id}|{self.refNo}"

Sources: mbbank/base/transfer.py:65-75

Sequence Diagram: Transaction Execution

This diagram shows the interaction between the client application and the library during a transfer.

Data Models

Transaction Authentication

The system uses a TransactionAuthen model to track the specific ID assigned to a transfer before it is finalized.

Field	Type	Description
id	str	The internal transaction ID.
custId	str	The customer identifier.
amount	str	The amount to be transferred.
destAccountName	str	The confirmed name of the recipient.
Sources: mbbank/modals/transfer.py:57-78

Transfer Parameters

When calling the API endpoints (e.g., /make-transfer), the following JSON structure is typically encrypted and sent:

• srcAccountNumber: Source account number.
• benAccountNumber: Beneficiary account number.
• benBankCd: Destination bank code (e.g., "MB").
• amount: Transaction amount.
• otp: The crafted OTP string.
  Sources: mbbank/sync/transfer.py:141-151, mbbank/aio/transfer.py:143-153

Error Handling

Common errors encountered during money transfers include:

• BankNotFoundError: Raised if the provided bank_code does not exist in the bank list.
• MBBankError: Raised if methods like transfer() are called out of order (e.g., before get_qr_code()).
• MBBankAPIError: Raised when the bank API returns an unsuccessful result code.
  Sources: mbbank/sync/transfer.py:71-72, mbbank/aio/transfer.py:123-125

Summary

The Money Transfer system is a multi-stage workflow managed through a context object. It abstracts the complexities of the MBBank API by automating account inquiry and providing utility methods for OTP crafting and transaction verification, ensuring that transfers are both secure and valid before final execution.