shihaam/thijooree
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases 8 Wiki Activity

Compare commits

base: shihaam:v1.0.8
Branches Tags
shihaam:main
shihaam:v1.0.8 shihaam:v1.0.7 shihaam:v1.0.6 shihaam:v1.0.5 shihaam:v1.0.4 shihaam:v1.0.3 shihaam:v1.0.2 shihaam:v1.0 shihaam:v1.0.1
..
compare: shihaam:main
Branches Tags
shihaam:main
shihaam:v1.0.8 shihaam:v1.0.7 shihaam:v1.0.6 shihaam:v1.0.5 shihaam:v1.0.4 shihaam:v1.0.3 shihaam:v1.0.2 shihaam:v1.0 shihaam:v1.0.1

8 Commits
v1.0.8 ... main

Author SHA1 Message Date
Shihaam Abdul Rahman
ea227bf3b9 impprove ci performance
All checks were successful
Auto Tag on Version Change / check-version (push) Successful in 5s
Details
2026-05-24 00:29:40 +05:00
Shihaam Abdul Rahman
6b3131069e update docs
All checks were successful
Auto Tag on Version Change / check-version (push) Successful in 6s
Details
2026-05-24 00:27:59 +05:00
Shihaam Abdul Rahman
8037ce3f02 Merge pull request 'add product group mapping for cards' (#4) from fix/bmlapi-card-parser-add-missing-product-groups into main
All checks were successful
Auto Tag on Version Change / check-version (push) Successful in 4s
Details 
Reviewed-on: #4
 2026-05-24 00:04:47 +05:00
WovenCoast
cecf0bedfc add product group mapping for cards 2026-05-23 23:56:15 +05:00
Shihaam Abdul Rahman
256f216da4 update docs
All checks were successful
Auto Tag on Version Change / check-version (push) Successful in 4s
Details
2026-05-23 23:46:00 +05:00
Shihaam Abdul Rahman
0a27de4a34 update bml api docs
All checks were successful
Auto Tag on Version Change / check-version (push) Successful in 5s
Details
2026-05-23 23:33:31 +05:00
Shihaam Abdul Rahman
a3f8852163 some android studio bs
All checks were successful
Auto Tag on Version Change / check-version (push) Successful in 6s
Details
2026-05-23 23:13:07 +05:00
Shihaam Abdul Rahman
8e345746ed pending finaces on dashboard is now a button that takes you to finaces page 2026-05-23 23:12:50 +05:00
39 changed files with 3966 additions and 1759 deletions
Expand all files Collapse all files

4
.build/release/compose.yml
View File

@@ -1,11 +1,9 @@
services: services:
release: release:
# image: git.shihaam.dev/dockerfiles/android-builder
image: git.shihaam.dev/dockerfiles/runners/gradle image: git.shihaam.dev/dockerfiles/runners/gradle
hostname: isodroid
network_mode: host network_mode: host
env_file: .env env_file: .env
volumes: volumes:
- ./release:/release - ./release:/release
- ../../:/source - ../../:/source
# - /root/.cache/cache-runners/gradle:/root/.gradle - /root/.cache/cache-runners/gradle:/root/.gradle

8
.idea/markdown.xml generated Normal file
View File

@@ -0,0 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<project version="4">
<component name="MarkdownSettings">
<option name="previewPanelProviderInfo">
<ProviderInfo name="Compose (experimental)" className="com.intellij.markdown.compose.preview.ComposePanelProvider" />
</option>
</component>
</project>

4
app/src/main/java/sh/sar/basedbank/ui/home/DashboardFragment.kt
View File

@@ -53,6 +53,10 @@ class DashboardFragment : Fragment() {
binding.swipeRefresh.isRefreshing = false binding.swipeRefresh.isRefreshing = false
} }
binding.cardPendingFinances.setOnClickListener {
(activity as? HomeActivity)?.navigateTo(R.id.nav_finances)
}
val cardAdapter = DashboardCardAdapter() val cardAdapter = DashboardCardAdapter()
binding.rvCards.layoutManager = LinearLayoutManager(requireContext(), LinearLayoutManager.HORIZONTAL, false) binding.rvCards.layoutManager = LinearLayoutManager(requireContext(), LinearLayoutManager.HORIZONTAL, false)
binding.rvCards.adapter = cardAdapter binding.rvCards.adapter = cardAdapter

57
app/src/main/java/sh/sar/basedbank/util/bmlapi/BmlCardParser.kt
View File

@@ -12,35 +12,34 @@ object BmlCardParser {
productCodeToAsset(account.productCode) productCodeToAsset(account.productCode)
fun productCodeToAsset(productCode: String): String = when (productCode) { fun productCodeToAsset(productCode: String): String = when (productCode) {
"C8201" -> "cards/bml/master_prepaid.png" "C8201", "C8001", "C8009" -> "cards/bml/master_prepaid.png"
"C8205" -> "cards/bml/master_prepaid_travel.png" "C8205", "C8005", "C8008" -> "cards/bml/master_prepaid_travel.png"
"C8005" -> "cards/bml/master_prepaid_travel.png" "C3007", "C3017", "C3097", "C3095", "C3077", "C3177" -> "cards/bml/amex_debit_green.png"
"C3007" -> "cards/bml/amex_debit_green.png" "C3003", "C3013", "C3053", "C3023", "C3033", "C3052" -> "cards/bml/amex_debit_gold.png"
"C1007" -> "cards/bml/visa_debit.png" "C3009", "C3019", "C3029", "C3099", "C3088", "C3188" -> "cards/bml/amex_credit_gold.png"
"C1003" -> "cards/bml/visa_gold.png" "C3001", "C3011", "C3050", "C3051", "C3031" -> "cards/bml/amex_credit_green.png"
"C8022" -> "cards/bml/master_gold.png" "C3005", "C3015", "C3055", "C3054" -> "cards/bml/amex_platinum.png"
"C1020" -> "cards/bml/visa_debit_platinum.png" "C1003", "C1013", "C1083", "C1084", "C1103", "C1113", "C1183", "C1184" -> "cards/bml/visa_gold.png"
"C8902" -> "cards/bml/master_islamic.png" "C1007", "C1027", "C1097", "C1107", "C1197", "C1077", "C1177" -> "cards/bml/visa_debit.png"
"C1020", "C1021" -> "cards/bml/visa_debit_platinum.png"
"C8020", "C8022" -> "cards/bml/master_gold.png"
"C8902", "C8907", "C8909", "C8912", "C8992", "C8996", "C8997", "C8982", "C8983" -> "cards/bml/master_islamic.png"
"C8101" -> "cards/bml/master_masveriyaa.png" "C8101" -> "cards/bml/master_masveriyaa.png"
// "?????" -> "cards/bml/amex_credit_gold.png" "C8102" -> "cards/bml/master_odiveriyaa.png"
// "?????" -> "cards/bml/amex_credit_green.png" "C8010", "C8011" -> "cards/bml/master_platinum.png"
// "?????" -> "cards/bml/amex_debit_gold.png" "C8040", "C8044" -> "cards/bml/master_world.png"
// "?????" -> "cards/bml/amex_platinum.png" "C8030", "C8033" -> "cards/bml/master_business_debit.png"
// "?????" -> "cards/bml/master.png" "C8901", "C8991", "C8980", "C8981" -> "cards/bml/master_passport.png"
// "?????" -> "cards/bml/master_business_debit.png" "C1030", "C1090", "C1130", "C1033", "C1133" -> "cards/bml/visa_corporate.png"
// "?????" -> "cards/bml/master_odiveriyaa.png" "C8905", "C8995" -> "cards/bml/visa_credit.png"
// "?????" -> "cards/bml/master_passport.png" "C1001", "C1011", "C1082", "C1081", "C1101", "C1111", "C1181", "C1182" -> "cards/bml/visa_debit_generic.png"
// "?????" -> "cards/bml/master_platinum.png" "C1005", "C1006", "C1089" -> "cards/bml/visa_debit_islamic.png"
// "?????" -> "cards/bml/master_prepaid_business.png" "C1017" -> "cards/bml/visa_infinite.png"
// "?????" -> "cards/bml/master_world.png" "C1009", "C1019", "C1085", "C1086", "C1109", "C1119", "C1185", "C1186" -> "cards/bml/visa_platinum.png"
// "?????" -> "cards/bml/visa_corporate.png" "C1050", "C1051", "C1087", "C1088", "C1150", "C1151", "C1187", "C1188", "C1040", "C1041", "C1047", "C1048", "C1140", "C1141", "C1147", "C1148" -> "cards/bml/visa_student_black.png"
// "?????" -> "cards/bml/visa_credit.png" "C8925", "C8926" -> "cards/bml/visa_student_blue.png"
// "?????" -> "cards/bml/visa_debit_generic.png" "C1071", "C1073", "C1061", "C1063", "C1161", "C1163" -> "cards/bml/master.png"
// "?????" -> "cards/bml/visa_debit_islamic.png" "C1070", "C1072", "C1059", "C1062", "C1159", "C1162" -> "cards/bml/master_prepaid_business.png"
// "?????" -> "cards/bml/visa_infinite.png" else -> "cards/bml/defaultcard.png"
// "?????" -> "cards/bml/visa_platinum.png"
// "?????" -> "cards/bml/visa_student_black.png"
// "?????" -> "cards/bml/visa_student_blue.png"
else -> "cards/bml/defaultcard.png"
} }
} }

5
app/src/main/res/layout/fragment_dashboard.xml
View File

@@ -178,11 +178,14 @@
<!-- Pending Finances card --> <!-- Pending Finances card -->
<com.google.android.material.card.MaterialCardView <com.google.android.material.card.MaterialCardView
android:id="@+id/cardPendingFinances"
android:layout_width="match_parent" android:layout_width="match_parent"
android:layout_height="wrap_content" android:layout_height="wrap_content"
android:layout_marginTop="16dp" android:layout_marginTop="16dp"
app:cardElevation="1dp" app:cardElevation="1dp"
app:cardCornerRadius="12dp"> app:cardCornerRadius="12dp"
android:clickable="true"
android:focusable="true">
<LinearLayout <LinearLayout
android:layout_width="match_parent" android:layout_width="match_parent"

8
docs/AI_SECURITY_CHECK.md
View File

@@ -187,15 +187,15 @@ The app presents different identities to different backends, which is intentiona
| Backend | User-Agent sent | | Backend | User-Agent sent |
|---|---| |---|---|
| MIB API | `android/1.0` | | MIB API | `android/1.0` |
| MIB WebView | `Mozilla/5.0 (Linux; Android 14; wv) AppleWebKit/537.36 ... Mobile Safari/537.36` | | MIB WebView | `Mozilla/5.0 (Linux; Android {version}; wv) AppleWebKit/537.36 ... Mobile Safari/537.36` |
| BML web steps | `Mozilla/5.0 (X11; Linux x86_64; rv:150.0) Gecko/20100101 Firefox/150.0` | | BML web steps | `Mozilla/5.0 (X11; Linux x86_64; rv:150.0) Gecko/20100101 Firefox/150.0` |
| BML API calls | `bml-mobile-banking/345 (POCO; Android 14; 22101320I)` | | BML API calls | `bml-mobile-banking/345 (POCO; Android {version}; {model})` |
| Fahipay login/OTP | WebView UA with actual `Build.MODEL` | | Fahipay login/OTP | WebView UA with actual `Build.MODEL` |
| Fahipay API calls | `okhttp/4.12.0` | | Fahipay API calls | `okhttp/4.12.0` |
| Ooredoo | No custom UA | | Ooredoo | No custom UA |
| Dhiraagu | `Mozilla/5.0 (X11; Linux x86_64; rv:150.0) Gecko/20100101 Firefox/150.0` | | Dhiraagu | `Mozilla/5.0 (X11; Linux x86_64; rv:150.0) Gecko/20100101 Firefox/150.0` |
The BML API User-Agent hardcodes a specific device model (`POCO; Android 14; 22101320I`) to mimic the official BML mobile app. This is required for the API to accept requests. The BML API User-Agent hardcodes a specific device model (`POCO; Android {version}; {model}`) to mimic the official BML mobile app. This is required for the API to accept requests.
The Fahipay login includes `Build.MODEL` and `Build.MANUFACTURER` from the actual device, sent as `device[model]` and `device[manufacturer]` form fields. This is a **device fingerprint** sent to Fahipay on every login. The Fahipay login includes `Build.MODEL` and `Build.MANUFACTURER` from the actual device, sent as `device[model]` and `device[manufacturer]` form fields. This is a **device fingerprint** sent to Fahipay on every login.
@@ -327,7 +327,7 @@ All hardcoded values in this codebase are protocol constants extracted from reve
| `P = BigInteger("2410312426921...")` | `MibCrypto.kt:17` | MIB DH prime modulus. Same value as in the official app. | Public parameter — no risk. | | `P = BigInteger("2410312426921...")` | `MibCrypto.kt:17` | MIB DH prime modulus. Same value as in the official app. | Public parameter — no risk. |
| `CLIENT_ID = "98C83590-513F-4716-B02B-EC68B7D9E7E7"` | `BmlLoginFlow.kt:30` | BML OAuth client ID, extracted from the official BML mobile app APK. | Not a personal secret — it is the same value for all BML mobile clients. | | `CLIENT_ID = "98C83590-513F-4716-B02B-EC68B7D9E7E7"` | `BmlLoginFlow.kt:30` | BML OAuth client ID, extracted from the official BML mobile app APK. | Not a personal secret — it is the same value for all BML mobile clients. |
| `REDIRECT_URI = "https://app.bankofmaldives.com.mv/oauth/mobile-callback"` | `BmlLoginFlow.kt:31` | BML OAuth redirect URI, must match what BML's server expects. | Fixed protocol value. | | `REDIRECT_URI = "https://app.bankofmaldives.com.mv/oauth/mobile-callback"` | `BmlLoginFlow.kt:31` | BML OAuth redirect URI, must match what BML's server expects. | Fixed protocol value. |
| `APP_USER_AGENT = "bml-mobile-banking/345 (POCO; Android 14; 22101320I)"` | `BmlLoginFlow.kt:32` | Impersonates the official BML app and a specific POCO device model. | Intentional compatibility measure; no personal data. | | `APP_USER_AGENT = "bml-mobile-banking/345 (POCO; Android {version}; {model})"` | `BmlLoginFlow.kt:32` | Impersonates the official BML app and a specific POCO device model. | Intentional compatibility measure; no personal data. |
| `APP_VERSION = "2.1.43.345"` | `BmlLoginFlow.kt:33` | BML app version string being impersonated. | Fixed protocol value. | | `APP_VERSION = "2.1.43.345"` | `BmlLoginFlow.kt:33` | BML app version string being impersonated. | Fixed protocol value. |
| `website_id = "CA2BB809-3A22-485B-A518-DA6B6DE653A5"` | `DhiraaguClient.kt:45` | Dhiraagu SDK identifier embedded in the lookup URL. Extracted from Dhiraagu's public Easy Pay page. | Public value embedded in their web page; not a secret. | | `website_id = "CA2BB809-3A22-485B-A518-DA6B6DE653A5"` | `DhiraaguClient.kt:45` | Dhiraagu SDK identifier embedded in the lookup URL. Extracted from Dhiraagu's public Easy Pay page. | Public value embedded in their web page; not a secret. |
| `MIB_SWIFT_ON_BML = "F4E79935-3E73-E611-80DD-00155D020F0A"` | `AddContactSheetFragment.kt:457` | BML's internal bank code (SWIFT/FinInstnId) used to identify MIB as the counterpart bank during BML transfers. | Protocol constant, not a secret. | | `MIB_SWIFT_ON_BML = "F4E79935-3E73-E611-80DD-00155D020F0A"` | `AddContactSheetFragment.kt:457` | BML's internal bank code (SWIFT/FinInstnId) used to identify MIB as the counterpart bank during BML transfers. | Protocol constant, not a secret. |

256
docs/bmlapi/01-login.md Normal file
View File

@@ -0,0 +1,256 @@
# Login
Authenticate a user through the BML web session flow. This involves four sequential HTTP steps before OAuth can begin: seeding cookies, posting credentials, verifying TOTP, and selecting a profile.
All requests in this flow use the **web User-Agent** and a shared cookie jar that persists cookies (`XSRF-TOKEN`, `blaze_session`, `blaze_identity`) across steps.
---
## Step 1 — Seed Session Cookies
```
GET https://www.bankofmaldives.com.mv/internetbanking/web/login
```
This request initialises the session. The server sets the `XSRF-TOKEN` and `blaze_session` cookies which must be carried through the entire login flow.
### Request
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/web/login' \
--header 'User-Agent: Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0'
```
### Response
`200 OK` — HTML page. The cookies set in the response headers are the only output needed:
```
Set-Cookie: XSRF-TOKEN=<token>; Path=/; SameSite=Lax
Set-Cookie: blaze_session=<session>; Path=/; HttpOnly; SameSite=Lax
```
Extract `XSRF-TOKEN` from the cookie store for use in Step 2.
---
## Step 2 — Submit Credentials
```
POST https://www.bankofmaldives.com.mv/internetbanking/web/login
```
### Request
**Content-Type:** `application/json`
```json
{
"username": "A123456",
"password": "your_password",
"code": ""
}
```
| Field | Notes |
|---|---|
| `username` | BML online banking username (typically the national ID card number) |
| `password` | Online banking password |
| `code` | Always empty string `""` at this step |
**Headers:**
| Header | Value |
|---|---|
| `X-XSRF-TOKEN` | Value of the `XSRF-TOKEN` cookie from Step 1 |
| `Content-Type` | `application/json` |
| `User-Agent` | `Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0` |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/web/login' \
--header 'Content-Type: application/json' \
--header 'User-Agent: Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--header 'X-XSRF-TOKEN: <xsrf_token>' \
--cookie 'XSRF-TOKEN=<xsrf_token>; blaze_session=<session>' \
--data '{"username":"A123456","password":"your_password","code":""}'
```
### Response
**Success:** `302` redirect to `/web/login/2fa`. The `blaze_session` cookie is updated.
**Failure:** Any non-`302` response (typically `200` with the login page re-rendered) means the credentials were rejected.
---
## Step 3 — Fetch 2FA Page
```
GET https://www.bankofmaldives.com.mv/internetbanking/web/login/2fa
```
This request refreshes the `XSRF-TOKEN` cookie for the TOTP submission in Step 4. The response body is an HTML page that can be discarded.
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/web/login/2fa' \
--header 'User-Agent: Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--cookie 'XSRF-TOKEN=<xsrf_token>; blaze_session=<session>'
```
Extract the fresh `XSRF-TOKEN` from the updated cookie store before Step 4.
---
## Step 4 — Submit TOTP
```
POST https://www.bankofmaldives.com.mv/internetbanking/web/login/2fa
```
### Request
**Content-Type:** `application/json`
```json
{
"code": "123456",
"channel": "authenticator"
}
```
| Field | Value | Notes |
|---|---|---|
| `code` | `123456` | 6-digit TOTP from the user's authenticator app |
| `channel` | `authenticator` | Always `authenticator` for TOTP |
**Headers:**
| Header | Value |
|---|---|
| `X-XSRF-TOKEN` | Fresh value from Step 3 |
| `Content-Type` | `application/json` |
| `User-Agent` | Web UA |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/web/login/2fa' \
--header 'Content-Type: application/json' \
--header 'User-Agent: Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--header 'X-XSRF-TOKEN: <xsrf_token_2>' \
--cookie 'XSRF-TOKEN=<xsrf_token_2>; blaze_session=<session>' \
--data '{"code":"123456","channel":"authenticator"}'
```
### Response
**Success:** `302` redirect to `/web/profile`.
**Failure:** Any non-`302` (typically a `200` with the 2FA page) means the TOTP was invalid. Generate a fresh code and retry.
---
## TOTP Details
BML uses standard RFC 6238 TOTP:
| Parameter | Value |
|---|---|
| Algorithm | HMAC-SHA1 |
| Period | 30 seconds |
| Digits | 6 |
| Encoding | Base32 secret |
---
## Step 5 — Profile Selection
```
GET https://www.bankofmaldives.com.mv/internetbanking/web/profile
```
### Response — Multi-profile account
`200 OK` with an HTML page containing an Inertia.js `data-page` payload. After [extracting the Inertia JSON](README.md#inertiajs-response-format):
```json
{
"props": {
"profiles": [
{
"profile_id": "12345",
"name": "Mohamed Ali",
"type": "Profile",
"profile": {
"profile_type": "default"
}
},
{
"profile_id": "67890",
"name": "My Company Ltd",
"type": "Business",
"profile": {
"profile_type": "business"
}
}
]
}
}
```
| Field | Type | Description |
|---|---|---|
| `profile_id` | `string` | ID used in Step 6 to activate this profile |
| `name` | `string` | Display name of the profile |
| `type` | `string` | `"Profile"` for personal, `"Business"` for business |
| `profile.profile_type` | `string` | `"default"` (personal) or `"business"` |
### Response — Single-profile account
`302` redirect (to `/web/redirect` or similar). The server has auto-activated the sole profile and set the `blaze_identity` cookie. Skip Step 6 and proceed directly to [OAuth Token Exchange](03-oauth-token.md).
---
## Step 6 — Activate Profile
```
GET https://www.bankofmaldives.com.mv/internetbanking/web/profile/{profile_id}
```
Replace `{profile_id}` with the value from the profile list.
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/web/profile/12345' \
--header 'User-Agent: Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--cookie 'XSRF-TOKEN=<xsrf_token>; blaze_session=<session>'
```
### Response — Personal profile (`profile_type: "default"`)
`302` redirect (to `/web/redirect` or any path other than `/web/profile/2fa/business`), or `409 Conflict` if the profile was already active.
Both outcomes mean success: the `blaze_identity` cookie is now set. Proceed to [OAuth Token Exchange](03-oauth-token.md).
### Response — Business profile (`profile_type: "business"`)
`302` redirect to `/web/profile/2fa/business`. The business profile requires an additional SMS/email OTP verification step.
Proceed to [Business Profile OTP](02-business-otp.md).
---
## Next Steps
- **Personal profile activated** → proceed to **[OAuth Token Exchange](03-oauth-token.md)**
- **Business profile** → proceed to **[Business Profile OTP](02-business-otp.md)**
---
&nbsp;
---
[← README](README.md) &nbsp;&nbsp;&nbsp; **Next →** [Business Profile OTP](02-business-otp.md)

164
docs/bmlapi/02-business-otp.md Normal file
View File

@@ -0,0 +1,164 @@
# Business Profile OTP
When activating a business profile (where `profile_type` is `"business"`), the server requires SMS or email OTP verification before issuing the `blaze_identity` cookie. This is a two-step process: request an OTP to a chosen channel, then submit the received code.
---
## Prerequisites
- Completed [Login Steps 1–5](01-login.md) (web session cookies are active)
- Received a `302` redirect to `/web/profile/2fa/business` after `GET /web/profile/{profile_id}`
---
## Step 1 — Fetch Available OTP Channels
```
GET https://www.bankofmaldives.com.mv/internetbanking/web/profile/2fa/business
```
Fetches the HTML page for the business 2FA screen. This also refreshes the `XSRF-TOKEN` cookie needed for the POST requests below.
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/web/profile/2fa/business' \
--header 'User-Agent: Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--cookie 'XSRF-TOKEN=<xsrf_token>; blaze_session=<session>; blaze_identity=<identity>'
```
### Response
`200 OK` — HTML with an Inertia.js `data-page` payload. After [extracting the Inertia JSON](README.md#inertiajs-response-format):
```json
{
"props": {
"channels": [
{
"channel": "sms",
"description": "SMS",
"masked": "+960 9XX XXXX"
},
{
"channel": "email",
"description": "Email",
"masked": "m****@example.com"
}
]
}
}
```
| Field | Type | Description |
|---|---|---|
| `channel` | `string` | Channel identifier — use in Step 2 and Step 3 |
| `description` | `string` | Human-readable channel name |
| `masked` | `string` | Partially masked destination (for display to user) |
Present the `masked` values to the user so they can choose where to receive their OTP.
---
## Step 2 — Request OTP
```
POST https://www.bankofmaldives.com.mv/internetbanking/web/profile/2fa/business
```
Send an empty `code` to trigger OTP dispatch to the chosen channel.
### Request
**Content-Type:** `application/json`
```json
{
"code": "",
"channel": "sms"
}
```
| Field | Value | Notes |
|---|---|---|
| `code` | `""` | Empty — signals OTP dispatch, not submission |
| `channel` | `"sms"` or `"email"` | Channel from Step 1 |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/web/profile/2fa/business' \
--header 'Content-Type: application/json' \
--header 'User-Agent: Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--header 'X-XSRF-TOKEN: <xsrf_token>' \
--cookie 'XSRF-TOKEN=<xsrf_token>; blaze_session=<session>' \
--data '{"code":"","channel":"sms"}'
```
### Response
**Success:** `302` redirect — OTP has been sent.
**Failure:** Any non-`302` — request failed; check session cookies and retry.
---
## Step 3 — Submit OTP
```
POST https://www.bankofmaldives.com.mv/internetbanking/web/profile/2fa/business
```
Before submitting, refresh the XSRF token by making a fresh `GET /web/profile/2fa/business` (repeat Step 1). This ensures the token is valid for the confirmation POST.
### Request
**Content-Type:** `application/json`
```json
{
"code": "123456",
"channel": "sms"
}
```
| Field | Value | Notes |
|---|---|---|
| `code` | `"123456"` | OTP received via SMS/email |
| `channel` | `"sms"` or `"email"` | Same channel used in Step 2 |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/web/profile/2fa/business' \
--header 'Content-Type: application/json' \
--header 'User-Agent: Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--header 'X-XSRF-TOKEN: <xsrf_token_fresh>' \
--cookie 'XSRF-TOKEN=<xsrf_token_fresh>; blaze_session=<session>' \
--data '{"code":"123456","channel":"sms"}'
```
### Response — Success
`302` redirect to `/web/redirect` or `409 Conflict`. Both mean the OTP was accepted and the `blaze_identity` cookie is now set for the business profile.
Proceed to [OAuth Token Exchange](03-oauth-token.md).
### Response — Invalid OTP
`302` redirect to any path other than `/web/redirect`. The OTP was wrong. Retry Step 3 with a new code (re-requesting is not usually needed unless the OTP expired).
### Response — Other failure
Non-`302` HTTP status — session has likely expired. Return to the full [login flow](01-login.md).
---
## Next Steps
After the `blaze_identity` cookie is set → proceed to **[OAuth Token Exchange](03-oauth-token.md)**
---
&nbsp;
---
[← Login](01-login.md) &nbsp;&nbsp;&nbsp; **Next →** [OAuth Token](03-oauth-token.md)

193
docs/bmlapi/03-oauth-token.md Normal file
View File

@@ -0,0 +1,193 @@
# OAuth Token Exchange and Refresh
After the web login flow has set the `blaze_identity` cookie (profile activated), the client exchanges a PKCE authorization code for an `access_token` and `refresh_token`. These tokens are used for all subsequent REST API calls.
---
## Prerequisites
- Completed [Login](01-login.md) (and [Business OTP](02-business-otp.md) if applicable)
- `blaze_identity` cookie set in the session
- PKCE `code_verifier` and `code_challenge` generated at the start of the login session
- `Device-ID` generated at the start of the login session
---
## PKCE Parameter Generation
Generate these once at the start of each login session:
| Parameter | Generation |
|---|---|
| `code_verifier` | 72 cryptographically random bytes, base64url-encoded (no padding) |
| `code_challenge` | SHA-256 hash of `code_verifier` (as ASCII bytes), base64url-encoded (no padding) |
| `Device-ID` | 8 cryptographically random bytes, hex-encoded (16 hex chars) |
| `state` | 16 random bytes, base64url-encoded |
| `nonce` | 12 random bytes, base64url-encoded |
---
## Step 1 — Authorize (Get Auth Code)
```
GET https://www.bankofmaldives.com.mv/internetbanking/oauth/authorize
```
### Query Parameters
| Parameter | Value |
|---|---|
| `redirect_uri` | `https://app.bankofmaldives.com.mv/oauth/mobile-callback` |
| `client_id` | `98C83590-513F-4716-B02B-EC68B7D9E7E7` |
| `response_type` | `code` |
| `state` | Random base64url string (16 bytes) |
| `nonce` | Random base64url string (12 bytes) |
| `code_challenge` | SHA-256 of `code_verifier`, base64url-encoded |
| `code_challenge_method` | `S256` |
| `Device-ID` | Random 16-char hex string |
| `User-Agent` | App user agent string |
| `x-app-version` | `2.1.44.348` |
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/oauth/authorize?redirect_uri=https%3A%2F%2Fapp.bankofmaldives.com.mv%2Foauth%2Fmobile-callback&client_id=98C83590-513F-4716-B02B-EC68B7D9E7E7&response_type=code&state=<state>&nonce=<nonce>&code_challenge=<code_challenge>&code_challenge_method=S256&Device-ID=<device_id>&User-Agent=bml-mobile-banking%2F348+%28{manufacturer}%3B+Android+14%3B+{model}%29&x-app-version=2.1.44.348' \
--header 'User-Agent: Mozilla/5.0 (Android {version}; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--cookie 'blaze_session=<session>; blaze_identity=<identity>'
```
### Response
`302` redirect to:
```
https://app.bankofmaldives.com.mv/oauth/mobile-callback?code=<auth_code>&state=<state>
```
Extract the `code` query parameter from the `Location` header. This is the one-time authorization code.
---
## Step 2 — Token Exchange
```
POST https://www.bankofmaldives.com.mv/internetbanking/oauth/token
```
### Request
**Content-Type:** `application/x-www-form-urlencoded`
| Field | Value |
|---|---|
| `grant_type` | `authorization_code` |
| `code` | Auth code from Step 1 |
| `code_verifier` | PKCE verifier generated at login start |
| `client_id` | `98C83590-513F-4716-B02B-EC68B7D9E7E7` |
| `redirect_uri` | `https://app.bankofmaldives.com.mv/oauth/mobile-callback` |
| `Device-ID` | Same device ID used in Step 1 |
| `User-Agent` | App user agent string |
| `x-app-version` | `2.1.44.348` |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/oauth/token' \
--header 'User-Agent: Mozilla/5.0 (Android {version}; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0' \
--data 'grant_type=authorization_code' \
--data 'code=<auth_code>' \
--data 'code_verifier=<code_verifier>' \
--data 'client_id=98C83590-513F-4716-B02B-EC68B7D9E7E7' \
--data 'redirect_uri=https%3A%2F%2Fapp.bankofmaldives.com.mv%2Foauth%2Fmobile-callback' \
--data 'Device-ID=<device_id>' \
--data 'User-Agent=bml-mobile-banking%2F348+%28{manufacturer}%3B+Android+14%3B+{model}%29' \
--data 'x-app-version=2.1.44.348'
```
### Response
```json
{
"access_token": "eyJhbGciOiJSUzI1NiJ9...",
"refresh_token": "def50200aabbcc...",
"token_type": "Bearer",
"expires_in": 3600
}
```
| Field | Type | Description |
|---|---|---|
| `access_token` | `string` | JWT Bearer token — use in `Authorization: Bearer <token>` on all REST API calls |
| `refresh_token` | `string` | Long-lived token — use to refresh without re-login |
| `token_type` | `string` | Always `"Bearer"` |
| `expires_in` | `number` | Token lifetime in seconds (typically `3600`) |
Store `access_token`, `refresh_token`, `expires_in`, and `Device-ID` together as the session. The `access_token` expires at `now + expires_in * 1000` milliseconds.
---
## Token Refresh
When the access token expires (on `401` or `419` from any REST endpoint), obtain a new one using the refresh token. No web session or cookies are needed.
```
POST https://www.bankofmaldives.com.mv/internetbanking/oauth/token
```
### Request
**Content-Type:** `application/x-www-form-urlencoded`
| Field | Value |
|---|---|
| `grant_type` | `refresh_token` |
| `refresh_token` | Stored refresh token |
| `client_id` | `98C83590-513F-4716-B02B-EC68B7D9E7E7` |
| `Device-ID` | Same device ID from the original login |
| `User-Agent` | App user agent string |
| `x-app-version` | `2.1.44.348` |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/oauth/token' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--data 'grant_type=refresh_token' \
--data 'refresh_token=def50200aabbcc...' \
--data 'client_id=98C83590-513F-4716-B02B-EC68B7D9E7E7' \
--data 'Device-ID=a1b2c3d4e5f60718' \
--data 'User-Agent=bml-mobile-banking%2F348+%28{manufacturer}%3B+Android+14%3B+{model}%29' \
--data 'x-app-version=2.1.44.348'
```
### Response
Same structure as the token exchange response. The server may issue a new `refresh_token` (rotating tokens). If a new one is returned, replace the stored value; otherwise keep the original.
```json
{
"access_token": "eyJhbGciOiJSUzI1NiJ9...<new>",
"refresh_token": "def50200...<new or same>",
"token_type": "Bearer",
"expires_in": 3600
}
```
**Failure:** If `access_token` is absent or blank in the response, the refresh token has expired. Re-run the full [login flow](01-login.md).
---
## Session Storage
Persist the following to represent a saved BML session:
| Field | Description |
|---|---|
| `access_token` | Bearer token for REST API calls |
| `refresh_token` | Used to renew without re-login |
| `expires_at` | Unix timestamp (ms) when `access_token` expires |
| `device_id` | Must be sent with every refresh; ties tokens to the device |
---
&nbsp;
---
[← Business Profile OTP](02-business-otp.md) &nbsp;&nbsp;&nbsp; **Next →** [Dashboard](04-dashboard.md)

244
docs/bmlapi/04-dashboard.md Normal file
View File

@@ -0,0 +1,244 @@
# Dashboard
Fetch all accounts for the active profile: CASA (savings/current), cards (prepaid/credit/debit), and loans.
---
## Endpoint
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/dashboard
```
---
## Prerequisites
- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
---
## Request
### Headers
| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/dashboard' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348'
```
---
## Response
```json
{
"success": true,
"payload": {
"dashboard": [
{
"id": "abc123def456",
"account": "7730000000001",
"account_type": "CASA",
"product": "Current Account",
"alias": "My Account",
"currency": "MVR",
"account_status": "Active",
"availableBalance": 1234.56,
"ledgerBalance": 1250.00,
"lockedAmount": 15.44
},
{
"id": "xyz789",
"account": "7730000000002",
"account_type": "CASA",
"product": "Savings Account",
"alias": "USD Savings",
"currency": "USD",
"account_status": "Active",
"availableBalance": 500.00,
"ledgerBalance": 500.00,
"lockedAmount": 0.0
},
{
"id": "card001",
"account": "4111111111111111",
"account_type": "Card",
"product": "Visa Debit",
"alias": "My Debit Card",
"currency": "MVR",
"account_status": "Active",
"prepaid_card": false,
"product_code": "VISA",
"account_visible": false,
"cardBalance": {
"AvailableLimit": 0.0,
"CurrentBalance": 0.0
}
},
{
"id": "card002",
"account": "4111111111112222",
"account_type": "Card",
"product": "Visa Prepaid",
"alias": "Prepaid",
"currency": "MVR",
"account_status": "Active",
"prepaid_card": true,
"product_code": "VISA",
"account_visible": true,
"cardBalance": {
"AvailableLimit": 200.00,
"CurrentBalance": 50.00
}
},
{
"id": "loan001",
"account": "9900000000001",
"account_type": "Loan",
"product": "Personal Finance",
"alias": "My Loan",
"currency": "MVR",
"account_status": "Active",
"availableBalance": -30000.0
}
]
}
}
```
---
## Response Fields
### Top-level
| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` on success |
| `payload.dashboard` | `array` | List of account objects; order may vary |
### Common Account Fields
| Field | Type | Description |
|---|---|---|
| `id` | `string` | Internal BML account ID — use this for history and loan detail calls |
| `account` | `string` | Account or card number (as displayed) |
| `account_type` | `string` | Account category — see table below |
| `product` | `string` | Product name (e.g. `"Current Account"`, `"Visa Prepaid"`) |
| `alias` | `string` | User-assigned label; may be blank |
| `currency` | `string` | ISO 4217 currency code (e.g. `"MVR"`, `"USD"`) |
| `account_status` | `string` | `"Active"` or other status strings |
### Account Types
| `account_type` | Description |
|---|---|
| `CASA` | Current Account or Savings Account |
| `Card` | Debit, credit, or prepaid card |
| `Loan` | Loan or financing account |
---
## CASA Fields
| Field | Type | Description |
|---|---|---|
| `availableBalance` | `number` | Available balance (funds available to use) |
| `ledgerBalance` | `number` | Book balance (may include pending transactions) |
| `lockedAmount` | `number` | Blocked/reserved amount |
---
## Card Fields
| Field | Type | Description |
|---|---|---|
| `prepaid_card` | `bool` | `true` for prepaid cards |
| `product_code` | `string` | Card scheme (e.g. `"VISA"`) |
| `account_visible` | `bool` | `true` for credit cards, `false` for debit cards |
| `cardBalance.AvailableLimit` | `number` | Available credit/prepaid balance |
| `cardBalance.CurrentBalance` | `number` | Current outstanding balance |
### Card Profile Types
| Condition | Type |
|---|---|
| `prepaid_card: true` | Prepaid card |
| `prepaid_card: false` AND `account_visible: true` | Credit card |
| `prepaid_card: false` AND `account_visible: false` | Debit card |
### Product Code → Card Name
The `product_code` field identifies the specific card product. Known mappings:
| `product_code` | Card name | Asset |
|---|---|---|
| `C8201`, `C8001`, `C8009` | Mastercard Prepaid | `master_prepaid` |
| `C8205`, `C8005`, `C8008` | Mastercard Prepaid Travel | `master_prepaid_travel` |
| `C8010`, `C8011` | Mastercard Platinum | `master_platinum` |
| `C8020`, `C8022` | Mastercard Gold | `master_gold` |
| `C8030`, `C8033` | Mastercard Business Debit | `master_business_debit` |
| `C8040`, `C8044` | Mastercard World | `master_world` |
| `C8101` | Mastercard Masveriyaa | `master_masveriyaa` |
| `C8102` | Mastercard Odiveriyaa | `master_odiveriyaa` |
| `C8901`, `C8991`, `C8980`, `C8981` | Mastercard Passport | `master_passport` |
| `C8902`, `C8907`, `C8909`, `C8912`, `C8992`, `C8996`, `C8997`, `C8982`, `C8983` | Mastercard Islamic | `master_islamic` |
| `C8905`, `C8995` | Visa Credit | `visa_credit` |
| `C8925`, `C8926` | Visa Student Blue | `visa_student_blue` |
| `C3001`, `C3011`, `C3050`, `C3051`, `C3031` | Amex Credit Green | `amex_credit_green` |
| `C3003`, `C3013`, `C3053`, `C3023`, `C3033`, `C3052` | Amex Debit Gold | `amex_debit_gold` |
| `C3005`, `C3015`, `C3055`, `C3054` | Amex Platinum | `amex_platinum` |
| `C3007`, `C3017`, `C3097`, `C3095`, `C3077`, `C3177` | Amex Debit Green | `amex_debit_green` |
| `C3009`, `C3019`, `C3029`, `C3099`, `C3088`, `C3188` | Amex Credit Gold | `amex_credit_gold` |
| `C1001`, `C1011`, `C1082`, `C1081`, `C1101`, `C1111`, `C1181`, `C1182` | Visa Debit Generic | `visa_debit_generic` |
| `C1003`, `C1013`, `C1083`, `C1084`, `C1103`, `C1113`, `C1183`, `C1184` | Visa Gold | `visa_gold` |
| `C1005`, `C1006`, `C1089` | Visa Debit Islamic | `visa_debit_islamic` |
| `C1007`, `C1027`, `C1097`, `C1107`, `C1197`, `C1077`, `C1177` | Visa Debit | `visa_debit` |
| `C1009`, `C1019`, `C1085`, `C1086`, `C1109`, `C1119`, `C1185`, `C1186` | Visa Platinum | `visa_platinum` |
| `C1017` | Visa Infinite | `visa_infinite` |
| `C1020`, `C1021` | Visa Debit Platinum | `visa_debit_platinum` |
| `C1030`, `C1090`, `C1130`, `C1033`, `C1133` | Visa Corporate | `visa_corporate` |
| `C1040`, `C1041`, `C1047`, `C1048`, `C1050`, `C1051`, `C1087`, `C1088`, `C1140`, `C1141`, `C1147`, `C1148`, `C1150`, `C1151`, `C1187`, `C1188` | Visa Student Black | `visa_student_black` |
| `C1059`, `C1062`, `C1070`, `C1072`, `C1159`, `C1162` | Mastercard Prepaid Business | `master_prepaid_business` |
| `C1061`, `C1063`, `C1071`, `C1073`, `C1161`, `C1163` | Mastercard | `master` |
| _(any other)_ | — | default card image |
---
## Loan Fields
| Field | Type | Description |
|---|---|---|
| `availableBalance` | `number` | Outstanding balance — returned as a negative number; use `abs()` for display |
For full loan details (interest rate, repayment schedule, overdue info), call [GET /api/mobile/account/{id}](05-userinfo.md#loan-detail).
---
## Error Responses
### Expired session
HTTP `401` or `419` — the access token has expired. Attempt [token refresh](03-oauth-token.md#token-refresh).
### Server error
HTTP `5xx` — BML server-side error. Retry after a delay.
---
&nbsp;
---
[← OAuth Token](03-oauth-token.md) &nbsp;&nbsp;&nbsp; **Next →** [User Info](05-userinfo.md)

141
docs/bmlapi/05-userinfo.md Normal file
View File

@@ -0,0 +1,141 @@
# User Info and Session Health
Two endpoints for checking the current session and fetching the authenticated user's personal details.
---
## Profile Health Check
A lightweight call to verify that the access token is still valid. Returns HTTP `200` on success, `401`/`419` if expired.
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/profile
```
### Request
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/profile' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348'
```
Use this to probe the session before making more expensive calls. On `401` or `419`, proceed to [token refresh](03-oauth-token.md#token-refresh).
---
## User Info
Fetch personal details for the currently authenticated user.
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/userinfo
```
### Request
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/userinfo' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348'
```
### Response
```json
{
"success": true,
"payload": {
"user": {
"fullname": "MOHAMED ALI",
"email": "user@example.com",
"mobile_phone": "9600000001",
"customer_number": "C0000001",
"idcard": "A123456",
"birthdate": "1990-01-01"
}
}
}
```
| Field | Type | Description |
|---|---|---|
| `fullname` | `string` | Full name (typically uppercase) |
| `email` | `string` | Registered email address |
| `mobile_phone` | `string` | Registered mobile number |
| `customer_number` | `string` | BML internal customer ID (e.g. `C0000001`) |
| `idcard` | `string` | National ID card number |
| `birthdate` | `string` | Date of birth (`YYYY-MM-DD`) |
### Failure
```json
{ "success": false }
```
Returns `null` payload if the account has no user info record, or `success: false` on any error.
---
## Loan Detail
Fetch extended details for a loan account. The `{id}` is the internal account ID (`id` field) from the [dashboard](04-dashboard.md) response.
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/account/{id}
```
### Request
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/account/loan001' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348'
```
### Response
```json
{
"success": true,
"payload": {
"loanAmount": 50000.00,
"outstandingAmt": -30000.00,
"repayAmount": 1500.00,
"intRate": 8.5,
"loanStatus": "Active",
"startDate": "2023-10-26T00:00:00+05:00",
"endDate": "2026-10-26T00:00:00+05:00",
"noOfRepayOverdue": 0,
"overdueAmount": 0.00
}
}
```
| Field | Type | Description |
|---|---|---|
| `loanAmount` | `number` | Original loan principal |
| `outstandingAmt` | `number` | Outstanding balance — returned as a **negative number**; use `abs()` for display |
| `repayAmount` | `number` | Periodic repayment amount |
| `intRate` | `number` | Interest rate (percentage) |
| `loanStatus` | `string` | Status string (e.g. `"Active"`) |
| `startDate` | `string` | Loan start date (ISO 8601) |
| `endDate` | `string` | Loan end date (ISO 8601) |
| `noOfRepayOverdue` | `number` | Number of overdue repayments |
| `overdueAmount` | `number` | Total overdue amount |
On `401`/`419` the session has expired — attempt [token refresh](03-oauth-token.md#token-refresh).
---
&nbsp;
---
[← Dashboard](04-dashboard.md) &nbsp;&nbsp;&nbsp; **Next →** [Account History](06-account-history.md)

194
docs/bmlapi/06-account-history.md Normal file
View File

@@ -0,0 +1,194 @@
# Account Transaction History
Fetch paginated transaction history for a CASA (savings/current) account.
---
## Endpoint
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/account/{accountId}/history/{page}
```
| Path parameter | Description |
|---|---|
| `accountId` | Internal account ID (`id` field from [dashboard](04-dashboard.md)) |
| `page` | Page number, 1-based |
---
## Prerequisites
- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
- Internal account `id` from the [Dashboard](04-dashboard.md) response (not the account number)
---
## Request
### Headers
| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/account/abc123def456/history/1' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348'
```
---
## Pagination
The API uses 1-based page numbering. The response includes `totalPages` — increment the page number until you reach or exceed it.
| Page | URL |
|---|---|
| First | `/api/mobile/account/{id}/history/1` |
| Second | `/api/mobile/account/{id}/history/2` |
| N-th | `/api/mobile/account/{id}/history/N` |
Stop when the current page number exceeds `totalPages`, or when the `history` array is empty.
---
## Response
```json
{
"success": true,
"payload": {
"totalPages": 5,
"history": [
{
"id": "TXN001",
"bookingDate": "2026-05-16",
"description": "Transfer Debit",
"narrative1": "16-05-2026 15-10-25",
"narrative2": "Mohamed Ali",
"amount": -500.00,
"currency": "MVR",
"reference": "FT20260516123456"
},
{
"id": "TXN002",
"bookingDate": "2026-05-15",
"description": "Transfer Credit",
"narrative1": "15-05-2026 10-30-00",
"narrative2": "Ahmed Hassan",
"amount": 1000.00,
"currency": "MVR",
"reference": "FT20260515103000"
},
{
"id": "TXN003",
"bookingDate": "2026-05-14",
"description": "Purchase",
"narrative1": "14-05-2026 041500",
"narrative2": "",
"amount": -75.00,
"currency": "MVR",
"reference": ""
}
]
}
}
```
---
## Response Fields
### Top-level
| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` on success |
| `payload.totalPages` | `number` | Total number of pages |
| `payload.history` | `array` | List of transactions for this page |
### Transaction Object
| Field | Type | Description |
|---|---|---|
| `id` | `string` | Transaction ID |
| `bookingDate` | `string` | Booking date (fallback date — prefer parsed `narrative1` where available) |
| `description` | `string` | Transaction type — see table below |
| `narrative1` | `string` | Encodes the precise timestamp; format depends on `description` |
| `narrative2` | `string` | Counterparty name (for transfers); may be blank |
| `amount` | `number` | Amount — **negative = debit, positive = credit** |
| `currency` | `string` | ISO 4217 currency code |
| `reference` | `string` | Transfer reference number; blank for non-transfer entries |
---
## Transaction Descriptions
| `description` | Meaning |
|---|---|
| `Transfer Debit` | Outgoing transfer |
| `Transfer Credit` | Incoming transfer |
| `Purchase` | Card purchase or point-of-sale transaction |
| Other | Various bank-generated transaction types |
---
## Date Parsing from `narrative1`
The `bookingDate` field is date-only. For precise timestamps, parse `narrative1`:
### Transfer Debit / Transfer Credit
Format: `DD-MM-YYYY HH-mm-ss`
```
"16-05-2026 15-10-25" → 2026-05-16 15:10:25
```
Parse with `SimpleDateFormat("dd-MM-yyyy HH-mm-ss")`.
### Purchase
Format: `DD-MM-YYYY HHmmSS` (time is first 4 digits of the numeric suffix)
```
"14-05-2026 041500" → date: 14-05-2026, time part: "0415" → 04:15
→ 2026-05-14 04:15:00
```
Parse: split on space → date part `DD-MM-YYYY`, time part take first 4 chars → `HH:mm`. Combine and parse with `SimpleDateFormat("dd-MM-yyyy HH:mm:ss")`.
### All other descriptions
Fall back to `bookingDate` as-is.
---
## Amount Sign Convention
| Sign | Meaning |
|---|---|
| Positive (`+`) | Credit — money received |
| Negative (`-`) | Debit — money spent |
---
## Error Responses
| HTTP Code | Meaning |
|---|---|
| `401` / `419` | Access token expired — attempt [token refresh](03-oauth-token.md#token-refresh) |
---
&nbsp;
---
[← User Info](05-userinfo.md) &nbsp;&nbsp;&nbsp; **Next →** [Card Statement](07-card-statement.md)

164
docs/bmlapi/07-card-statement.md Normal file
View File

@@ -0,0 +1,164 @@
# Card Statement
Fetch transaction history for a card account (prepaid, credit, or debit). Returns three sets of entries: outstanding authorisations, unbilled transactions, and billed statement entries.
---
## Endpoint
```
POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/card/statement
```
---
## Prerequisites
- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
- Internal card ID (`id` field from [dashboard](04-dashboard.md)) and a target month
---
## Request
**Content-Type:** `application/json`
### Body
```json
{
"card": "card001",
"month": "2026-05"
}
```
| Field | Description |
|---|---|
| `card` | Internal card ID — the `id` field from the dashboard response (not the card number) |
| `month` | Target month in `YYYY-MM` format |
### Headers
| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/card/statement' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'Content-Type: application/json' \
--data '{"card":"card001","month":"2026-05"}'
```
---
## Response
The payload contains up to three distinct sections, each may be absent or `null`:
```json
{
"success": true,
"payload": {
"outstanding": {
"CardOutStdAuthDetails": [
{
"TranApprCode": "123456",
"DateTime": "2026-05-16T15:10:25",
"TranDesc": "Online Purchase - Amazon",
"BillingAmount": 50.00,
"BillingCcy": "USD"
}
]
},
"unbilled": {
"CardUnbillTxnDetails": [
{
"TranApprCode": "789012",
"DateTime": "2026-05-15T10:30:00",
"TranDesc": "Supermarket",
"BillingAmount": 120.00,
"BillingCcy": "MVR"
}
]
},
"cardstatement": [
{
"TranRef": "STMT20260501001",
"TransDate": "2026-05-01",
"TranDate": "2026-05-01",
"TranDesc": "Monthly Fee",
"Description": "Monthly Fee",
"TranAmount": 25.00,
"TranCcy": "MVR"
}
]
}
}
```
---
## Response Sections
### `outstanding.CardOutStdAuthDetails` — Pending Authorisations
Transactions that have been authorised but not yet posted. Amounts are in the billing currency.
| Field | Type | Description |
|---|---|---|
| `TranApprCode` | `string` | Authorisation approval code |
| `DateTime` | `string` | Authorisation timestamp |
| `TranDesc` | `string` | Merchant or transaction description |
| `BillingAmount` | `number` | Amount in billing currency (positive) |
| `BillingCcy` | `string` | Billing currency code |
### `unbilled.CardUnbillTxnDetails` — Unbilled Transactions
Transactions posted to the card but not yet included in a statement cycle.
Same field structure as `CardOutStdAuthDetails`.
### `cardstatement` — Billed Statement Entries
Previously billed transactions from the statement cycle for the requested month.
| Field | Type | Description |
|---|---|---|
| `TranRef` | `string` | Statement reference |
| `TransDate` / `TranDate` | `string` | Transaction date (check both keys; `TransDate` takes priority) |
| `TranDesc` / `Description` | `string` | Description (check both keys; `TranDesc` takes priority) |
| `TranAmount` | `number` | Amount — **stored as positive, displayed as debit** (negate for sign convention) |
| `TranCcy` | `string` | Transaction currency |
> The `TranAmount` in `cardstatement` is always positive in the API response. Negate it to `−TranAmount` so it follows the standard debit-negative convention.
---
## Amount Sign Convention
| Section | Sign in response | Meaning |
|---|---|---|
| `outstanding` / `unbilled` | Positive | Debit (charge to card) |
| `cardstatement` | Positive (negate on display) | Debit (charge to card) |
---
## Error Responses
| HTTP Code | Meaning |
|---|---|
| `401` / `419` | Access token expired — attempt [token refresh](03-oauth-token.md#token-refresh) |
---
&nbsp;
---
[← Account History](06-account-history.md) &nbsp;&nbsp;&nbsp; **Next →** [Transfer](08-transfer.md)

235
docs/bmlapi/08-transfer.md Normal file
View File

@@ -0,0 +1,235 @@
# Transfer
Initiate and confirm a fund transfer. The process is two-step: an initial POST triggers an OTP to the user's chosen channel; a second POST with the OTP confirms and completes the transfer.
The same endpoint (`POST /api/mobile/transfer`) handles both steps — the presence of an `otp` field distinguishes them.
---
## Prerequisites
- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
- Validated destination account from [Account Validation](10-validate.md)
---
## Transfer Channels
Before initiating a transfer, fetch the OTP channels available to the user.
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer
```
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348'
```
### Response
```json
{
"success": true,
"payload": {
"transfer": {
"otpChannel": [
{
"channel": "token",
"description": "Authenticator App",
"masked": ""
},
{
"channel": "sms",
"description": "SMS",
"masked": "+960 9XX XXXX"
}
]
}
}
}
```
| Field | Type | Description |
|---|---|---|
| `channel` | `string` | Channel identifier — use in transfer requests |
| `description` | `string` | Human-readable channel name |
| `masked` | `string` | Partially masked destination (blank for authenticator) |
---
## Transfer Types
| `transfertype` | Description | Requires `bank` |
|---|---|---|
| `IAT` | Internal — BML account to BML account | No |
| `QTR` | Quick Transfer — via PayMV alias | No |
| `DOT` | Domestic Outside Transfer — BML to another bank (e.g. MIB) | Yes — BIC of the destination bank |
---
## Step 1 — Initiate Transfer (Trigger OTP)
```
POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer
```
### Request Body
**Content-Type:** `application/json`
```json
{
"debitAccount": "7730000000001",
"creditAccount": "7730000000002",
"debitAmount": 100.00,
"transfertype": "IAT",
"currency": "MVR",
"channel": "token"
}
```
For `DOT` (outside bank) transfers, add `"bank"`:
```json
{
"debitAccount": "7730000000001",
"creditAccount": "90101000000001000",
"debitAmount": 250.00,
"transfertype": "DOT",
"currency": "MVR",
"channel": "sms",
"bank": "MIBVMVMV"
}
```
| Field | Type | Description |
|---|---|---|
| `debitAccount` | `string` | Source BML account number |
| `creditAccount` | `string` | Destination account number |
| `debitAmount` | `number` | Amount to transfer |
| `transfertype` | `string` | `IAT`, `QTR`, or `DOT` |
| `currency` | `string` | Currency code (e.g. `"MVR"`, `"USD"`) |
| `channel` | `string` | OTP channel from the channels list (e.g. `"token"`, `"sms"`) |
| `bank` | `string` | BIC of the destination bank — required for `DOT` only |
### Headers
| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |
| `accept` | `application/json` |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"debitAccount":"7730000000001","creditAccount":"7730000000002","debitAmount":100.00,"transfertype":"IAT","currency":"MVR","channel":"token"}'
```
### Response — OTP Triggered
```json
{
"success": true,
"code": 22,
"message": "OTP sent to your authenticator app"
}
```
`success: true` AND `code: 22` together confirm that the OTP has been dispatched. Proceed to Step 2.
Any other combination means the request failed.
---
## Step 2 — Confirm Transfer (Submit OTP)
```
POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer
```
Repeat the exact same body as Step 1, adding the `otp` field (and optionally `remarks`).
### Request Body
```json
{
"debitAccount": "7730000000001",
"creditAccount": "7730000000002",
"debitAmount": 100.00,
"transfertype": "IAT",
"currency": "MVR",
"channel": "token",
"otp": "123456",
"remarks": "Rent payment"
}
```
| Additional field | Type | Description |
|---|---|---|
| `otp` | `string` | OTP received via the chosen channel |
| `remarks` | `string` | Optional transfer reference/memo (omit if blank) |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/transfer' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"debitAccount":"7730000000001","creditAccount":"7730000000002","debitAmount":100.00,"transfertype":"IAT","currency":"MVR","channel":"token","otp":"123456","remarks":"Rent payment"}'
```
---
## Responses
### Success
```json
{
"success": true,
"message": "Transfer successful",
"payload": {
"reference": "FT202605160001",
"timestamp": "2026-05-16 15:10:25"
}
}
```
| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` |
| `message` | `string` | Confirmation message |
| `payload.reference` | `string` | Transfer reference number |
| `payload.timestamp` | `string` | Completion timestamp |
### Failure
```json
{
"success": false,
"message": "Invalid OTP. Please try again."
}
```
`success: false` — the `message` field contains the reason. Common causes: wrong OTP, insufficient balance, invalid account.
---
&nbsp;
---
[← Card Statement](07-card-statement.md) &nbsp;&nbsp;&nbsp; **Next →** [Contacts](09-contacts.md)

157
docs/bmlapi/09-contacts.md Normal file
View File

@@ -0,0 +1,157 @@
# Contacts (Saved Beneficiaries)
Manage the user's saved beneficiary list: list all contacts, save a new one, and delete an existing one.
---
## List Contacts
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/contacts
```
### Request
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/contacts' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348'
```
### Response
```json
{
"success": true,
"payload": [
{
"id": 1,
"account": "7730000000001",
"name": "Mohamed Ali",
"alias": "Ali",
"status": "S",
"currency": "MVR"
},
{
"id": 2,
"account": "90101000000001000",
"name": "Ahmed Hassan",
"alias": "Hassan",
"status": "S",
"currency": "MVR"
}
]
}
```
| Field | Type | Description |
|---|---|---|
| `id` | `number` | Internal contact ID — use for delete |
| `account` | `string` | Beneficiary account number |
| `name` | `string` | Account holder name |
| `alias` | `string` | User-assigned nickname; falls back to `name` if blank |
| `status` | `string` | Contact status (typically `"S"` for saved) |
| `currency` | `string` | Transfer currency for this contact |
Entries where `account` is blank are skipped.
---
## Save Contact
```
POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/contacts
```
### Request
**Content-Type:** `application/json`
```json
{
"contact_type": "BML",
"account": "7730000000001",
"alias": "Ali",
"currency": "MVR",
"name": "Mohamed Ali"
}
```
| Field | Type | Required | Description |
|---|---|---|---|
| `contact_type` | `string` | Yes | Contact category (e.g. `"BML"`) |
| `account` | `string` | Yes | Beneficiary account number |
| `alias` | `string` | Yes | Display nickname |
| `currency` | `string` | No | Transfer currency |
| `name` | `string` | No | Full name of the beneficiary |
| `swift` | `string` | No | SWIFT/BIC code (for international contacts) |
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/contacts' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"contact_type":"BML","account":"7730000000001","alias":"Ali","currency":"MVR","name":"Mohamed Ali"}'
```
### Response
```json
{ "success": true }
```
`success: true` confirms the contact was saved. `success: false` on failure.
---
## Delete Contact
```
POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/contacts/{contactId}
```
BML does not support `DELETE` directly — the delete is sent as a POST with a `_method: delete` body override.
| Path parameter | Description |
|---|---|
| `contactId` | The `id` from the contacts list |
### Request
**Content-Type:** `application/json`
```json
{ "_method": "delete" }
```
```bash
curl --request POST \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/contacts/1' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--data '{"_method":"delete"}'
```
### Response
```json
{ "success": true }
```
`success: true` confirms the contact was deleted.
---
&nbsp;
---
[← Transfer](08-transfer.md) &nbsp;&nbsp;&nbsp; **Next →** [Account Validation](10-validate.md)

175
docs/bmlapi/10-validate.md Normal file
View File

@@ -0,0 +1,175 @@
# Account Validation
Resolve and validate a destination account before initiating a transfer. Two endpoints cover different account types:
- **BML / alias accounts** — `GET /api/mobile/validate/account/{input}` — resolves BML account numbers and PayMV aliases
- **MIB accounts** — `GET /api/mobile/favara/account-verification/{account}/MIB` — resolves MIB accounts via BML's Favara interbank network
---
## Validate BML Account or Alias
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/validate/account/{input}
```
`{input}` is either a BML account number or a PayMV alias string (e.g. `"MALI"` or a phone number used as alias).
### Request
```bash
# Validate a BML account number
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/validate/account/7730000000001' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'Accept: application/json'
# Validate an alias
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/validate/account/MALI' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'Accept: application/json'
```
---
## Responses
The `validationType` in the response determines which transfer type to use.
### BML Account (`validationType: "BML"`) — use `IAT`
```json
{
"success": true,
"payload": {
"trnType": "IAT",
"validationType": "BML",
"account": "7730000000001",
"name": "Mohamed Ali",
"alias": "MALI",
"currency": "MVR"
}
}
```
| Field | Type | Description |
|---|---|---|
| `trnType` | `string` | Transfer type to use — `"IAT"` |
| `validationType` | `string` | `"BML"` |
| `account` | `string` | Resolved BML account number |
| `name` | `string` | Account holder name |
| `alias` | `string` | Alias (if any) — blank or `"null"` if none |
| `currency` | `string` | Account currency |
---
### PayMV Alias (`validationType: "alias"`) — use `QTR`
Returned when the input resolves to a PayMV alias (interbank quick transfer).
```json
{
"success": true,
"payload": {
"trnType": "QTR",
"validationType": "alias",
"CdtrAcct": {
"Acct": "7730000000001",
"FinInstnId": ""
},
"contact_name": "Mohamed Ali",
"currency": "MVR"
}
}
```
| Field | Type | Description |
|---|---|---|
| `trnType` | `string` | Transfer type to use — `"QTR"` |
| `validationType` | `string` | `"alias"` |
| `CdtrAcct.Acct` | `string` | Resolved account number |
| `CdtrAcct.FinInstnId` | `string` | BIC of the destination institution (blank for BML-to-BML) |
| `contact_name` | `string` | Account holder name |
| `currency` | `string` | Account currency |
> For `QTR` transfers, pass the **original alias input** as `creditAccount` (not the resolved account number), as the alias is what the server routes on.
---
### Failure
```json
{ "success": false }
```
Account or alias not found, or not eligible for transfer.
---
## Verify MIB Account (Favara)
```
GET https://www.bankofmaldives.com.mv/internetbanking/api/mobile/favara/account-verification/{account}/MIB
```
Verifies a Maldives Islamic Bank (MIB) account number via BML's Favara interbank network. Use the result for a `DOT` transfer.
### Request
```bash
curl --request GET \
--url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/favara/account-verification/90101000000001000/MIB' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'Accept: application/json'
```
### Response
```json
{
"success": true,
"account": "90101000000001000",
"name": "Mohamed Ali",
"agnt": "MIBVMVMV"
}
```
| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` if the account exists and is reachable |
| `account` | `string` | MIB account number |
| `name` | `string` | Account holder name |
| `agnt` | `string` | BIC of MIB — send as the `bank` field in the [transfer](08-transfer.md) request |
### Failure
```json
{ "success": false }
```
Account not found or not accessible via Favara.
---
## Transfer Type Summary
| `validationType` / source | `trnType` to use | `bank` required |
|---|---|---|
| `"BML"` | `IAT` | No |
| `"alias"` | `QTR` | No |
| MIB (Favara) | `DOT` | Yes — `agnt` value from verification response |
---
&nbsp;
---
[← Contacts](09-contacts.md) &nbsp;&nbsp;&nbsp; **Next →** [Foreign Limits](11-foreign-limits.md)

147
docs/bmlapi/11-foreign-limits.md Normal file
View File

@@ -0,0 +1,147 @@
# Foreign Transaction Limits
Fetch the user's USD foreign currency transaction limits per card, broken down by channel (ATM, ECOM, POS) and category (general, medical).
This endpoint uses a **different base URL** from the main REST API.
---
## Endpoint
```
GET https://app.bankofmaldives.com.mv/api/v2/foreign-limits
```
---
## Prerequisites
- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
---
## Request
### Headers
| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |
| `Accept` | `application/json` |
```bash
curl --request GET \
--url 'https://app.bankofmaldives.com.mv/api/v2/foreign-limits' \
--header 'Authorization: Bearer <access_token>' \
--header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
--header 'x-app-version: 2.1.44.348' \
--header 'Accept: application/json'
```
---
## Response
```json
{
"success": true,
"payload": [
{
"type": "Debit",
"used": 150.00,
"totalLimit": 1000.00,
"generalCap": 1000.00,
"generalRemaining": 850.00,
"medicalRemaining": 500.00,
"isAtmEnabled": true,
"isPosEnabled": true,
"usageByCategory": {
"ATM": {
"remaining": 350.00,
"limit": 500.00
},
"ECOM": {
"remaining": 200.00,
"limit": 300.00
},
"POS": {
"remaining": 300.00,
"limit": 500.00
}
}
},
{
"type": "Credit",
"used": 0.00,
"totalLimit": 2000.00,
"generalCap": 2000.00,
"generalRemaining": 2000.00,
"medicalRemaining": 1000.00,
"isAtmEnabled": true,
"isPosEnabled": true,
"usageByCategory": {
"ATM": { "remaining": 500.00, "limit": 500.00 },
"ECOM": { "remaining": 500.00, "limit": 500.00 },
"POS": { "remaining": 1000.00, "limit": 1000.00 }
}
}
]
}
```
---
## Response Fields
### Top-level
| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` on success |
| `payload` | `array` | One entry per card type (e.g. Debit, Credit, Prepaid) |
### Limit Object
| Field | Type | Description |
|---|---|---|
| `type` | `string` | Card type — e.g. `"Debit"`, `"Credit"`, `"Prepaid"` |
| `used` | `number` | Total amount used this period (USD) |
| `totalLimit` | `number` | Overall foreign transaction limit (USD) |
| `generalCap` | `number` | General spending cap (USD) |
| `generalRemaining` | `number` | Remaining general limit (USD) |
| `medicalRemaining` | `number` | Remaining medical category limit (USD) |
| `isAtmEnabled` | `bool` | Whether ATM withdrawals are enabled |
| `isPosEnabled` | `bool` | Whether POS payments are enabled |
### `usageByCategory` — Channel Breakdown
| Channel | Description |
|---|---|
| `ATM` | ATM cash withdrawals |
| `ECOM` | E-commerce / online purchases |
| `POS` | Point-of-sale payments |
Each channel object:
| Field | Type | Description |
|---|---|---|
| `remaining` | `number` | Remaining limit for this channel (USD) |
| `limit` | `number` | Total limit for this channel (USD) |
---
## Error Responses
| HTTP Code | Meaning |
|---|---|
| `401` / `419` | Access token expired — attempt [token refresh](03-oauth-token.md#token-refresh) |
---
&nbsp;
---
[← Account Validation](10-validate.md)

198
docs/bmlapi/README.md Normal file
View File

@@ -0,0 +1,198 @@
# BML Internet Banking API Documentation
Reverse-engineered from traffic captures of the BML Mobile Banking Android app (`mv.com.bml.mib`).
[Play Store](https://play.google.com/store/apps/details?id=mv.com.bml.mib)
---
## Overview
Bank of Maldives (BML) uses a hybrid authentication model: a web session flow (cookie-based, Inertia.js frontend) handles login and profile selection, which then feeds into a PKCE OAuth 2.0 exchange to obtain a Bearer token for the REST API.
The login process is stateful and must be executed in order:
1. Web login (credentials + TOTP)
2. Profile activation
3. PKCE OAuth token exchange
4. Authenticated REST API calls using the Bearer token
---
## Base URLs
| Purpose | Base URL |
|---|---|
| Web login / OAuth | `https://www.bankofmaldives.com.mv/internetbanking` |
| REST API (authenticated) | `https://www.bankofmaldives.com.mv/internetbanking/api/mobile` |
| Foreign limits API | `https://app.bankofmaldives.com.mv/api/v2` |
---
## Authentication Model
| Value | How obtained | How used |
|---|---|---|
| `XSRF-TOKEN` cookie | Set by server on `GET /web/login` | Sent as `X-XSRF-TOKEN` header on all web POST requests |
| `blaze_session` cookie | Set by server during web flow | Managed automatically by cookie jar |
| `blaze_identity` cookie | Set by server after profile activation | Managed automatically; identifies the active profile |
| `access_token` | Returned by `POST /oauth/token` after PKCE exchange | Sent as `Authorization: Bearer <token>` on all REST API calls |
| `refresh_token` | Returned alongside `access_token` | Used to obtain a new `access_token` without re-login |
The web flow uses a standard browser cookie jar. The REST API only needs the Bearer token — no cookies required after the OAuth exchange.
---
## OAuth 2.0 PKCE Parameters
| Parameter | Value |
|---|---|
| `client_id` | `98C83590-513F-4716-B02B-EC68B7D9E7E7` |
| `redirect_uri` | `https://app.bankofmaldives.com.mv/oauth/mobile-callback` |
| `response_type` | `code` |
| `code_challenge_method` | `S256` |
The `code_verifier` is a cryptographically random 72-byte value, base64url-encoded (no padding). The `code_challenge` is the SHA-256 hash of the verifier, also base64url-encoded.
The `Device-ID` is a random 8-byte hex string generated once per login session.
---
## User-Agent Strategy
Two different User-Agent strings are used depending on the phase:
| Phase | User-Agent to use |
|---|---|
| Web login steps (GET/POST `/web/*`, `/oauth/authorize`) | Browser UA |
| OAuth token endpoint (`POST /oauth/token`) | Browser UA |
| All authenticated REST API calls (`/api/mobile/*`, `/api/v2/*`) | App UA |
**Browser UA** (used during the entire web session and OAuth flow):
```
Mozilla/5.0 (Android 14; Mobile; rv:150.0) Gecko/150.0 Firefox/150.0
```
**App UA** (used for all REST API calls after the token is obtained):
```
bml-mobile-banking/348 (<Build.MANUFACTURER>; Android <Build.VERSION.RELEASE>; <Build.MODEL>)
```
Example app UA:
```
bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})
```
---
## Inertia.js Response Format
The BML web frontend is built with Inertia.js. All web page responses embed their data as HTML-escaped JSON in the `data-page` attribute of the root `<div>`:
```html
<div id="app" data-page="{&quot;component&quot;:&quot;Login&quot;,&quot;props&quot;:{...}}">
```
To extract: find `data-page="..."`, unescape HTML entities (`&quot;` → `"`, `&amp;` → `&`, `&#39;` → `'`, `&lt;` → `<`, `&gt;` → `>`), then parse as JSON. The useful data is inside the `props` key.
---
## Login Flow
```
Client Server
| |
| GET /web/login | ← seeds XSRF-TOKEN + blaze_session cookies
|------------------------------------------------>|
| Set-Cookie: XSRF-TOKEN=...; blaze_session=... |
|<------------------------------------------------|
| |
| POST /web/login | ← JSON: {username, password, code:""}
| X-XSRF-TOKEN: <xsrf> |
|------------------------------------------------>|
| 302 Redirect → /web/login/2fa |
|<------------------------------------------------|
| |
| GET /web/login/2fa | ← refreshes cookies
|------------------------------------------------>|
| Set-Cookie: XSRF-TOKEN=<new> |
|<------------------------------------------------|
| |
| POST /web/login/2fa | ← JSON: {code: <TOTP>, channel: "authenticator"}
| X-XSRF-TOKEN: <xsrf2> |
|------------------------------------------------>|
| 302 Redirect → /web/profile |
|<------------------------------------------------|
| |
| GET /web/profile | ← profile picker (multi) or auto-redirect (single)
|------------------------------------------------>|
| 200 (profile list) OR 302 (auto-activated) |
|<------------------------------------------------|
| |
| (multi-profile) GET /web/profile/{profileId} | ← activate selected profile
|------------------------------------------------>|
| 302 → /web/redirect (personal) |
| 302 → /web/profile/2fa/business (business) |
|<------------------------------------------------|
| |
| GET /oauth/authorize?...&code_challenge=... | ← PKCE authorize
|------------------------------------------------>|
| 302 → mobile-callback?code=<auth_code> |
|<------------------------------------------------|
| |
| POST /oauth/token | ← exchange auth code for tokens
| {code, code_verifier, grant_type, client_id} |
|------------------------------------------------>|
| {access_token, refresh_token, expires_in} |
|<------------------------------------------------|
| |
| GET /api/mobile/dashboard | ← authenticated REST API
| Authorization: Bearer <access_token> |
|------------------------------------------------>|
| {success: true, payload: {dashboard: [...]}} |
|<------------------------------------------------|
```
---
## Session Expiry
The access token expires after `expires_in` seconds (typically 3600). On a `401` or `419` response from any REST endpoint:
1. Attempt to refresh using the stored `refresh_token` → [Token Refresh](03-oauth-token.md#token-refresh)
2. If refresh fails, re-run the full login flow
---
## Transfer Types
| Code | Description |
|---|---|
| `IAT` | Internal Account Transfer — BML account to BML account |
| `QTR` | Quick Transfer — transfer via PayMV alias |
| `DOT` | Domestic Outside Transfer — BML to another bank (e.g. MIB) |
---
## Documents
| # | File | Description |
|---|---|---|
| 1 | [Login](01-login.md) | Web login: credentials, TOTP, profile selection |
| 2 | [Business Profile OTP](02-business-otp.md) | SMS/email OTP for business profile activation |
| 3 | [OAuth Token](03-oauth-token.md) | PKCE token exchange and token refresh |
| 4 | [Dashboard](04-dashboard.md) | Fetch all accounts (CASA, card, loan) |
| 5 | [User Info](05-userinfo.md) | User profile details and session health check |
| 6 | [Account History](06-account-history.md) | Paginated transaction history for CASA accounts |
| 7 | [Card Statement](07-card-statement.md) | Card transaction history (prepaid, credit, debit) |
| 8 | [Transfer](08-transfer.md) | Initiate and confirm fund transfers |
| 9 | [Contacts](09-contacts.md) | Saved beneficiaries — list, save, delete |
| 10 | [Account Validation](10-validate.md) | Validate BML accounts, aliases, and MIB accounts |
| 11 | [Foreign Limits](11-foreign-limits.md) | USD foreign transaction limits by card and channel |
---
&nbsp;
---
> **Next →** [Login](01-login.md)

10
docs/fahipayapi/01-login.md
View File

@@ -29,8 +29,8 @@ POST https://fahipay.mv/api/app/login/
| `device[available]` | `true` | See [common device fields](README.md#common-form-fields-device-info) | | `device[available]` | `true` | See [common device fields](README.md#common-form-fields-device-info) |
| `device[platform]` | `Android` | | | `device[platform]` | `Android` | |
| `device[uuid]` | `a1b2c3d4e5f60718` | Persistent 16-char hex UUID, generated once per install | | `device[uuid]` | `a1b2c3d4e5f60718` | Persistent 16-char hex UUID, generated once per install |
| `device[model]` | `22101320I` | `Build.MODEL` | | `device[model]` | `{model}` | `Build.MODEL` |
| `device[manufacturer]` | `Xiaomi` | `Build.MANUFACTURER` | | `device[manufacturer]` | `{manufacturer}` | `Build.MANUFACTURER` |
| `device[isVirtual]` | `false` | | | `device[isVirtual]` | `false` | |
| `device[serial]` | `unknown` | | | `device[serial]` | `unknown` | |
@@ -47,7 +47,7 @@ curl --request POST \
--header 'accept: application/json' \ --header 'accept: application/json' \
--header 'accept-encoding: gzip, deflate, br' \ --header 'accept-encoding: gzip, deflate, br' \
--header 'connection: keep-alive' \ --header 'connection: keep-alive' \
--header 'user-agent: Mozilla/5.0 (Linux; Android 14; 22101320I Build/AP2A.240905.003; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36' \ --header 'user-agent: Mozilla/5.0 (Linux; Android {version}; {model} Build/AP2A.240905.003; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36' \
--form 'email=A123456' \ --form 'email=A123456' \
--form 'password=your_password' \ --form 'password=your_password' \
--form 'grant_type=auth_id' \ --form 'grant_type=auth_id' \
@@ -57,8 +57,8 @@ curl --request POST \
--form 'device[available]=true' \ --form 'device[available]=true' \
--form 'device[platform]=Android' \ --form 'device[platform]=Android' \
--form 'device[uuid]=a1b2c3d4e5f60718' \ --form 'device[uuid]=a1b2c3d4e5f60718' \
--form 'device[model]=22101320I' \ --form 'device[model]={model}' \
--form 'device[manufacturer]=Xiaomi' \ --form 'device[manufacturer]={manufacturer}' \
--form 'device[isVirtual]=false' \ --form 'device[isVirtual]=false' \
--form 'device[serial]=unknown' --form 'device[serial]=unknown'
``` ```

10
docs/fahipayapi/02-otp.md
View File

@@ -38,8 +38,8 @@ POST https://fahipay.mv/api/app/otp/
| `device[available]` | `true` | Same device fields as login — must match | | `device[available]` | `true` | Same device fields as login — must match |
| `device[platform]` | `Android` | | | `device[platform]` | `Android` | |
| `device[uuid]` | `a1b2c3d4e5f60718` | Must be the **same UUID** used in the login request | | `device[uuid]` | `a1b2c3d4e5f60718` | Must be the **same UUID** used in the login request |
| `device[model]` | `22101320I` | | | `device[model]` | `{model}` | |
| `device[manufacturer]` | `Xiaomi` | | | `device[manufacturer]` | `{manufacturer}` | |
| `device[isVirtual]` | `false` | | | `device[isVirtual]` | `false` | |
| `device[serial]` | `unknown` | | | `device[serial]` | `unknown` | |
@@ -57,7 +57,7 @@ curl --request POST \
--header 'accept: application/json' \ --header 'accept: application/json' \
--header 'accept-encoding: gzip, deflate, br' \ --header 'accept-encoding: gzip, deflate, br' \
--header 'connection: keep-alive' \ --header 'connection: keep-alive' \
--header 'user-agent: Mozilla/5.0 (Linux; Android 14; 22101320I Build/AP2A.240905.003; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36' \ --header 'user-agent: Mozilla/5.0 (Linux; Android {version}; {model} Build/AP2A.240905.003; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36' \
--form 'code=123456' \ --form 'code=123456' \
--form 'channel=totp' \ --form 'channel=totp' \
--form 'action=login' \ --form 'action=login' \
@@ -68,8 +68,8 @@ curl --request POST \
--form 'device[available]=true' \ --form 'device[available]=true' \
--form 'device[platform]=Android' \ --form 'device[platform]=Android' \
--form 'device[uuid]=a1b2c3d4e5f60718' \ --form 'device[uuid]=a1b2c3d4e5f60718' \
--form 'device[model]=22101320I' \ --form 'device[model]={model}' \
--form 'device[manufacturer]=Xiaomi' \ --form 'device[manufacturer]={manufacturer}' \
--form 'device[isVirtual]=false' \ --form 'device[isVirtual]=false' \
--form 'device[serial]=unknown' --form 'device[serial]=unknown'
``` ```

10
docs/fahipayapi/README.md
View File

@@ -1,6 +1,8 @@
# Fahipay API Documentation # Fahipay API Documentation
Reverse-engineered from traffic captures of the Fahipay Android WebView app (`fahipay.mv`). Reverse-engineered from traffic captures of the Fahipay Android WebView app (`mv.fahipay`).
[Play Store](https://play.google.com/store/apps/details?id=mv.fahipay)
--- ---
@@ -41,7 +43,7 @@ Content-Type: multipart/form-data; boundary=<boundary>
accept: application/json accept: application/json
accept-encoding: gzip, deflate, br accept-encoding: gzip, deflate, br
connection: keep-alive connection: keep-alive
user-agent: Mozilla/5.0 (Linux; Android 14; 22101320I Build/AP2A.240905.003; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36 user-agent: Mozilla/5.0 (Linux; Android {version}; {model} Build/AP2A.240905.003; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36
``` ```
### Authenticated data endpoints ### Authenticated data endpoints
@@ -64,8 +66,8 @@ All login and OTP requests include a standard set of device fields:
| `device[available]` | `true` | Always `true` | | `device[available]` | `true` | Always `true` |
| `device[platform]` | `Android` | Always `Android` | | `device[platform]` | `Android` | Always `Android` |
| `device[uuid]` | `a1b2c3d4e5f60718` | 16 hex chars, generated once per install, persisted | | `device[uuid]` | `a1b2c3d4e5f60718` | 16 hex chars, generated once per install, persisted |
| `device[model]` | `22101320I` | Device model string | | `device[model]` | `{model}` | Device model string |
| `device[manufacturer]` | `Xiaomi` | Device manufacturer | | `device[manufacturer]` | `{manufacturer}` | Device manufacturer |
| `device[isVirtual]` | `false` | Always `false` | | `device[isVirtual]` | `false` | Always `false` |
| `device[serial]` | `unknown` | Always `unknown` | | `device[serial]` | `unknown` | Always `unknown` |

234
docs/mibapi/01-encryption.md Normal file
View File

@@ -0,0 +1,234 @@
# Encryption, Key Exchange & Nonce
All traffic to the encrypted API (`faisanet.mib.com.mv`) uses Blowfish encryption. This document covers the cipher, the DH key exchange that derives the session key, and the nonce algorithm required by every request.
---
## Cipher
- **Algorithm**: Blowfish, ECB mode, PKCS5 padding
- **Input**: raw UTF-8 bytes of the JSON payload string
- **Key**: raw UTF-8 bytes of the key string
- **Output**: base64-encoded ciphertext (URL-encoded when sent as form data)
```python
from Crypto.Cipher import Blowfish
from Crypto.Util.Padding import pad, unpad
import base64, json
from urllib.parse import quote
def encrypt(payload: dict, key: str) -> str:
plaintext = json.dumps(payload, separators=(',', ':')).encode('utf-8')
key_bytes = key.encode('latin-1')
cipher = Blowfish.new(key_bytes, Blowfish.MODE_ECB)
ct = cipher.encrypt(pad(plaintext, Blowfish.block_size))
return base64.b64encode(ct).decode()
def decrypt(ciphertext_b64: str, key: str) -> dict:
key_bytes = key.encode('latin-1')
ct = base64.b64decode(ciphertext_b64)
cipher = Blowfish.new(key_bytes, Blowfish.MODE_ECB)
plaintext = unpad(cipher.decrypt(ct), Blowfish.block_size)
return json.loads(plaintext.decode('utf-8'))
def build_request_body(payload: dict, key: str, extra_fields: dict = {}) -> str:
sfunc = payload.get('sfunc', '')
encrypted = encrypt(payload, key)
body = '&'.join(f"{k}={v}" for k, v in extra_fields.items())
if body:
return f"{body}&sfunc={sfunc}&data={quote(encrypted)}"
return f"sfunc={sfunc}&data={quote(encrypted)}"
```
---
## Request / Response Transport
**Request** — form field `data`:
```
sfunc=<value>&data=<url-encoded base64 Blowfish ciphertext>
```
For `sfunc=n` calls, `xxid` must be the **first** field:
```
xxid=<session_xxid>&sfunc=n&data=<encrypted>
```
For `sfunc=i` calls, `key2` is a separate unencrypted field:
```
key2=<key2>&sfunc=i&data=<encrypted>
```
**Response** — body is raw base64 Blowfish ciphertext (no form encoding); base64-decode then decrypt directly.
---
## Keys
| Key | Value | Used for |
|---|---|---|
| `DEFAULT_KEY` | `8M3L9SBF1AC4FRE56788M3L9SBF1AC4FRE5678` | `sfunc=r` key exchange request/response |
| Session key | DH-derived (44-char base64, 32 bytes) | All subsequent requests |
---
## Diffie-Hellman Session Key Derivation
The session key is derived via a custom DH exchange. All three parameters are hardcoded in the app — this provides no real security since the private key `A` never rotates.
> **Note**: The variable names in the app source are **swapped** from their DH role. `A_VALUE` in source is the exponent (shorter number); `P_VALUE` is the prime modulus (longer number).
```
G (generator) = 2
A (client privkey) = 1563516802667282387226490351799736881442299778484610378722158765594241028592123324764949712696577
P (prime modulus) = 2410312426921032588552076022197566074856950548502459942654116941958108831682612228890093858261341614673227141477904012196503648957050582631942730706805009223062734745341073406696246014589361659774041027169249453200378729434170325843778659198143763193776859869524088940195577346119843545301547043747207749969763750084308926339295559968882457872412993810129130294592999947926365264059284647209730384947211681434464714438488520940127459844288859336526896320919633919
```
### Steps
1. Client sends `cmod = G^A mod P` (as decimal string) in the `sfunc=r` request
2. Server responds with `smod` (its DH public key, as decimal string)
3. Client computes shared secret: `shared = smod^A mod P`
4. Client SHA-256 hashes `str(shared)` → uppercase hex
5. Client converts the hex string to raw bytes, then base64-encodes → session key
```python
import hashlib, base64
def derive_session_key(smod: int) -> str:
A = 1563516802667282387226490351799736881442299778484610378722158765594241028592123324764949712696577
P = 2410312426921032588552076022197566074856950548502459942654116941958108831682612228890093858261341614673227141477904012196503648957050582631942730706805009223062734745341073406696246014589361659774041027169249453200378729434170325843778659198143763193776859869524088940195577346119843545301547043747207749969763750084308926339295559968882457872412993810129130294592999947926365264059284647209730384947211681434464714438488520940127459844288859336526896320919633919
shared = pow(smod, A, P)
sha256_hex = hashlib.sha256(str(shared).encode()).hexdigest().upper()
return base64.b64encode(bytes.fromhex(sha256_hex)).decode()
```
The result is always a **44-character base64 string** (32 bytes). It changes every session.
---
## Nonce Computation
Every request after key exchange includes a `nonce` field. It is computed from the `nonceGenerator` string returned by the key exchange response.
### `nonceGenerator` format
A string of 4 groups separated by `-`. Each group contains 8 space-separated tokens. Each token is a letter followed by a number (e.g. `M85`, `A37`, `C95`, `X2`).
```
M85 A87 A82 M82 M60 M31 A46 C95-M14 X83 A37 X2 C4 X22 X46 C95-M57 X29 C51 C34 S91 X60 S1 A15-M54 A89 S13 S18 C81 A70 X92 X59
```
### Nonce output format
4 groups separated by `-`. Each group: a zero-padded 5-digit seed followed by 7 two-digit numbers separated by spaces.
```
08160 19 73 45 17 89 07 10-00924 64 73 18 08 48 80 67-01026 20 17 13 26 26 43 24-00648 12 32 17 69 14 63 92
```
### Algorithm
**Phase 1 — seed values (one per group):**
For each of the 4 groups:
1. Extract the number from `token[0]` (e.g. `M85` → `85`)
2. Generate random `r = floor(random() * 99) + 1` (range 1–99 inclusive)
3. `product = N * r` → zero-pad to 5 digits
4. `digitSum = sum of digits of padded`
5. `lastTwo = int(padded[-2:])` (last two digits)
6. Accumulate `cumSum += digitSum`
**Phase 2 — nonce digits (tokens 1–7 of each group):**
For each group, start with `carry = lastTwo[i]`:
| op letter | Formula |
|---|---|
| `M` | `(carry % num) + digitSum + cumSum` |
| `A` | `carry + num + digitSum + cumSum` |
| `S` | `(carry * carry) + num + digitSum + cumSum` |
| `X` | `(carry * num) + digitSum + cumSum` |
| `C` | `(carry * carry * carry) + num + digitSum + cumSum` |
Nonce digit = last two digits of the result. Update `carry = nonceDigit` for the next token.
**Output**: join padded seed + 7 two-digit nonce digits per group, join 4 groups with `-`.
### Python implementation
```python
import math, random
def generate_nonce(nonce_generator: str) -> str:
groups = nonce_generator.split('-')
padded_list, last_two, digit_sum = [], [], []
cum_sum = 0
for group in groups:
tokens = group.split(' ')
n = int(''.join(c for c in tokens[0] if c.isdigit()))
r = math.floor(random.random() * 99) + 1
product = n * r
padded = str(product).zfill(5)
ds = sum(int(d) for d in padded)
lt = int(padded[-2:])
padded_list.append(padded)
last_two.append(lt)
digit_sum.append(ds)
cum_sum += ds
result_groups = []
for i, group in enumerate(groups):
tokens = group.split(' ')
carry = last_two[i]
ds = digit_sum[i]
nonce_digits = []
for token in tokens[1:]:
op = ''.join(c for c in token if c.isalpha())
num = int(''.join(c for c in token if c.isdigit()))
if op == 'M': val = (carry % num) + ds + cum_sum
elif op == 'A': val = carry + num + ds + cum_sum
elif op == 'S': val = (carry * carry) + num + ds + cum_sum
elif op == 'X': val = (carry * num) + ds + cum_sum
elif op == 'C': val = (carry * carry * carry) + num + ds + cum_sum
else: val = 0
digit = int(str(val)[-2:])
nonce_digits.append(digit)
carry = digit
group_str = padded_list[i] + ' ' + ' '.join(str(d).zfill(2) for d in nonce_digits)
result_groups.append(group_str)
return '-'.join(result_groups)
```
### Notes
- `nonce` and `sodium` are separate fields. `sodium` is an independent random integer (~23–24 bit range).
- The `nonceGenerator` is returned once by the key exchange response and reused for the entire session.
---
## Known `sfunc` / `routePath` Values
| `sfunc` | `routePath` | Description |
|---|---|---|
| `r` | `S40` | Initial DH key exchange (DEFAULT_KEY) |
| `i` | `S40` | Authenticated DH key exchange (key1/key2) |
| `n` | `A44` | Get auth type / `userSalt` |
| `n` | `A41` | Regular login initialization |
| `n` | `A42` | OTP verification (regular login) |
| `n` | `C41` | Device registration initialization |
| `n` | `C42` | OTP verification (registration) |
| `n` | `P41` | Get profile image (by hash) |
| `n` | `P40` | Update profile image |
| `n` | `P42` | Delete profile image |
| `n` | `P47` | Select profile / fetch account balances |
---
&nbsp;
---
**Next →** [Login Flow](02-login.md)

346
docs/mibapi/02-login.md Normal file
View File

@@ -0,0 +1,346 @@
# Login Flow
MIB uses a two-phase authentication model:
| Phase | Trigger | Key used |
|---|---|---|
| **Device Registration** | First time this device+account pair is seen | `DEFAULT_KEY` → DH session key |
| **Regular Login** | Every subsequent login (stored `key1`/`key2`) | `key1` → DH session key |
---
## Password Hashing (`pgf03`)
The password is never sent in plaintext. Required by both `C41` (registration) and `A41` (login).
```
pgf03 = SHA256( clientSalt + SHA256( userSalt + SHA256( password ) ) )
```
All SHA-256 values are uppercase hex strings. `clientSalt` is a fresh random 32-character alphanumeric string each time.
```python
import hashlib
def compute_pgf03(password: str, user_salt: str, client_salt: str) -> str:
h1 = hashlib.sha256(password.encode()).hexdigest().upper()
h2 = hashlib.sha256((user_salt + h1).encode()).hexdigest().upper()
return hashlib.sha256((client_salt + h2).encode()).hexdigest().upper()
```
---
## Device Registration Flow (first time only)
```
[0] sfunc=r DEFAULT_KEY → DH exchange → derive session_key_1, get xxid + nonceGenerator
[1] sfunc=n A44 → get userSalt
[2] sfunc=n C41 → submit credentials → returns key1, key2 (persist!)
[3] sfunc=n C42 → verify OTP
[4–8] regular login (below) using the key1/key2 just received
```
---
## Regular Login Flow
```
[0] sfunc=i key1 → DH exchange → derive session_key_2, get xxid + nonceGenerator
[1] sfunc=n A44 → get userSalt
[2] sfunc=n A41 → submit credentials → returns otpTypes, email, uuid
[3] sfunc=n P41 → fetch profile image (optional)
[4] sfunc=n A42 → verify OTP → session established
[5] sfunc=n P47 → select profile → returns accountBalance array
```
---
## Step-by-Step Reference
### [0] Initial Key Exchange — `sfunc=r`
**Key**: `DEFAULT_KEY = 8M3L9SBF1AC4FRE56788M3L9SBF1AC4FRE5678`
**Request** (outer + inner are encrypted together):
```json
{
"sfunc": "r",
"data": {
"cmod": "<G^A mod P as decimal string>",
"appId": "IOS17.2-<15 random alphanumeric chars>",
"routePath": "S40",
"sodium": "<random 20-bit int as string>",
"xxid": "<random 40-bit int as string>"
}
}
```
**Response** (decrypted with `DEFAULT_KEY`):
```json
{
"success": true,
"reasonCode": "201",
"reasonText": "Key generated successfully.",
"smod": "<server DH public key as decimal string>",
"nonceGenerator": "<instruction string>",
"xxid": "<session token — use for all subsequent calls>",
"sodium": "<server random>",
"encMethod": 2
}
```
After: `session_key = derive_session_key(int(smod))`. Save `xxid` and `nonceGenerator`.
---
### [1] Get Auth Type — `sfunc=n`, `routePath: A44`
**Key**: session key
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"uname": "<username>",
"nonce": "<computed nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "A44",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"data": [{ "loginType": "1", "userSalt": "<server salt>" }]
}
```
Use `userSalt` in `pgf03` computation.
---
### [2a] Device Registration Init — `sfunc=n`, `routePath: C41`
_First-time only._
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"uname": "<username>",
"pgf03": "<computed>",
"clientSalt": "<random 32-char string>",
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "C41",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "201",
"primaryOTPType": "3",
"otpTypes": [2, 3],
"fullName": "<user full name>",
"customerImgHash": "<hash>"
}
```
---
### [3a] OTP Verification (Registration) — `sfunc=n`, `routePath: C42`
_First-time only. Receive and persist `key1`/`key2`._
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"otp": "<6-digit OTP>",
"uname": "<username>",
"otpType": "3",
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "C42",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "101",
"data": [{
"key1": "<store securely — Blowfish key for next sfunc=i>",
"key2": "<store securely — sent plaintext in sfunc=i wrapper>",
"appId": "<appId>",
"encryptionMethod": "2"
}]
}
```
`key1` and `key2` are long-lived device credentials. Store them securely on the device.
---
### [0b] Authenticated Key Exchange — `sfunc=i`
_Regular login. `key2` is a separate unencrypted outer field._
**Key**: `key1`
Form body: `key2=<key2>&sfunc=i&data=<encrypted payload>`
**Encrypted payload**:
```json
{
"sfunc": "i",
"key2": "<key2>",
"data": {
"cmod": "<G^A mod P>",
"appId": "<appId>",
"routePath": "S40",
"sodium": "<random 20-bit int>",
"xxid": "<random 40-bit int>"
}
}
```
**Response** (decrypted with `key1`):
```json
{
"success": true,
"smod": "<new server DH public key>",
"nonceGenerator": "<new instruction string>",
"xxid": "<new session token>",
"encMethod": 2
}
```
After: derive new session key, replace `xxid` and `nonceGenerator`.
---
### [2b] Regular Login Init — `sfunc=n`, `routePath: A41`
**Key**: session key
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"uname": "<username>",
"pgf03": "<computed>",
"clientSalt": "<random 32-char>",
"pmodTime": 0,
"requireBankData": 1,
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "A41",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "104",
"primaryOTPType": "3",
"otpTypes": [2, 3],
"email": "<masked email>",
"uuid": "<uuid1>",
"uuid2": "<uuid2>"
}
```
---
### [3b] Get Profile Image — `sfunc=n`, `routePath: P41`
Optional. Fetch the user's avatar to display on the OTP screen.
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"imageHash": "<customerImgHash from C41/A41>",
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "P41",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "201",
"profileImage": "<base64-encoded JPEG>"
}
```
---
### [4b] OTP Verification (Login) — `sfunc=n`, `routePath: A42`
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"otp": "<6-digit OTP>",
"uname": "<username>",
"otpType": "3",
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "A42",
"xxid": "<session xxid>"
}
}
```
After successful `A42`, the `xxid` and `nonceGenerator` from the `sfunc=i` response become the WebView session cookies. See [README](README.md) for the cookie format.
---
### [5] Select Profile — `sfunc=n`, `routePath: P47`
See [03-accounts.md](03-accounts.md) for the full P47 reference.
---
&nbsp;
---
[← Encryption](01-encryption.md) &nbsp;&nbsp;&nbsp; **Next →** [Accounts](03-accounts.md)

137
docs/mibapi/03-accounts.md Normal file
View File

@@ -0,0 +1,137 @@
# Accounts & Balances
Account numbers and balances are returned by the **Select Profile** call (`routePath: P47`). The login init call (`A41`) returns an empty `accountBalance` array — balances are only available after `P47`.
---
## Select Profile — `sfunc=n`, `routePath: P47`
**Key**: session key (from `sfunc=i` response)
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"profileType": "<profileType from A41 operatingProfiles>",
"profileId": "<profileId from A41 operatingProfiles>",
"nonce": "<computed nonce>",
"appId": "<appId>",
"sodium": "<random 20-bit int>",
"routePath": "P47",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "101",
"reasonText": "Profile Selected!",
"landingPage": "0",
"accountBalance": [ ... ],
"accessRights": { ... },
"services": []
}
```
To switch between profiles (personal ↔ business), call `P47` again with the other profile's `profileId` and `profileType`.
---
## Profiles (from `A41` response)
The `A41` login init response includes `operatingProfiles`:
```json
{
"operatingProfiles": [
{
"profileId": "<profile ID>",
"customerProfileId": "<customer profile ID>",
"annexId": "<annex ID>",
"customerId": "<customer ID>",
"name": "<display name>",
"cifType": "Individual",
"customerImage": "<image hash>",
"profileType": "0",
"color": "<hex color>"
}
]
}
```
| `profileType` | Meaning |
|---|---|
| `"0"` | Individual (personal) |
| `"1"` | Sole Proprietor (business) |
---
## `accountBalance` Array
Each element represents one account:
```json
{
"cif": "<CIF number>",
"accountNumber": "<full account number>",
"accountBriefName": "<short label, e.g. 'SAR MVR - Savings'>",
"template": "<display template ID>",
"currencyCode": "<ISO 4217 numeric>",
"currencyName": "<ISO 4217 alpha>",
"accountTypeName": "<account type label>",
"transfer": "Y",
"branchName": "<branch name>",
"availableBalance": "<decimal string>",
"currentBalance": "<decimal string>",
"blockedAmount": "<decimal string, may be negative>",
"settlementBalance": "<decimal string>",
"mvrBalance": "<MVR equivalent>",
"statusDesc": "Active"
}
```
| Field | Description |
|---|---|
| `accountNumber` | Full account number |
| `accountBriefName` | Human-readable account label |
| `currencyCode` | ISO 4217 numeric (e.g. `"462"` = MVR, `"840"` = USD) |
| `currencyName` | ISO 4217 alpha (e.g. `"MVR"`, `"USD"`) |
| `accountTypeName` | Account type (e.g. `"Saving Account"`) |
| `availableBalance` | Spendable balance (decimal string) |
| `currentBalance` | Ledger balance (decimal string) |
| `blockedAmount` | Held/blocked funds — negative means funds are held |
| `settlementBalance` | Balance including pending settlements |
| `mvrBalance` | All balances converted to MVR for unified display |
| `transfer` | `"Y"` if usable as transfer source |
| `statusDesc` | Account status (e.g. `"Active"`) |
| `cif` | Customer Information File number |
| `template` | UI template ID |
> All balance fields are **decimal strings**, not numbers — parse with `Decimal` for precision.
---
## `accessRights`
```json
{
"numAccounts": "<number of accounts>",
"packageRights": "[1,2,3,4,6,7,8,9,10,11,12]",
"roleRights": "[]"
}
```
`packageRights` is a JSON array encoded as a string — parse it separately.
---
&nbsp;
---
[← Login Flow](02-login.md) &nbsp;&nbsp;&nbsp; **Next →** [Transaction History](04-history.md)

107
docs/mibapi/04-history.md Normal file
View File

@@ -0,0 +1,107 @@
# Transaction History
Fetch paginated transaction history for a single MIB account. Served from the WebView subdomain.
---
## Endpoint
```
POST https://faisamobilex-wv.mib.com.mv/ajaxAccounts/trxHistory
```
---
## Authentication
See [README](README.md) for cookie and AJAX header format.
```
Referer: https://faisamobilex-wv.mib.com.mv//accountDetails?trxh=1&dashurl=1&accountNo=<accountNo>
```
---
## Request Body (form-urlencoded)
| Field | Example | Description |
|---|---|---|
| `accountNo` | `90101000000001000` | Account number to fetch history for |
| `trxNo` | `` | Transaction number filter (empty = all) |
| `trxType` | `0` | Transaction type filter (`0` = all) |
| `sortTrx` | `date` | Sort field |
| `sortDir` | `desc` | Sort direction |
| `fromDate` | `` | From date filter (empty = no filter) |
| `toDate` | `` | To date filter (empty = no filter) |
| `start` | `1` | Start record index (1-based) |
| `end` | `20` | End record index (`start + pageSize - 1`) |
| `includeCount` | `1` | Include `total_count` in response |
### Pagination
Page size is 20. Compute `start`/`end` per page:
| Page | `start` | `end` |
|---|---|---|
| 1 | `1` | `20` |
| 2 | `21` | `40` |
| N | `(N-1)*20 + 1` | `N*20` |
Stop when total fetched equals `total_count` or `data` is empty.
---
## Response
```json
{
"success": true,
"total_count": "87",
"data": [
{
"trxNumber": "TXN20260516001",
"trxDate": "2026-05-16",
"descr1": "Transfer Debit",
"baseAmount": "-500.00",
"curCodeDesc": "MVR",
"benefName": "Mohamed Ali",
"trxNumber2": "FT20260516001"
},
{
"trxNumber": "TXN20260515001",
"trxDate": "2026-05-15",
"descr1": "Transfer Credit",
"baseAmount": "1000.00",
"curCodeDesc": "MVR",
"benefName": "",
"trxNumber2": ""
}
]
}
```
| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` on success |
| `total_count` | `string` | Total transaction count — parse to `int` |
| `data` | `array` | Transactions for this page |
### Transaction Object
| Field | Type | Description |
|---|---|---|
| `trxNumber` | `string` | Unique transaction ID |
| `trxDate` | `string` | Transaction date (`YYYY-MM-DD`) |
| `descr1` | `string` | Transaction description — trim whitespace |
| `baseAmount` | `string` | Decimal string — **negative = debit, positive = credit** |
| `curCodeDesc` | `string` | Currency code (e.g. `"MVR"`, `"USD"`) |
| `benefName` | `string` | Counterparty name — blank or literal `"null"` means none |
| `trxNumber2` | `string` | Secondary reference; may be blank |
---
&nbsp;
---
[← Accounts](03-accounts.md) &nbsp;&nbsp;&nbsp; **Next →** [Cards](05-cards.md)

86
docs/mibapi/05-cards.md Normal file
View File

@@ -0,0 +1,86 @@
# Cards
Fetch debit card information for the authenticated session.
---
## Endpoint
```
POST https://faisamobilex-wv.mib.com.mv/ajaxDebitCard/fetchCardInfos
```
---
## Authentication
See [README](README.md) for cookie and AJAX header format.
```
Referer: https://faisamobilex-wv.mib.com.mv//debitCards?dashurl=1
```
---
## Request Body (form-urlencoded)
| Field | Value | Description |
|---|---|---|
| `name` | `` | Card name filter (empty = all) |
| `start` | `1` | Start index (1-based) |
| `end` | `50` | End index |
| `includeCount` | `1` | Include total count |
---
## Response
```json
{
"success": true,
"data": [
{
"cardId": "CARD001",
"maskedCardNumber": "4111 **** **** 1234",
"cardStatus": "A",
"cardType": "D",
"cardTypeDesc": "Debit Card",
"customerId": "C000001",
"phoneNumber": "9600000001",
"cardHolderName": "MOHAMED ALI"
}
]
}
```
| Field | Type | Description |
|---|---|---|
| `success` | `bool` | `true` on success |
| `data` | `array` | List of card objects |
### Card Object
| Field | Type | Description |
|---|---|---|
| `cardId` | `string` | Internal card identifier |
| `maskedCardNumber` | `string` | Partially masked card number for display |
| `cardStatus` | `string` | Card status (`A` = Active) |
| `cardType` | `string` | Card type code (e.g. `D` = Debit) |
| `cardTypeDesc` | `string` | Human-readable card type (e.g. `"Debit Card"`) |
| `customerId` | `string` | Customer ID |
| `phoneNumber` | `string` | Registered phone number |
| `cardHolderName` | `string` | Name on card |
### Failure
```json
{ "success": false }
```
---
&nbsp;
---
[← Transaction History](04-history.md) &nbsp;&nbsp;&nbsp; **Next →** [Financing](06-financing.md)

106
docs/mibapi/06-financing.md Normal file
View File

@@ -0,0 +1,106 @@
# Financing
Fetch active financing deals. Unlike other data endpoints, this returns an HTML page — deal data is embedded in `data-*` attributes on card elements.
---
## Endpoint
```
GET https://faisamobilex-wv.mib.com.mv/financing?dashurl=1
```
---
## Authentication
See [README](README.md) for cookie format.
### Additional Header
| Header | Value |
|---|---|
| `X-Requested-With` | `mv.com.mib.faisamobilex` |
Note: this endpoint uses the app package name as `X-Requested-With`, not `XMLHttpRequest`.
---
## Response
**Content-Type:** `text/html; charset=UTF-8`
Each financing deal is a `<div>` with class `finance-card-holder` and all fields as `data-*` attributes:
```html
<div class="card border finance-card-holder"
data-productDesc = "Product Name"
data-dealStatus = "P"
data-statusDesc = "Approved"
data-dealAmount = "10000.00"
data-dealNo = "12345"
data-paidAmount = "2500.00"
data-outstandingAmount = "7500.00"
data-dealDate = "2024-01-15 00:00:00"
data-overdueAmount = "0"
data-installmentAmount = "500.00"
data-noOfInstallments = "24"
data-lastPaidDate = "2026-05-01 00:00:00"
data-lastPayAmount = "500.00"
data-financeCurrency = "462"
data-curCodeDesc = "MVR">
```
### Data Fields
| Attribute | Type | Description |
|---|---|---|
| `productDesc` | String | Product name (e.g. `"Ujalaa CG Finance"`) |
| `dealStatus` | String | Status code (`P` = Active/Pending) |
| `statusDesc` | String | Human-readable status (e.g. `"Approved"`) |
| `dealAmount` | Decimal | Total financing amount |
| `dealNo` | Integer | Unique deal/contract number |
| `paidAmount` | Decimal | Amount paid to date |
| `outstandingAmount` | Decimal | Remaining unpaid balance |
| `dealDate` | String | Contract start date (`yyyy-MM-dd HH:mm:ss`) |
| `overdueAmount` | Decimal | Amount currently overdue (`0` if none) |
| `installmentAmount` | Decimal | Monthly installment amount |
| `noOfInstallments` | Integer | Total number of installments |
| `lastPaidDate` | String | Date of most recent payment (`yyyy-MM-dd HH:mm:ss`) |
| `lastPayAmount` | Decimal | Amount of most recent payment |
| `financeCurrency` | Integer | Currency numeric code (`462` = MVR) |
| `curCodeDesc` | String | Currency abbreviation (e.g. `"MVR"`) |
### Parsing
```kotlin
val cardPattern = Regex("""finance-card-holder[^>]+>""")
val attrPattern = Regex("""data-(\w+)\s*=\s*"([^"]*)"""")
```
Find all `finance-card-holder` elements, then extract `data-*` key/value pairs from each match.
---
## Completion Date Estimation
```
remainingInstallments = ceil(outstandingAmount / installmentAmount)
completionDate = today + remainingInstallments months
```
---
## Notes
- No encryption — session maintained purely via cookies.
- The response is gzip/brotli compressed; OkHttp handles decompression automatically.
- `time-tracker=597` appears static — omitting it may affect behavior.
---
&nbsp;
---
[← Cards](05-cards.md) &nbsp;&nbsp;&nbsp; **Next →** [Personal Profile](07-profile.md)

92
docs/mibapi/07-profile.md Normal file
View File

@@ -0,0 +1,92 @@
# Personal Profile
Fetch the user's personal profile details. This endpoint returns an HTML page; data is extracted via HTML scraping.
---
## Endpoint
```
GET https://faisamobilex-wv.mib.com.mv/personalProfile
```
---
## Authentication
Session cookies only — no additional AJAX headers required.
```
Cookie: mbmodel=IOS-1.0; xxid=<session_xxid>; IBSID=<session_xxid>; mbnonce=<nonceGenerator>; time-tracker=597
```
---
## Response
**Content-Type:** `text/html; charset=UTF-8`
The page contains an `<h5>` with the user's full name and `<span>` elements with labelled fields.
### Parsing Strategy
**Full name** — extracted from:
```html
<h5 class="mb-1 text-dark fw-semibold">Mohamed Ali</h5>
```
Regex:
```kotlin
Regex("""<h5 class="mb-1 text-dark fw-semibold">\s*([^<]+)\s*</h5>""")
```
**Labelled fields** — each follows this pattern:
```html
<span ...><b ...>Username:</b ...>...<span ...>myusername</span>
```
Regex (used for each label):
```kotlin
Regex(
"""<span[^>]*>\s*<b[^>]*>\s*$label\s*</b[^>]*>.*?<span[^>]*>([^<]+)</span>""",
setOf(RegexOption.DOT_MATCHES_ALL, RegexOption.IGNORE_CASE)
)
```
---
## Extracted Fields
| Label in HTML | Field | Description |
|---|---|---|
| `Username:` | `username` | Login username |
| `Email:` | `email` | Registered email address |
| `Mobile no:` | `mobile` | Registered mobile number |
| `Enrolled:` | `enrolled` | Enrollment date or status |
Combined with the `fullName` from the `<h5>`:
```kotlin
data class MibPersonalProfile(
val fullName: String,
val username: String,
val email: String,
val mobile: String,
val enrolled: String
)
```
---
## Notes
- Returns `null` if the response cannot be parsed (network error or unexpected HTML structure).
- This endpoint does not have a JSON equivalent — scraping is the only method.
---
&nbsp;
---
[← Financing](06-financing.md) &nbsp;&nbsp;&nbsp; **Next →** [Transfer](08-transfer.md)

208
docs/mibapi/08-transfer.md Normal file
View File

@@ -0,0 +1,208 @@
# Account Lookup & Transfer
Two-step process: look up the recipient to validate the account and get the holder name, then execute the transfer.
All endpoints are on the WebView subdomain. See [README](README.md) for cookie and AJAX header format.
```
Referer: https://faisamobilex-wv.mib.com.mv/transfer/quick
```
---
## Step 1 — Account Lookup
The lookup endpoint depends on the format of the input:
| Input format | Endpoint | Body field |
|---|---|---|
| Starts with `7`, exactly 13 digits | `AjaxAlias/getIPSAccount` | `benefAccount` |
| Starts with `9`, exactly 17 digits | `ajaxBeneficiary/getAccountName` | `accountNo` |
| Starts with `7` or `9`, exactly 7 digits | `AjaxAlias/getAlias` | `aliasName` |
| Starts with `A` followed by 6 digits | `AjaxAlias/getAlias` | `aliasName` |
| Contains `@` (email) | `AjaxAlias/getAlias` | `aliasName` |
---
### 1a. IPS Account — BML / local bank (13 digits, starts with `7`)
```
POST https://faisamobilex-wv.mib.com.mv/AjaxAlias/getIPSAccount
```
Body: `benefAccount=7700000000000`
**Response**:
```json
{
"success": true,
"responseCode": "2",
"accountName": "ACCOUNT HOLDER NAME",
"bankBic": "MALBMVMV"
}
```
- `accountName` — account holder name
- `bankBic` — bank BIC (e.g. `MALBMVMV` for BML)
- Account number is the input itself — not returned in response
Use `bankNo=3` and `transferLocal` for the transfer.
---
### 1b. MIB Internal Account (17 digits, starts with `9`)
```
POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getAccountName
```
Body: `accountNo=90100000000000000`
**Response**:
```json
{
"success": true,
"accountName": "ACCOUNT HOLDER NAME"
}
```
- `accountName` may be at root level or inside a `data` object — check both
- Bank is always MIB (`MADVMVMV`)
Use `bankNo=2` and `transferInternal` for the transfer.
---
### 1c. Favara Alias — shortcodes, A-IDs, emails
```
POST https://faisamobilex-wv.mib.com.mv/AjaxAlias/getAlias
```
Body: `aliasName=<alias>`
**Response**:
```json
{
"success": true,
"responseCode": "2",
"data": {
"BfyNm": "Account Holder Name",
"CdtrAcct": {
"Acct": "90100000000000000",
"FinInstnId": "MADVMVMV"
}
}
}
```
- `BfyNm` — beneficiary name (trim whitespace)
- `CdtrAcct.Acct` — resolved account number to use for the transfer
- `CdtrAcct.FinInstnId` — bank BIC (`MADVMVMV` = MIB, `MALBMVMV` = BML)
Use `bankNo=2` (MIB) or `3` (BML/local) depending on `FinInstnId`, and the matching transfer endpoint.
---
### Lookup Errors
All three lookup endpoints return `success: false` with a human-readable `reasonText` on failure:
```json
{
"success": false,
"reasonText": "Account not found"
}
```
Always show `reasonText` directly to the user.
---
## Step 2 — Execute Transfer
Two endpoints depending on the destination bank:
| `bankNo` | Endpoint | Destination |
|---|---|---|
| `2` | `ajaxTransfer/transferInternal` | MIB internal account |
| `3` | `ajaxTransfer/transferLocal` | BML or other local bank |
```
POST https://faisamobilex-wv.mib.com.mv/ajaxTransfer/transferInternal
POST https://faisamobilex-wv.mib.com.mv/ajaxTransfer/transferLocal
```
### Request Body (form-urlencoded)
| Field | Description |
|---|---|
| `benefName` | Recipient name (from lookup) |
| `benefNo` | `0` (not a saved contact) |
| `fromAccountNo` | Source account number |
| `benefAccountNo` | Destination account number |
| `transferCy` | Currency numeric code (`"462"` = MVR, `"840"` = USD) |
| `benefCurrencyCode` | Same as `transferCy` |
| `amount` | Amount as string (e.g. `"100.00"`) |
| `bankNo` | `2` = MIB internal, `3` = local/BML |
| `purpose` | Transfer purpose; send `"-"` if blank |
| `otp` | OTP from the user |
| `otpType` | `"3"` (SMS/authenticator OTP) |
### Response — Success
```json
{
"success": true,
"data": [
{
"trxId": "TRX20260516001",
"date": "2026-05-16 15:10:25"
}
]
}
```
| Field | Description |
|---|---|
| `trxId` | Transaction ID |
| `date` | Completion timestamp |
### Response — Failure
```json
{
"success": false,
"reasonText": "Insufficient balance"
}
```
`reasonText` contains the error reason. On HTTP `419`, the session has expired — re-login required.
---
## Transfer Type Summary
| Recipient | Lookup endpoint | `bankNo` | Transfer endpoint |
|---|---|---|---|
| MIB (17-digit `9…`) | `getAccountName` | `2` | `transferInternal` |
| BML (13-digit `7…`) | `getIPSAccount` | `3` | `transferLocal` |
| Favara alias → MIB | `getAlias` | `2` | `transferInternal` |
| Favara alias → BML | `getAlias` | `3` | `transferLocal` |
---
## Currency Codes
| `transferCy` | Currency |
|---|---|
| `"462"` | MVR (Maldivian Rufiyaa) |
| `"840"` | USD |
---
&nbsp;
---
[← Personal Profile](07-profile.md) &nbsp;&nbsp;&nbsp; **Next →** [Contacts](09-contacts.md)

229
docs/mibapi/09-contacts.md Normal file
View File

@@ -0,0 +1,229 @@
# Contacts (Beneficiaries)
Manage the user's saved beneficiary list. All endpoints use WebView session auth — see [README](README.md).
```
Referer: https://faisamobilex-wv.mib.com.mv/beneficiary?dashurl=1
```
---
## List Categories
```
POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getCategories
```
Empty POST body.
### Response
```json
{
"success": true,
"data": [
{ "id": "100001", "categoryName": "Myself", "numBenef": "2" },
{ "id": "100002", "categoryName": "Friends", "numBenef": "10" },
{ "id": "100003", "categoryName": "Business", "numBenef": "8" },
{ "id": "100004", "categoryName": "Family", "numBenef": "5" }
]
}
```
| Field | Description |
|---|---|
| `id` | Category ID — use as `searchCategoryId` when filtering contacts |
| `categoryName` | Display name |
| `numBenef` | Number of beneficiaries in this category (string) |
---
## List Contacts
```
POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/main
```
### Request Body (form-urlencoded)
| Field | Example | Description |
|---|---|---|
| `page` | `1` | Page number (1-based) |
| `search` | `` | Search query (empty = all) |
| `searchCategoryId` | `0` | Category filter (`0` = all) |
| `benefType` | `A` | `A`=All, `L`=Local, `I`=Internal, `S`=Swift |
| `sortBenef` | `name` | Sort field |
| `sortDir` | `asc` | Sort direction |
| `start` | `1` | Start record index (1-based) |
| `end` | `100` | End record index |
| `includeCount` | `1` | Include `total_count` |
### Beneficiary Types
| `benefType` | Meaning |
|---|---|
| `I` | Internal (MIB to MIB) |
| `L` | Local (other Maldivian banks, e.g. BML) |
| `S` | Swift (international) |
### Response
```json
{
"success": true,
"total_count": "48",
"data": [
{
"benefNo": "100001",
"benefName": "Person Name",
"benefNickName": "Nickname",
"benefAccount": "7700000000001",
"benefType": "L",
"bankColor": "#AC0000",
"benefBankName": "Bank of Maldives PLC",
"bankCode": "BML",
"benefSwiftCode": "MALBMVMV",
"benefStatus": "A",
"benefBankId": "3",
"transferCy": "462",
"transferCyDesc": "MVR",
"customerImgHash": "abcd1234hash",
"benefCategoryID": "100002"
}
]
}
```
| Field | Description |
|---|---|
| `benefNo` | Unique beneficiary ID — use for delete |
| `benefNickName` | User-assigned nickname (prefer over `benefName` for display) |
| `benefType` | `L`, `I`, or `S` |
| `bankColor` | Hex color for placeholder avatar background |
| `customerImgHash` | Hash for fetching profile photo (`null` if no photo) |
| `benefCategoryID` | Category ID — `"0"` means uncategorized |
| `transferCyDesc` | Currency (e.g. `"MVR"`, `"USD"`) |
---
## Get Profile Image
```
POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getProfileImage
```
Body: `imageHash=<customerImgHash>`
### Response
```json
{
"success": true,
"profileImage": "<base64-encoded JPEG>"
}
```
`profileImage` is raw base64 JPEG with no data URI prefix. Decode with `Base64.decode(value, Base64.DEFAULT)` then `BitmapFactory.decodeByteArray(...)`. Cache decoded bitmaps — the same hash may appear across multiple contacts.
---
## Create Contact
```
POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/createLocalBeneficiary
```
```
Referer: https://faisamobilex-wv.mib.com.mv/beneficiary/createNew
```
### Request Body (form-urlencoded)
| Field | Description |
|---|---|
| `benefType` | `"I"` = MIB internal, `"L"` = local/BML |
| `benefAccount` | Beneficiary account number |
| `benefName` | Full name |
| `nickName` | Display nickname |
| `bankNo` | `2` = MIB, `3` = BML/local |
| `transferCy` | Currency numeric code (`"462"` = MVR) |
| `categoryId` | Category ID (`"0"` = uncategorized) |
| `imageSet` | `"1"` if image provided, `"0"` otherwise |
| `image` | Base64-encoded image (empty string if none) |
| `benefIban` | Leave blank |
| `benefAddress` | Leave blank |
| `benefCity` | Leave blank |
| `benefCountry` | `"4"` |
| `benefBankSwift` | Leave blank |
| `benefBankName` | Leave blank |
| `benefBankBranch` | Leave blank |
| `benefBankAddress` | Leave blank |
| `benefBankCity` | Leave blank |
| `benefBankCountry` | `"4"` |
| `intBankSwift` | Leave blank |
| `intBankName` | Leave blank |
| `intBankAddress` | Leave blank |
| `intBankBranch` | Leave blank |
| `intBankCity` | Leave blank |
| `intBankCountry` | `"4"` |
| `transferCySwift` | `"840"` (USD numeric — static) |
| `email` | Leave blank |
| `contactNumber` | Leave blank |
| `website` | Leave blank |
### Response
```json
{ "success": true }
```
`success: true` confirms the contact was saved.
---
## Delete Contact
```
POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/deleteBeneficiary
```
Body: `benefNo=<benefNo>`
### Response
```json
{ "success": true }
```
---
## Contact Stats
```
POST https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getStats
```
Empty POST body.
### Response
```json
{
"success": true,
"data": [
{ "type": "L", "count": "30" },
{ "type": "I", "count": "10" },
{ "type": "S", "count": "2" }
]
}
```
Gives counts per beneficiary type. Useful for showing tab badges.
---
&nbsp;
---
[← Transfer](08-transfer.md)

172
docs/mibapi/ACCOUNTS.md
View File

@@ -1,172 +0,0 @@
# MIB Faisanet — List Accounts & Balances
Account numbers and balances are returned by the **Select Profile** call (`routePath: P47`).
The login initialization call (`A41`) returns an empty `accountBalance` array until a profile is selected.
---
## Flow to Get Account Balances
```
[0] sfunc=i (key1) → DH key exchange → derive session_key
[1] sfunc=n A44 → get userSalt
[2] sfunc=n A41 → login with password → returns operatingProfiles (no balances yet)
[3] sfunc=n A42 → OTP verify
[4] sfunc=n P47 → select profile → returns accountBalance array
```
Steps 0–3 are the standard login flow (see `LOGIN_FLOW.md`). Step 4 is the new call.
---
## Step 1 — Get Profile List from A41 Response
The `A41` login initialization response includes `operatingProfiles` — the list of
profiles available to the user (personal, business, etc.).
**Relevant fields from A41 response:**
```json
{
"defaultProfile": "2",
"operatingProfiles": [
{
"profileId": "<profile ID>",
"customerProfileId": "<customer profile ID>",
"annexId": "<annex ID>",
"customerId": "<customer ID>",
"name": "<profile display name>",
"cifType": "Individual",
"customerImage": "<image hash>",
"profileType": "0",
"color": "<hex color>"
},
{
"profileId": "<profile ID>",
"customerProfileId": "<customer profile ID>",
"annexId": "<annex ID>",
"customerId": "<customer ID>",
"name": "<business name / owner name>",
"cifType": "Sole Propr",
"customerImage": "<image hash>",
"profileType": "1",
"color": "<hex color>"
}
],
"selectedProfileId": null,
"selectedProfileType": null,
"profileSelected": false
}
```
`profileType` values observed:
| Value | Meaning |
|---|---|
| `"0"` | Individual (personal) |
| `"1"` | Sole Proprietor (business) |
---
## Step 2 — Select Profile (`sfunc=n`, `routePath: P47`)
**Key**: session key (derived from `sfunc=i` response)
**Request:**
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"profileType": "<profileType from operatingProfiles>",
"profileId": "<profileId from operatingProfiles>",
"nonce": "<computed nonce>",
"appId": "<appId>",
"sodium": "<random 20-bit int>",
"routePath": "P47",
"xxid": "<session xxid>"
}
}
```
**Response:**
```json
{
"success": true,
"reasonCode": "101",
"reasonText": "Profile Selected!",
"landingPage": "0",
"accountBalance": [ ... ],
"accessRights": { ... },
"services": []
}
```
---
## accountBalance Array
Each element in `accountBalance` represents one account:
```json
{
"cif": "<CIF number>",
"accountNumber": "<full account number>",
"accountBriefName": "<short label, e.g. 'SAR MVR - Savings'>",
"template": "<display template ID>",
"currencyCode": "<ISO 4217 numeric code>",
"currencyName": "<ISO 4217 alpha code>",
"accountTypeName": "<account type label>",
"transfer": "Y",
"branchName": "<branch name>",
"availableBalance": "<decimal string>",
"currentBalance": "<decimal string>",
"blockedAmount": "<decimal string, may be negative>",
"settlementBalance": "<decimal string>",
"mvrBalance": "<MVR equivalent as decimal string>",
"statusDesc": "Active"
}
```
### Field reference
| Field | Description |
|---|---|
| `accountNumber` | Full account number |
| `accountBriefName` | Human-readable account label |
| `currencyCode` | ISO 4217 numeric (e.g. `"462"` = MVR, `"840"` = USD) |
| `currencyName` | ISO 4217 alpha (e.g. `"MVR"`, `"USD"`) |
| `accountTypeName` | Account type (e.g. `"Saving Account"`) |
| `availableBalance` | Spendable balance |
| `currentBalance` | Ledger balance |
| `blockedAmount` | Held/blocked funds (negative means funds are held) |
| `settlementBalance` | Balance including pending settlements |
| `mvrBalance` | All balances converted to MVR for display |
| `transfer` | `"Y"` if account can be used as transfer source |
| `statusDesc` | Account status (e.g. `"Active"`) |
| `cif` | Customer Information File number |
| `template` | UI template ID (controls how card is rendered in-app) |
---
## accessRights
Also returned in the P47 response, describes what the selected profile can do:
```json
{
"numAccounts": "<number of accounts>",
"packageRights": "[1,2,3,4,6,7,8,9,10,11,12,...]",
"roleRights": "[]"
}
```
`packageRights` is a JSON array encoded as a string — parse it separately.
---
## Notes
- `accountBalance` in the `A41` response is always `[]`. Balances are only returned after `P47`.
- To switch between profiles (personal ↔ business), call `P47` again with the other profile's `profileId` and `profileType`.
- `mvrBalance` is always in MVR regardless of the account's native currency, useful for showing a unified total.
- All balance fields are **decimal strings**, not numbers — parse with `Decimal` for precision.

345
docs/mibapi/API.md
View File

@@ -1,345 +0,0 @@
# Faisanet MIB API Documentation
Reverse-engineered from `mv.com.mib.faisamobilex` (React Native, Hermes bytecode v96).
---
## Base
- **URL**: `https://faisanet.mib.com.mv/faisamobilex_smvc/`
- **Method**: `POST /`
- **Content-Type**: `application/x-www-form-urlencoded; charset=utf-8`
- **User-Agent**: `android/1.0`
- **Accept**: `application/json`
All requests share the same form body structure:
```
sfunc=<function_code>&data=<urlencode(blowfish_ecb_base64_ciphertext)>
```
---
## Encryption
### Algorithm
- **Cipher**: Blowfish, ECB mode, PKCS5 padding
- **Input**: raw UTF-8 bytes of JSON payload string
- **Key**: raw UTF-8 bytes of key string
- **Output**: base64-encoded ciphertext (URL-encoded when sent as form data)
### Python equivalent
```python
from Crypto.Cipher import Blowfish
from Crypto.Util.Padding import pad, unpad
import base64
def encrypt(payload: dict, key: str) -> str:
import json
plaintext = json.dumps(payload).encode()
key_bytes = key.encode('latin-1')
cipher = Blowfish.new(key_bytes, Blowfish.MODE_ECB)
ct = cipher.encrypt(pad(plaintext, Blowfish.block_size))
return base64.b64encode(ct).decode()
def decrypt(ciphertext_b64: str, key: str) -> dict:
import json
key_bytes = key.encode('latin-1')
ct = base64.b64decode(ciphertext_b64)
cipher = Blowfish.new(key_bytes, Blowfish.MODE_ECB)
plaintext = unpad(cipher.decrypt(ct), Blowfish.block_size)
return json.loads(plaintext.decode())
```
### Key lifecycle
| Phase | Key used |
|---|---|
| `sfunc=r` (key exchange) | `DEFAULT_KEY` (hardcoded in app) |
| All subsequent requests | DH-derived session key |
**DEFAULT_KEY** (hardcoded):
```
8M3L9SBF1AC4FRE56788M3L9SBF1AC4FRE5678
```
---
## Diffie-Hellman Key Exchange
The app uses a **custom Diffie-Hellman** scheme to derive a session key.
### Fixed parameters (hardcoded in app)
> Note: the variable names in the app's source are swapped from their DH role.
> `A_VALUE` in the source is the **exponent** (shorter number), `P_VALUE` is the **prime modulus** (longer number).
```
G (generator) = 2
A (client privkey) = 1563516802667282387226490351799736881442299778484610378722158765594241028592123324764949712696577
P (prime modulus) = 2410312426921032588552076022197566074856950548502459942654116941958108831682612228890093858261341614673227141477904012196503648957050582631942730706805009223062734745341073406696246014589361659774041027169249453200378729434170325843778659198143763193776859869524088940195577346119843545301547043747207749969763750084308926339295559968882457872412993810129130294592999947926365264059284647209730384947211681434464714438488520940127459844288859336526896320919633919
```
> **Note**: `A` (client private key) is hardcoded in the app — this DH provides no real security.
### Session key derivation
```python
import hashlib, base64
def derive_session_key(smod: int) -> str:
A = 1563516802667282387226490351799736881442299778484610378722158765594241028592123324764949712696577
P = 2410312426921032588552076022197566074856950548502459942654116941958108831682612228890093858261341614673227141477904012196503648957050582631942730706805009223062734745341073406696246014589361659774041027169249453200378729434170325843778659198143763193776859869524088940195577346119843545301547043747207749969763750084308926339295559968882457872412993810129130294592999947926365264059284647209730384947211681434464714438488520940127459844288859336526896320919633919
shared_secret = pow(smod, A, P)
sha256_hex = hashlib.sha256(str(shared_secret).encode()).hexdigest().upper()
return base64.b64encode(bytes.fromhex(sha256_hex)).decode()
```
The resulting session key is always a **44-character base64 string** (32 bytes / 256-bit SHA-256 output), for example:
```
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX=
```
It changes every session because `smod` is different each time.
---
## Endpoints (sfunc values)
### `r` — Key Exchange (initiate session)
**Request payload** (encrypted with DEFAULT_KEY):
```json
{
"sfunc": "r",
"data": {
"cmod": "<G^A mod P as decimal string>",
"appId": "IOS17.2-<random 15-char string>",
"routePath": "S40",
"sodium": "<random 20-bit integer as string>",
"xxid": "<random 40-bit integer as string>"
}
}
```
**Response payload** (encrypted with DEFAULT_KEY):
```json
{
"success": true,
"responseCode": "1",
"reasonCode": "201",
"reasonText": "Key generated successfully.",
"smod": "<server DH public key as decimal string>",
"nonceGenerator": "<instruction string for nonce computation>",
"xxid": "<session token>",
"sodium": "<server random>",
"encMethod": 1
}
```
After this call:
- Compute `encryptionKey = derive_session_key(int(smod))`
- Store `xxid` and `nonceGenerator` for subsequent calls
---
## Request envelope structure
All requests after key exchange use this structure:
```json
{
"sfunc": "<function_code>",
"xxid": "<session xxid>",
"data": {
"nonce": "<computed from nonceGenerator>",
"appId": "<same appId>",
"sodium": "<random 20-bit>",
"routePath": "<route constant>",
"xxid": "<session xxid>",
...additional fields...
}
}
```
Encrypted with the DH-derived `encryptionKey`.
---
## Login Flows
### First-time device registration (no stored key1/key2)
1. `sfunc=r` → `S40` — DH key exchange with `DEFAULT_KEY` → receive `xxid`, `nonceGenerator`, `smod` → derive session key
2. `sfunc=n` → `A44` — get `userSalt` for username
3. `sfunc=n` → `C41` — submit `pgf03` (computed from password + userSalt + random clientSalt)
4. `sfunc=n` → `C42` — verify TOTP OTP → receive `key1` and `key2`; persist them
5. Continue with regular login below (using the just-received key1/key2)
### Regular login (stored key1/key2 present)
1. `sfunc=i` → `S40` — DH key exchange with `key1`, sending `key2` as extra form field → derive session key
2. `sfunc=n` → `A44` — get `userSalt` for username
3. `sfunc=n` → `A41` — submit `pgf03` → receive `operatingProfiles` list
4. For each profile: `sfunc=n` → `P47` — fetch `accountBalance` array
> **No A42 step in regular login.** OTP is only verified once during first-time registration (C42).
### pgf03 formula
```python
h1 = SHA256(password).hexdigest().upper()
h2 = SHA256(h1 + userSalt).hexdigest().upper()
pgf03 = SHA256(clientSalt + h2).hexdigest().upper()
```
`clientSalt` is a random 32-character alphanumeric string generated fresh each login.
---
## Known route paths
| sfunc | routePath | Description |
|---|---|---|
| `r` | `S40` | DH key exchange (first-time registration) |
| `i` | `S40` | DH key exchange (regular login, sends `key1`/`key2`) |
| `n` | `A44` | Get auth type — returns `userSalt` for the given `uname` |
| `n` | `C41` | Registration: submit credentials (`uname`, `pgf03`, `clientSalt`) |
| `n` | `C42` | Registration: verify OTP (`otp`, `uname`, `otpType=3`) — returns `key1`/`key2` |
| `n` | `A41` | Login: submit credentials (`uname`, `pgf03`, `clientSalt`, `pmodTime`, `requireBankData`) — returns `operatingProfiles` |
| `n` | `P47` | Fetch account balances for a profile (`profileType`, `profileId`) — returns `accountBalance` array |
| `n` | `P40` | Update profile image |
| `n` | `P42` | Delete profile image |
> Note: `A42` (login OTP verify) is **not sent** during regular login. It was present in an older flow but is no longer used. `C42` is only sent during first-time device registration.
---
## Nonce Computation
Every request after key exchange includes a `nonce` field computed from the `nonceGenerator`
string returned by the key exchange response.
### nonceGenerator format
A string of 4 groups separated by `-`. Each group contains 8 space-separated tokens.
Each token is a letter followed by a number (e.g. `M85`, `A37`, `C95`, `X2`).
```
M85 A87 A82 M82 M60 M31 A46 C95-M14 X83 A37 X2 C4 X22 X46 C95-M57 X29 C51 C34 S91 X60 S1 A15-M54 A89 S13 S18 C81 A70 X92 X59
```
### Nonce output format
4 groups separated by `-`. Each group: a zero-padded 5-digit number followed by 7 two-digit
numbers separated by spaces.
```
08160 19 73 45 17 89 07 10-00924 64 73 18 08 48 80 67-01026 20 17 13 26 26 43 24-00648 12 32 17 69 14 63 92
```
### Algorithm
**Phase 1 — process first token of each group (produces seed values):**
For each of the 4 groups (index `i`):
1. Take `token[0]` (e.g. `M85`). Extract the number: `N = parseInt(token.replace(/\D/g, ''))`.
2. Generate a random integer: `r = floor(random() * 99) + 1` (range 1–99 inclusive).
3. Compute `product = N * r`. Zero-pad to 5 digits: `padded = product.toString().padStart(5, '0')`.
4. Compute `digitSum[i]` = sum of all digits in `padded`.
5. Store `lastTwo[i]` = `parseInt(padded.slice(-2))` (last two digits as integer).
6. Accumulate `cumSum += digitSum[i]`.
After all 4 groups: `cumSum` = sum of all four `digitSum` values.
**Phase 2 — process tokens 1–7 of each group (produces nonce digits):**
For each group (index `i`), process `token[1]` through `token[7]`:
- Initialise `carry = lastTwo[i]`.
- For each token at position `j` (1–7):
- Extract letter `op` and number `num`.
- Compute `val` based on `op`:
| op | formula |
|---|---|
| `M` | `(carry % num) + digitSum[i] + cumSum` |
| `A` | `carry + num + digitSum[i] + cumSum` |
| `S` | `(carry * carry) + num + digitSum[i] + cumSum` |
| `X` | `(carry * num) + digitSum[i] + cumSum` |
| `C` | `(carry * carry * carry) + num + digitSum[i] + cumSum` |
- Nonce digit = `parseInt(val.toString().slice(-2))` (last two digits as integer).
- Update `carry = nonceDigit` for the next token.
**Assembling the nonce string:**
For each group `i`:
```
group_str = padded[i] + " " + nonceDigit[i][0].toString().padStart(2,'0') + " " + ... (7 digits)
```
Join 4 groups with `-`.
### Python implementation
```python
import math, random
def generate_nonce(nonce_generator: str) -> str:
groups = nonce_generator.split('-')
padded_list, last_two, digit_sum = [], [], []
cum_sum = 0
# Phase 1
for group in groups:
tokens = group.split(' ')
n = int(''.join(c for c in tokens[0] if c.isdigit()))
r = math.floor(random.random() * 99) + 1
product = n * r
padded = str(product).zfill(5)
ds = sum(int(d) for d in padded)
lt = int(padded[-2:])
padded_list.append(padded)
last_two.append(lt)
digit_sum.append(ds)
cum_sum += ds
# Phase 2
result_groups = []
for i, group in enumerate(groups):
tokens = group.split(' ')
carry = last_two[i]
ds = digit_sum[i]
nonce_digits = []
for token in tokens[1:]:
op = ''.join(c for c in token if c.isalpha())
num = int(''.join(c for c in token if c.isdigit()))
if op == 'M':
val = (carry % num) + ds + cum_sum
elif op == 'A':
val = carry + num + ds + cum_sum
elif op == 'S':
val = (carry * carry) + num + ds + cum_sum
elif op == 'X':
val = (carry * num) + ds + cum_sum
elif op == 'C':
val = (carry * carry * carry) + num + ds + cum_sum
else:
val = 0
digit = int(str(val)[-2:])
nonce_digits.append(digit)
carry = digit
group_str = padded_list[i] + ' ' + ' '.join(str(d).zfill(2) for d in nonce_digits)
result_groups.append(group_str)
return '-'.join(result_groups)
```
### Notes
- `nonce` and `sodium` are **separate** request fields. `sodium` is an independent random integer
(observed range ~1M–16M, approximately 23–24 bit).
- The nonce string is the same value for both the `nonce` and ... actually they are different fields:
`nonce` = the computed nonce string; `sodium` = a random integer sent as a plain string.
- For `sfunc=i`, `key2` is sent as a **separate form field** (not inside the encrypted payload):
`key2=<key2>&sfunc=i&data=<encrypted>`. The encrypted payload is the inner data object only,
encrypted with `key1`.
- For all `sfunc=n` requests (every request after key exchange), `xxid` is sent as a **separate
unencrypted form field** as the FIRST field:
`xxid=<session_xxid>&sfunc=n&data=<encrypted>`. The `xxid` also appears inside the encrypted
payload. Field order matters — `xxid` must come before `sfunc` and `data`.

180
docs/mibapi/ENCRYPTION.md
View File

@@ -1,180 +0,0 @@
# MIB Faisanet API — Encryption & Decryption
## Overview
All API traffic is encrypted using **Blowfish** in ECB mode with PKCS5 padding.
Every request and response body is a single base64-encoded Blowfish ciphertext.
There are two keys in play:
| Key | Used for |
|---|---|
| `DEFAULT_KEY` (hardcoded) | The initial key exchange request and response (`sfunc=r`) |
| Session key (DH-derived) | Every request and response after the key exchange |
---
## The DEFAULT_KEY
```
8M3L9SBF1AC4FRE56788M3L9SBF1AC4FRE5678
```
This key is hardcoded in the app's JavaScript bundle. It is only used for the
first call (`sfunc=r`) which establishes a session key via Diffie-Hellman.
---
## Session Key Derivation (Diffie-Hellman)
The app uses a custom DH key exchange to derive a per-session Blowfish key.
All three DH parameters are hardcoded in the app:
```
G = 2
P = 1563516802667282387226490351799736881442299778484610378722158765594241028592123324764949712696577
A = 2410312426921032588552076022197566074856950548502459942654116941958108831682612228890093858261341614673227141477904012196503648957050582631942730706805009223062734745341073406696246014589361659774041027169249453200378729434170325843778659198143763193776859869524088940195577346119843545301547043747207749969763750084308926339295559968882457872412993810129130294592999947926365264059284647209730384947211681434464714438488520940127459844288859336526896320919633919
```
`A` is the client's private key. Because it is hardcoded and never rotates,
anyone with the APK can derive the session key from a captured `smod`.
### Step-by-step
1. Client computes `cmod = G^A mod P` and sends it in the `sfunc=r` request.
2. Server computes its own keypair and responds with `smod` (its public key).
3. Client computes the shared secret: `shared = smod^A mod P`
4. Client SHA-256 hashes the decimal string of the shared secret (uppercased hex).
5. Client converts that hex string to raw bytes, then base64-encodes it.
6. The result is the Blowfish key for the rest of the session.
```python
import hashlib, base64
def derive_session_key(smod: int) -> str:
# A_VALUE in app = exponent (shorter), P_VALUE in app = modulus (longer)
A = 1563516802667282387226490351799736881442299778484610378722158765594241028592123324764949712696577
P = 2410312426921032588552076022197566074856950548502459942654116941958108831682612228890093858261341614673227141477904012196503648957050582631942730706805009223062734745341073406696246014589361659774041027169249453200378729434170325843778659198143763193776859869524088940195577346119843545301547043747207749969763750084308926339295559968882457872412993810129130294592999947926365264059284647209730384947211681434464714438488520940127459844288859336526896320919633919
shared = pow(smod, A, P)
sha256_hex = hashlib.sha256(str(shared).encode()).hexdigest().upper()
return base64.b64encode(bytes.fromhex(sha256_hex)).decode()
```
---
## Encrypting a Request
All request payloads follow this JSON structure before encryption:
```json
{
"sfunc": "<function code>",
"xxid": "<session token>",
"data": {
...
}
}
```
### Encryption steps
1. `JSON.stringify` the payload.
2. Use the raw UTF-8 bytes of the payload as plaintext.
3. Use the raw UTF-8 bytes of the key string as the Blowfish key.
4. Encrypt: Blowfish / ECB / PKCS5 padding.
5. Base64-encode the ciphertext.
6. URL-encode the base64 string.
7. Send as form field: `sfunc=<value>&data=<url-encoded-ciphertext>`
```python
import json, base64
from urllib.parse import quote
from Crypto.Cipher import Blowfish
from Crypto.Util.Padding import pad
def encrypt(payload: dict, key: str) -> str:
plaintext = json.dumps(payload, separators=(',', ':')).encode('utf-8')
key_bytes = key.encode('latin-1')
cipher = Blowfish.new(key_bytes, Blowfish.MODE_ECB)
ct = cipher.encrypt(pad(plaintext, Blowfish.block_size))
return base64.b64encode(ct).decode()
def build_request_body(payload: dict, key: str) -> str:
sfunc = payload.get('sfunc', '')
encrypted = encrypt(payload, key)
return f"sfunc={sfunc}&data={quote(encrypted)}"
```
---
## Decrypting a Response
The response body is a raw base64-encoded Blowfish ciphertext (no form encoding).
### Decryption steps
1. Base64-decode the response body to get the ciphertext bytes.
2. Decrypt with Blowfish / ECB / PKCS5 padding using the appropriate key.
3. Parse the result as JSON.
```python
import json, base64
from Crypto.Cipher import Blowfish
from Crypto.Util.Padding import unpad
def decrypt(ciphertext_b64: str, key: str) -> dict:
key_bytes = key.encode('latin-1')
ct = base64.b64decode(ciphertext_b64)
cipher = Blowfish.new(key_bytes, Blowfish.MODE_ECB)
plaintext = unpad(cipher.decrypt(ct), Blowfish.block_size)
return json.loads(plaintext.decode('utf-8'))
```
---
## Full Session Example
### 1. Send key exchange (`sfunc=r`) — use DEFAULT_KEY
Request form body:
```
sfunc=r&data=<base64 of Blowfish(DEFAULT_KEY, {"sfunc":"r","data":{"cmod":"...","appId":"...","routePath":"S40","sodium":"...","xxid":"..."}})>
```
Response (decrypted with DEFAULT_KEY):
```json
{
"success": true,
"smod": "<large decimal integer — server DH public key>",
"nonceGenerator": "<instruction string, e.g. 'M26 C16 C4 C5 M64 ...'>",
"xxid": "<session token>",
"sodium": "<server random hex string>",
"encMethod": 2
}
```
### 2. Derive the session key from `smod`
```python
session_key = derive_session_key(int(response['smod']))
# → a 44-character base64 string, e.g. "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
# The key is 32 bytes (256-bit SHA-256 output) encoded as base64.
```
### 3. All subsequent requests — use session key
Encrypt with `session_key`, decrypt responses with `session_key`.
---
## Quick reference
| What | How |
|---|---|
| Cipher | Blowfish, ECB mode, PKCS5 padding |
| Key for `sfunc=r` | `8M3L9SBF1AC4FRE56788M3L9SBF1AC4FRE5678` |
| Key for everything else | `derive_session_key(smod)` |
| Request encoding | JSON → encrypt → base64 → URL-encode → form field `data=` |
| Response encoding | base64 → decrypt → JSON |
| Key input | raw UTF-8 bytes of key string |
| Plaintext input | raw UTF-8 bytes of JSON string |

449
docs/mibapi/LOGIN_FLOW.md
View File

@@ -1,449 +0,0 @@
# MIB Faisanet — Login Flow
Fully reverse engineered from a captured HAR trace of a first-time device
registration followed immediately by a regular login.
---
## Key Corrections
The DH parameter names in the app's source are **misleading**:
| App variable | DH role | Value |
|---|---|---|
| `A_VALUE` | Exponent / client private key | `15635168026...` (shorter) |
| `P_VALUE` | Prime modulus | `24103124269...` (longer) |
| `G_VALUE` | Generator | `2` |
The session key derivation is:
```python
shared = pow(smod, A_VALUE, P_VALUE) # NOT pow(smod, P_VALUE, A_VALUE)
sha256_hex = SHA256(str(shared)).upper()
session_key = base64(bytes.fromhex(sha256_hex))
```
---
## Overview
The full login sequence consists of two phases:
| Phase | Purpose | Key used |
|---|---|---|
| **Phase 1** — Device registration | First time this device+account pair is seen | DH session key from `sfunc=r` |
| **Phase 2** — Regular login | Every subsequent login | key1/key2 (from phase 1) → second DH → new session key |
---
## Full Flow Diagram
```
Client Server
| |
| [0] sfunc=r (DEFAULT_KEY) |
| { cmod, appId, routePath:S40, ... } |
|--------------------------------------------->|
| { smod, nonceGenerator, xxid, ... } |
|<---------------------------------------------|
| derive session_key_1 = DH(smod) |
| |
| [1] sfunc=n routePath:A44 (session_key_1)|
| { uname } |
|--------------------------------------------->|
| { loginType, userSalt } |
|<---------------------------------------------|
| |
| [2] sfunc=n routePath:C41 (session_key_1)| ← device registration init
| { uname, pgf03, clientSalt } |
|--------------------------------------------->|
| { key1, key2, otpTypes, fullName, ... } |
|<---------------------------------------------|
| |
| [3] sfunc=n routePath:C42 (session_key_1)| ← OTP verify (registration)
| { otp, uname, otpType } |
|--------------------------------------------->|
| { key1, key2, encryptionMethod:2, ... } |
|<---------------------------------------------|
| store key1, key2 on device |
| |
| [4] sfunc=i (key1) | ← second DH key exchange
| { cmod, appId, routePath:S40, key2 } |
|--------------------------------------------->|
| { smod, nonceGenerator, xxid, ... } |
|<---------------------------------------------|
| derive session_key_2 = DH(smod) |
| |
| [5] sfunc=n routePath:A44 (session_key_2)|
| { uname } |
|--------------------------------------------->|
| { loginType, userSalt } |
|<---------------------------------------------|
| |
| [6] sfunc=n routePath:A41 (session_key_2)| ← regular login init
| { uname, pgf03, clientSalt, requireBankData:1 }|
|--------------------------------------------->|
| { primaryOTPType, otpTypes, email, uuid, uuid2, ... }|
|<---------------------------------------------|
| |
| [7] sfunc=n routePath:P41 (session_key_2)| ← fetch profile image
| { imageHash } |
|--------------------------------------------->|
| { profileImage (base64 JPEG) } |
|<---------------------------------------------|
| |
| [8] sfunc=n routePath:A42 (session_key_2)| ← OTP verify (regular login)
| { otp, uname, otpType } |
|--------------------------------------------->|
| { ... session established ... } |
|<---------------------------------------------|
```
---
## Step-by-Step Reference
### [0] Initial Key Exchange — `sfunc=r`
**Key**: `DEFAULT_KEY = 8M3L9SBF1AC4FRE56788M3L9SBF1AC4FRE5678`
**Request body** (inner `data` field):
```json
{
"cmod": "<G^A_VALUE mod P_VALUE as decimal string>",
"appId": "IOS17.2-<15 random chars>",
"routePath": "S40",
"sodium": "<random 20-bit int>",
"xxid": "<random 40-bit int>"
}
```
**Full request** (outer wrapper, encrypted together):
```json
{ "sfunc": "r", "data": { ...above... } }
```
**Response** (decrypted with DEFAULT_KEY):
```json
{
"success": true,
"reasonCode": "201",
"reasonText": "Key generated successfully.",
"smod": "<server DH public key>",
"nonceGenerator": "<instruction string>",
"xxid": "<session token — carry for all subsequent calls>",
"sodium": "<server random>",
"encMethod": 2
}
```
After this step:
- Derive `session_key_1 = derive_session_key(smod)`
- Save `xxid` and `nonceGenerator`
---
### [1] Get Auth Type — `sfunc=n`, `routePath: A44`
**Key**: `session_key_1`
**Request** (encrypted):
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"uname": "<username>",
"nonce": "<computed from nonceGenerator>",
"appId": "<appId>",
"sodium": "<random 20-bit int>",
"routePath": "A44",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "108",
"reasonText": "Auth type retrieved!",
"data": [
{
"loginType": "1",
"userSalt": "<server salt for password hashing>"
}
]
}
```
---
### [2] Device Registration Init — `sfunc=n`, `routePath: C41`
First-time only. Registers this device+account pair.
**Key**: `session_key_1`
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"uname": "<username>",
"pgf03": "<salted password hash — see below>",
"clientSalt": "<random 32-char string>",
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "C41",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "201",
"reasonText": "Registration Initialization Successfully.",
"primaryOTPType": "3",
"roleName": "Consumer Premium",
"otpTypes": [2, 3],
"fullName": "<user's full name>",
"lastLoginTime": "<datetime>",
"customerImgHash": "<hash>"
}
```
---
### [3] OTP Verification (Registration) — `sfunc=n`, `routePath: C42`
**Key**: `session_key_1`
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"otp": "<6-digit OTP>",
"uname": "<username>",
"otpType": "3",
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "C42",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "101",
"reasonText": "registration success",
"data": [
{
"appId": "<appId>",
"createdDate": "<datetime>",
"key1": "<device credential 1 — store securely>",
"key2": "<device credential 2 — store securely>",
"encryptionMethod": "2",
"appAgent": "android/1.0"
}
]
}
```
`key1` and `key2` are long-lived device credentials. `key1` is the Blowfish key
for the next `sfunc=i` call. `key2` is sent as plaintext in the outer wrapper of
that call.
---
### [4] Authenticated Key Exchange — `sfunc=i`
Second DH exchange, authenticated with the device credentials.
**Key**: `key1`
**Request** (outer wrapper includes `key2`):
```json
{
"sfunc": "i",
"key2": "<key2 from registration>",
"data": {
"cmod": "<G^A_VALUE mod P_VALUE>",
"appId": "<appId>",
"routePath": "S40",
"sodium": "<random 20-bit int>",
"xxid": "<random 40-bit int>"
}
}
```
**Response** (decrypted with `key1`):
```json
{
"success": true,
"reasonCode": "201",
"reasonText": "Key generated successfully.",
"smod": "<new server DH public key>",
"nonceGenerator": "<new instruction string>",
"xxid": "<new session token>",
"encMethod": 2
}
```
After this step:
- Derive `session_key_2 = derive_session_key(smod)`
- Replace `xxid` and `nonceGenerator` with new values
---
### [5] Get Auth Type — `sfunc=n`, `routePath: A44`
Same as step [1] but with `session_key_2`. Fetches `userSalt` for password hashing.
---
### [6] Regular Login Init — `sfunc=n`, `routePath: A41`
**Key**: `session_key_2`
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"uname": "<username>",
"pgf03": "<salted password hash>",
"clientSalt": "<random 32-char string>",
"pmodTime": 0,
"requireBankData": 1,
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "A41",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "104",
"reasonText": "Initialization Successful",
"primaryOTPType": "3",
"roleName": "Consumer Premium",
"otpTypes": [2, 3],
"email": "<masked email>",
"uuid": "<uuid1>",
"uuid2": "<uuid2>",
"xxid": "<xxid>"
}
```
---
### [7] Get Profile Image — `sfunc=n`, `routePath: P41`
**Key**: `session_key_2`
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"imageHash": "<customerImgHash from step 2/6>",
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "P41",
"xxid": "<session xxid>"
}
}
```
**Response**:
```json
{
"success": true,
"reasonCode": "201",
"reasonText": "Image Found",
"profileImage": "<base64 JPEG>"
}
```
---
### [8] OTP Verification (Login) — `sfunc=n`, `routePath: A42`
**Key**: `session_key_2`
**Request**:
```json
{
"sfunc": "n",
"xxid": "<session xxid>",
"data": {
"otp": "<6-digit OTP>",
"uname": "<username>",
"otpType": "3",
"nonce": "<nonce>",
"appId": "<appId>",
"sodium": "<random>",
"routePath": "A42",
"xxid": "<session xxid>"
}
}
```
---
## Password Hashing (`pgf03`)
The password is never sent in plaintext. The scheme prevents replay attacks by
mixing in a server-provided salt and a client-generated random salt.
```
pgf03 = SHA256( clientSalt + SHA256( userSalt + SHA256( password ) ) )
```
All SHA256 values are uppercase hex strings.
```python
import hashlib
def compute_pgf03(password: str, user_salt: str, client_salt: str) -> str:
h1 = hashlib.sha256(password.encode()).hexdigest().upper()
h2 = hashlib.sha256((user_salt + h1).encode()).hexdigest().upper()
h3 = hashlib.sha256((client_salt + h2).encode()).hexdigest().upper()
return h3
```
---
## Route Paths Summary
| routePath | sfunc | Description |
|---|---|---|
| `S40` | `r` or `i` | DH key exchange |
| `A44` | `n` | Get auth type / userSalt |
| `A41` | `n` | Regular login initialization |
| `A42` | `n` | OTP verification (regular login) |
| `C41` | `n` | Device registration initialization |
| `C42` | `n` | OTP verification (registration) |
| `P41` | `n` | Get profile image |
| `P40` | `n` | Update profile image |
| `P42` | `n` | Delete profile image |

88
docs/mibapi/README.md Normal file
View File

@@ -0,0 +1,88 @@
# MIB Faisanet API
Reverse-engineered from `mv.com.mib.faisamobilex` (Faisanet Mobile Banking, React Native / Hermes bytecode v96).
[Play Store](https://play.google.com/store/apps/details?id=mv.com.mib.faisamobilex)
---
## Architecture
MIB uses **two completely separate backends**:
| Backend | Base URL | Auth | Used for |
|---|---|---|---|
| Encrypted API | `https://faisanet.mib.com.mv/faisamobilex_smvc/` | Blowfish + DH session key | Login, key exchange |
| WebView host | `https://faisamobilex-wv.mib.com.mv` | Session cookies | Accounts, history, transfers, contacts, cards, financing |
---
## Encrypted API
All calls to the encrypted API are `POST /` with `Content-Type: application/x-www-form-urlencoded; charset=utf-8` and form body:
```
sfunc=<function_code>&data=<url_encoded_base64_blowfish_ciphertext>
```
The request JSON is encrypted with Blowfish (ECB, PKCS5) before sending. The response body is also base64-encoded Blowfish ciphertext.
Two keys are used:
| Phase | Key |
|---|---|
| `sfunc=r` (initial key exchange) | `DEFAULT_KEY` (hardcoded in app) |
| All subsequent requests | DH-derived session key |
See [01-encryption.md](01-encryption.md) for full details.
---
## WebView Session Auth
After login, all data endpoints use cookie-based auth on `faisamobilex-wv.mib.com.mv`:
```
Cookie: mbmodel=IOS-1.0; xxid=<session_xxid>; IBSID=<session_xxid>; mbnonce=<nonceGenerator>; time-tracker=597
```
These values come from the login flow — `xxid` and `nonceGenerator` from the DH key exchange response.
### WebView AJAX Headers
All AJAX `POST` calls also require:
```
X-Requested-With: XMLHttpRequest
Accept: */*
Origin: https://faisamobilex-wv.mib.com.mv
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
```
The `Referer` value varies per endpoint (documented per endpoint).
### WebView User-Agent
```
Mozilla/5.0 (Linux; Android {version}; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36
```
---
## Documents
| # | File | Description |
|---|---|---|
| 1 | [01-encryption.md](01-encryption.md) | Blowfish encryption, DH key exchange, nonce computation |
| 2 | [02-login.md](02-login.md) | Device registration and regular login flows |
| 3 | [03-accounts.md](03-accounts.md) | Select profile, account balances |
| 4 | [04-history.md](04-history.md) | Transaction history |
| 5 | [05-cards.md](05-cards.md) | Debit card list |
| 6 | [06-financing.md](06-financing.md) | Financing deals |
| 7 | [07-profile.md](07-profile.md) | Personal profile (HTML scrape) |
| 8 | [08-transfer.md](08-transfer.md) | Account lookup and fund transfer |
| 9 | [09-contacts.md](09-contacts.md) | Beneficiary management |
---
**Start here →** [01-encryption.md](01-encryption.md)

123
docs/mibapi/accountlookup.md
View File

@@ -1,123 +0,0 @@
# MIB Account Lookup Routing
Before initiating a transfer, the recipient input must be resolved to a verified account name and
account number. Three different endpoints are used depending on the format of the input.
## Input Format Routing
| Input format | Endpoint | Body field |
|-------------------------------------------|---------------------------------------|-----------------|
| Starts with `7`, exactly 13 digits | `AjaxAlias/getIPSAccount` | `benefAccount` |
| Starts with `9`, exactly 17 digits | `ajaxBeneficiary/getAccountName` | `accountNo` |
| Starts with `7` or `9`, exactly 7 digits | `AjaxAlias/getAlias` | `aliasName` |
| Starts with `A` followed by 6 digits | `AjaxAlias/getAlias` | `aliasName` |
| Email address (contains `@`) | `AjaxAlias/getAlias` | `aliasName` |
All endpoints share the same WebView session auth (see `contacts.md` for cookie format) and use
`Referer: https://faisamobilex-wv.mib.com.mv/transfer/quick`.
---
## Endpoint Details
### 1. IPS Account Lookup — Local / BML accounts (13 digits, starts with 7)
**POST** `https://faisamobilex-wv.mib.com.mv/AjaxAlias/getIPSAccount`
Body: `benefAccount=7700000000000` (13 digits)
**Success response:**
```json
{
"success": true,
"responseCode": "2",
"reasonCode": "201",
"reasonText": "Request Successful. Account Found",
"accountName": "ACCOUNT HOLDER NAME",
"bankBic": "MALBMVMV"
}
```
Fields used:
- `accountName` — account holder name
- `bankBic` — bank SWIFT/BIC code
The account number is already known from the input; it is not returned in the response.
---
### 2. MIB Internal Account Name Lookup — MIB accounts (17 digits, starts with 9)
**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getAccountName`
Body: `accountNo=90100000000000000` (17 digits)
**Success response** (exact structure to be confirmed):
```json
{
"success": true,
"responseCode": "1",
"reasonText": "Account found",
"accountName": "ACCOUNT HOLDER NAME"
}
```
Fields used:
- `accountName` — account holder name (check at root level or inside `data` object)
The account number is already known from the input; bank is always MIB (`MADVMVMV`).
---
### 3. Favara Alias Lookup — Shortcodes, A-IDs, emails
**POST** `https://faisamobilex-wv.mib.com.mv/AjaxAlias/getAlias`
Body: `aliasName=<alias>`
Accepted alias formats:
- `7` or `9` followed by 6 digits → e.g. `7012345`, `9198026`
- `A` followed by 6 digits → e.g. `A123456`
- Email address → e.g. `user@example.com`
**Success response:**
```json
{
"success": true,
"responseCode": "2",
"reasonCode": "203",
"reasonText": " Favara ID found",
"data": {
"TxId": "BANK00001",
"CdtrAcct": {
"Acct": "90100000000000000",
"FinInstnId": "MADVMVMV"
},
"BfyNm": "Account Holder Name",
"RegDtTm": "2023-01-01T00:00:00"
}
}
```
Fields used from `data`:
- `BfyNm` — beneficiary name (trim whitespace)
- `CdtrAcct.Acct` — resolved account number to use for the transfer
- `CdtrAcct.FinInstnId` — bank institution ID
---
## Error Handling
All three endpoints return `"success": false` on failure with a human-readable `reasonText`:
```json
{
"success": false,
"responseCode": "0",
"reasonText": "Account not found"
}
```
- Always show `reasonText` directly to the user as the error message.
- For non-200 HTTP responses, also attempt to parse `reasonText` from the body before falling back to a generic error.
- If the input does not match any known format, reject it client-side before making any request.

249
docs/mibapi/contacts.md
View File

@@ -1,249 +0,0 @@
# MIB Contacts (Beneficiary) API
The contacts/beneficiary system is served from the MIB WebView subdomain. All endpoints use
session-cookie authentication (same cookies as the financing WebView).
## Authentication
All requests use the same session cookies:
```
Cookie: mbmodel=IOS-1.0; xxid=<session_xxid>; IBSID=<session_xxid>; mbnonce=<nonceGenerator>; time-tracker=597
```
All AJAX POST requests also require:
```
X-Requested-With: XMLHttpRequest
Origin: https://faisamobilex-wv.mib.com.mv
Referer: https://faisamobilex-wv.mib.com.mv/beneficiary?dashurl=1
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
```
---
## Endpoints
### 1. Get Categories
**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getCategories`
No request body required (empty POST).
**Response:**
```json
{
"success": true,
"responseCode": "1",
"reasonText": "Category retrieval success",
"reasonCode": "105",
"data": [
{
"id": "100001",
"categoryName": "Myself",
"icon": "f091",
"createdDate": "2023-01-01 00:00:00",
"modifiedDate": null,
"numBenef": "2"
},
{
"id": "100002",
"categoryName": "Friends",
"icon": "f095",
"createdDate": "2023-01-01 00:00:00",
"modifiedDate": "2023-01-02 00:00:00",
"numBenef": "10"
},
{
"id": "100003",
"categoryName": "Business",
"icon": "f097",
"createdDate": "2023-01-01 00:00:00",
"modifiedDate": "2023-01-02 00:00:00",
"numBenef": "8"
},
{
"id": "100004",
"categoryName": "Family",
"icon": "f090",
"createdDate": "2023-01-01 00:00:00",
"modifiedDate": "2023-01-02 00:00:00",
"numBenef": "5"
}
]
}
```
Fields:
- `id` — category ID (used as `searchCategoryId` when filtering contacts)
- `categoryName` — display name
- `icon` — font-awesome icon code (used in web UI, ignore in native app)
- `numBenef` — number of beneficiaries in this category (string)
---
### 2. Get Contacts (Paginated)
**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/main`
**Request body (form-urlencoded):**
| Field | Example | Description |
|--------------------|----------|-----------------------------------------------------------|
| `page` | `1` | Page number (1-based) |
| `search` | `` | Search query (empty = all) |
| `searchCategoryId` | `0` | Category filter (`0` = all categories) |
| `benefType` | `A` | Beneficiary type: `A`=All, `L`=Local, `I`=Internal, `S`=Swift |
| `sortBenef` | `name` | Sort field |
| `sortDir` | `asc` | Sort direction |
| `start` | `1` | Record start index (1-based) |
| `end` | `100` | Record end index |
| `includeCount` | `1` | Include `total_count` in response |
**Beneficiary types:**
- `L` — Local (other Maldivian banks, e.g. BML)
- `I` — Internal (MIB to MIB transfers)
- `S` — Swift (international transfers)
**Response:**
```json
{
"success": true,
"responseCode": "1",
"reasonText": "beneficiary retrieval success",
"reasonCode": "103",
"data": [
{
"benefNo": "100001",
"benefName": "Person Name",
"benefNickName": "Nickname",
"benefAccount": "7700000000001",
"benefType": "L",
"bankColor": "#AC0000",
"benefBankName": "Bank of Maldives PLC",
"bankCode": "BML",
"benefBankBranch": null,
"benefAddress1": null,
"benefAddress2": null,
"benefAddress3": null,
"benefCity": null,
"benefRegion": null,
"benefCountry": null,
"benefStatus": "A",
"benefBankId": "3",
"benefSwiftCode": "MALBMVMV",
"transferCy": "462",
"transferCyDesc": "MVR",
"bicCode": null,
"intermBankCode": "0",
"customerImgHash": "abcd1234hash...",
"benefImgHash": "abcd1234hash...",
"benefCategoryID": "100002",
"BENEF_CIF_NO": null,
"rnum": "1",
"last": "0"
},
{
"benefNo": "100002",
"benefName": "Another Person",
"benefNickName": "MIB Contact",
"benefAccount": "90103100000001000",
"benefType": "I",
"bankColor": "#FE860E",
"benefBankName": "MIB",
"bankCode": "MIB",
"benefBankBranch": null,
"benefStatus": "A",
"benefBankId": "2",
"benefSwiftCode": "SWIFTCODE",
"transferCy": "462",
"transferCyDesc": "MVR",
"customerImgHash": null,
"benefImgHash": null,
"benefCategoryID": "0",
"rnum": "2",
"last": "1"
}
],
"total_count": "48",
"pos": "1"
}
```
Key fields:
- `benefNo` — unique beneficiary ID
- `benefNickName` — user-assigned nickname (prefer over `benefName` for display)
- `benefType` — `L`, `I`, or `S`
- `bankColor` — hex color representing the bank (use for placeholder avatar background)
- `customerImgHash` — hash used to fetch profile photo (null if no photo set)
- `benefCategoryID` — category ID, `"0"` means uncategorized
- `transferCyDesc` — currency (MVR, USD)
- `rnum` — row number (1-based position in full sorted list)
- `last` — `"1"` if this is the last record on the page
Pagination: use `start`/`end` to page through results. `total_count` gives the total number of records.
---
### 3. Get Profile Image
**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getProfileImage`
**Request body (form-urlencoded):**
| Field | Description |
|-------------|------------------------------------|
| `imageHash` | The `customerImgHash` from contact |
**Response:**
```json
{
"success": true,
"responseCode": "1",
"reasonCode": "1",
"reasonText": "image found",
"profileImage": "<base64-encoded JPEG>"
}
```
- `profileImage` — raw base64-encoded JPEG (no data URI prefix)
- Decode with `Base64.decode(value, Base64.DEFAULT)` then `BitmapFactory.decodeByteArray(...)`
- The same hash may be reused across multiple contacts (deduplication recommended)
---
### 4. Get Stats (optional)
**POST** `https://faisamobilex-wv.mib.com.mv/ajaxBeneficiary/getStats`
No request body required.
**Response:**
```json
{
"success": true,
"responseCode": "1",
"reasonText": "Beneficiary Stats Retrieved",
"reasonCode": "109",
"data": [
{ "type": "L", "count": "30" },
{ "type": "I", "count": "10" },
{ "type": "S", "count": "2" }
]
}
```
Gives counts per beneficiary type. Useful for showing tab badges.
---
## Notes
- Profile images are fetched on-demand per contact. Cache decoded bitmaps in memory to avoid re-fetching.
- Contacts with `customerImgHash == null` have no profile photo; show initials + bank color as placeholder.
- The `benefCategoryID` of `"0"` means uncategorized (not in any category group).
- Pagination: use `start=1&end=100` for the first 100 records. Increment accordingly using `total_count`.

109
docs/mibapi/financing.md
View File

@@ -1,109 +0,0 @@
# MIB Financing API
## Overview
Financing data is fetched from the MIB **WebView** host (`faisamobilex-wv.mib.com.mv`), which is separate from the API host (`faisanet.mib.com.mv`). The response is an HTML page; financing deal data is embedded in `data-*` attributes on card elements.
---
## Endpoint
```
GET https://faisamobilex-wv.mib.com.mv/financing?dashurl=1
```
### Authentication
Session cookies from the login flow must be sent with the request:
| Cookie | Value |
|----------------|---------------------------------------------|
| `mbmodel` | `IOS-1.0` (literal string) |
| `xxid` | Session ID from login (`MibSession.xxid`) |
| `IBSID` | Same as `xxid` |
| `mbnonce` | `nonceGenerator` string from login response |
| `time-tracker` | `597` (literal string) |
### Request Headers
| Header | Value |
|--------------------|------------------------------------|
| `User-Agent` | Standard Android WebView UA string |
| `X-Requested-With` | `mv.com.mib.faisamobilex` |
---
## Response
**Content-Type:** `text/html; charset=UTF-8`
The response is a full HTML page. Each financing deal is represented as a `<div>` with the class `finance-card-holder` and all deal fields embedded as `data-*` attributes:
```html
<div class="card border finance-card-holder"
data-productDesc = "Product Name"
data-dealStatus = "P"
data-statusDesc = "Approved"
data-dealAmount = "10000.00"
data-dealNo = "12345"
data-paidAmount = "2500.00"
data-outstandingAmount = "7500.00"
data-dealDate = "2024-01-15 00:00:00"
data-overdueAmount = "0"
data-installmentAmount = "500.00"
data-noOfInstallments = "24"
data-lastPaidDate = "2026-05-01 00:00:00"
data-lastPayAmount = "500.00"
data-financeCurrency = "462"
data-curCodeDesc = "MVR">
```
### Data Fields
| Field | Type | Description |
|-----------------------|---------|------------------------------------------------------|
| `productDesc` | String | Product name (e.g. "Ujalaa CG Finance") |
| `dealStatus` | String | Status code: `P` = Active/Pending |
| `statusDesc` | String | Human-readable status (e.g. "Approved") |
| `dealAmount` | Decimal | Total financing amount |
| `dealNo` | Integer | Unique deal/contract number |
| `paidAmount` | Decimal | Amount paid to date |
| `outstandingAmount` | Decimal | Remaining unpaid balance |
| `dealDate` | String | Contract start date (`yyyy-MM-dd HH:mm:ss`) |
| `overdueAmount` | Decimal | Amount currently overdue (0 if none) |
| `installmentAmount` | Decimal | Monthly installment amount |
| `noOfInstallments` | Integer | Total number of installments |
| `lastPaidDate` | String | Date of most recent payment (`yyyy-MM-dd HH:mm:ss`) |
| `lastPayAmount` | Decimal | Amount of most recent payment |
| `financeCurrency` | Integer | Currency code (462 = MVR) |
| `curCodeDesc` | String | Currency abbreviation (e.g. "MVR") |
### Parsing Strategy
Use a regex to find all elements with class `finance-card-holder`, then extract all `data-*` attribute key/value pairs from each match:
```kotlin
val cardPattern = Regex("""finance-card-holder[^>]+>""")
val attrPattern = Regex("""data-(\w+)\s*=\s*"([^"]*)"""")
```
---
## Completion Date Estimation
Remaining installments can be estimated from outstanding and installment amounts:
```
remainingInstallments = ceil(outstandingAmount / installmentAmount)
completionDate = today + remainingInstallments months
```
---
## Notes
- The WebView endpoint uses a different subdomain (`faisamobilex-wv`) from the encrypted API (`faisanet`).
- No encryption is used; the session is maintained purely via cookies.
- The HTML is served gzip/brotli compressed; OkHttp handles decompression automatically.
- The `time-tracker` cookie value appears to be static at `597` — its purpose is unclear, but omitting it may affect behavior.
- Known product names include consumer goods finance and cash financing variants.

81
docs/mibapi/transfer.md
View File

@@ -1,81 +0,0 @@
# MIB Transfer API
Transfer endpoints are served from the MIB WebView subdomain, using the same session-cookie auth as
financing and contacts.
## Authentication
```
Cookie: mbmodel=IOS-1.0; xxid=<session_xxid>; IBSID=<session_xxid>; mbnonce=<nonceGenerator>; time-tracker=597
```
All AJAX POST requests also require:
```
X-Requested-With: XMLHttpRequest
Origin: https://faisamobilex-wv.mib.com.mv
Referer: https://faisamobilex-wv.mib.com.mv/transfer/quick
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
```
---
## Endpoints
### 1. Look Up Recipient by Favara Alias
Resolves a Favara ID (alias) to the account holder name and account number before initiating a transfer.
**POST** `https://faisamobilex-wv.mib.com.mv/AjaxAlias/getAlias`
**Request body (form-urlencoded):**
| Field | Description |
|-------------|------------------------------------------|
| `aliasName` | The recipient's Favara ID / alias number |
**Success response (`responseCode: "2"`):**
```json
{
"success": true,
"responseCode": "2",
"reasonCode": "203",
"reasonText": " Favara ID found",
"data": {
"TxId": "BANK00001",
"CreDtTm": "...",
"Resp": {
"Rslt": true,
"RsltDtls": null
},
"CdtrAcct": {
"Acct": "90100000000000000",
"FinInstnId": "MADVMVMV"
},
"BfyNm": "Account Holder Name",
"RegDtTm": "2023-01-01T00:00:00"
}
}
```
**Not found / error response:**
```json
{
"success": false,
"responseCode": "0",
"reasonCode": "400",
"reasonText": "Alias not found"
}
```
Key fields from `data`:
- `BfyNm` — beneficiary full name (trim whitespace)
- `CdtrAcct.Acct` — resolved account number to use for the transfer
- `CdtrAcct.FinInstnId` — bank institution ID (e.g. `MADVMVMV`, `MALBMVMV`)
**Notes:**
- Use `success` (not `responseCode`) to determine if the lookup succeeded.
- Show `BfyNm` + `CdtrAcct.Acct` to the user as confirmation before proceeding.
- The `reasonText` from error responses should be shown directly to the user.