External Services
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
External Services within the MBBank library refer to specialized integration points and secondary API systems managed by MBBank that reside outside the core retail internet banking domain. These services facilitate specific operations such as retrieving ATM card metadata and generating dynamic identifiers required for advanced transaction workflows.
The library provides both synchronous and asynchronous implementations to interact with these services, primarily through the getServiceToken and getATMCardID mechanisms. These allow the library to bridge the gap between standard account management and specialized card-related queries.
Sources: mbbank/sync/mbbank.py, mbbank/aio/mbbank.py
Authentication and Service Tokens
Before accessing certain external endpoints, the system must obtain a dedicated service token. This token differs from the standard session identifier used for retail banking operations and is required for specific sub-domains like mbcard.mbbank.com.vn.
Service Token Acquisition
The library retrieves a service token using the getServiceToken() method. This method ensures the user is authenticated before calling the internal getServiceToken endpoint. The resulting token is encapsulated in a ServiceTokenResponseModal, which contains the token string and its authorization type (typically used as a Bearer or similar header prefix).
Sources: mbbank/sync/mbbank.py:186-198, mbbank/aio/mbbank.py:440-452
Service Token Data Structure
| Field | Type | Description |
|---|---|---|
token | str | The actual authentication token for external service usage. |
type | str | The type of token (e.g., used for the Authorization header). |
refNo | str | Reference number for the request. |
Sources: mbbank/modals/base.py:43-48
ATM Card Services
The library interacts with external card gateways to perform inquiries on ATM cards. This is primarily handled via the mbcardgw gateway.
ATM Card ID Generation
To perform detailed inquiries on a physical card number, the system must first generate a unique cardID. This is achieved by calling the generateid endpoint on the external host https://mbcard.mbbank.com.vn:8446.
The sequence above illustrates the dependency on the service token to authorize requests against the external card gateway.
Sources: mbbank/sync/mbbank.py:382-411, mbbank/aio/mbbank.py:534-563
ATM Account Name Inquiry
A high-level feature of the external services module is resolving a card number to an account name. This involves a multi-step process:
- ID Generation: Retrieving the
cardIDfrom the external gateway. - Bank Identification: Matching the card's prefix (
smlCode) against the bank list. - Inquiry: Submitting the inquiry to the retail transfer endpoint using the external
cardID.
Sources: mbbank/sync/mbbank.py:413-460, mbbank/aio/mbbank.py:565-612
Data Models and Architecture
Class Relationship Diagram
The following diagram describes how external service models relate to the base response structures.
This hierarchy ensures that all responses from external services maintain a consistent reference number for tracking and logging.
Sources: mbbank/modals/base.py:8-13, mbbank/modals/external_service.py
External Endpoint Reference
| Endpoint Purpose | URL | Method |
|---|---|---|
| Service Token | .../api/retail_web/common/getServiceToken | POST |
| Card ID Generation | https://mbcard.mbbank.com.vn:8446/mbcardgw/internet/cardinfo/v1_0/generateid | POST |
| Card Inquiry | .../api/retail_web/transfer/inquiryAccountName | POST |
Sources: mbbank/sync/mbbank.py:194, 401, 451, mbbank/aio/mbbank.py:449, 553, 603
Conclusion
External Services in the MBBank library provide the necessary infrastructure to handle card-specific operations that are not covered by standard retail API endpoints. By implementing a dual-token authentication system and integrating with the mbcardgw gateway, the library enables developers to perform complex tasks like ATM card identification and account resolution across different banking sub-systems.