Synchronous Client
Relevant source files
The following files were used as context for generating this wiki page:
The Synchronous Client provides a blocking, easy-to-use interface for interacting with Military Commercial Joint Stock Bank (MBBank) personal accounts. It is built using the requests library to handle HTTP communications and follows a standard imperative programming model, making it suitable for simple scripts, command-line tools, or legacy applications that do not utilize Python's asyncio ecosystem.
The core of this module is the MBBank class, which manages session states, authentication challenges (including CAPTCHA and biometric checks), and data encryption required by the MBBank retail banking API. It works in conjunction with specialized context managers like TransferContext to facilitate complex operations such as fund transfers.
Sources: mbbank/sync/mbbank.py:53-73, mbbank/init.py:12-23
Architecture and Core Components
The synchronous client is structured around a base class that defines shared constants and utilities, with a concrete implementation that handles the blocking request logic.
Class Hierarchy
The following diagram illustrates the relationship between the synchronous implementation and the base banking logic.
Core Initialization Parameters
When instantiating the MBBank client, several parameters control its behavior:
| Parameter | Type | Description | Default |
|---|---|---|---|
username | str | MBBank Account Username | Required |
password | str | MBBank Account Password | Required |
proxy | str | Proxy URL (e.g., "http://127.0.0.1:8080") | None |
ocr_class | CapchaProcessing | Instance for CAPTCHA solving | CapchaOCR() |
retry_times | int | Max attempts for CAPTCHA processing | 30 |
timeout | Union[float, tuple] | Request timeout in seconds | None |
Sources: mbbank/sync/mbbank.py:65-71, mbbank/base/mbbank.py:62-65
Authentication Flow
Authentication is a multi-step process involving CAPTCHA retrieval, OCR processing, and WASM-based payload encryption.
Login Sequence
The _authenticate method handles the lifecycle of a session. If a request fails with a GW200 (Session Expired) or GW283 (Invalid Captcha) code, the client automatically triggers this flow.
Request Security
All sensitive requests use a deviceIdCommon generated during initialization using the pattern abi2jojr-mbib-0000-0000-{timestamp}. Furthermore, specific endpoints require the encrypt=True flag, which invokes a WebAssembly-based encryption routine (wasm_encrypt) to process the JSON body before transmission.
Sources: mbbank/base/mbbank.py:74, mbbank/sync/mbbank.py:91-115
Banking Operations
The client provides synchronous methods for various banking services, returning Pydantic models for type-safe data access.
Account Management
getBalance(): Retrieves all main and sub-account balances.getTransactionAccountHistory(...): Fetches history for a specific account. Note: date ranges are restricted to a maximum of 3 months.userinfo(): Provides detailed profile information, including customer ID and associated menu permissions.
Specialized Services
getBankList(): Fetches a list of supported banks for domestic transfers. This method implements internal caching viaself._tempto minimize redundant API calls.getATMCardID(cardNumber): A two-step process that first retrieves aServiceTokenand then calls thembcardgwgateway to resolve an internal ID for ATM card transfers.
Sources: mbbank/sync/mbbank.py:192-212, mbbank/sync/mbbank.py:318-335, mbbank/sync/mbbank.py:382-411
Fund Transfer System
The TransferContext class manages the state of an account-to-account transfer, which requires multiple verification and authentication steps.
Sources: mbbank/sync/transfer.py:53-200
Transfer Lifecycle Methods
start(): Orchestrates the initial lookup of the destination bank and account holder name.get_qr_code(): Generates a string in the formatTRANID|{auth_id}. This is typically used to generate a QR code for the user to scan with their physical MBBank app to generate an OTP.transfer(otp, auth_type): The final execution step. It "crafts" the OTP (using_craft_otplogic from the base class) and submits the finalized transfer request.
Sources: mbbank/sync/transfer.py:151-200, mbbank/sync/mbbank.py:441-460
Summary
The Synchronous Client serves as the primary gateway for developers seeking a straightforward implementation of the MBBank API. By encapsulating session management, WASM-based security, and automatic CAPTCHA retries, it allows for complex banking operations like fund transfers and history retrieval with minimal boilerplate code. All responses are validated against structured modals, ensuring data integrity across the various retail and card-management API endpoints.
Sources: mbbank/sync/mbbank.py:1-40, mbbank/sync/transfer.py:20-50