238 lines
6.0 KiB
Markdown
238 lines
6.0 KiB
Markdown
# 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 | Consumed | Description |
|
|
|---|---|---|
|
|
| `benefNo` | yes | Unique beneficiary ID — use for delete |
|
|
| `benefName` | yes | Legal/full name; used as fallback when nickname is blank |
|
|
| `benefNickName` | yes | User-assigned nickname (prefer over `benefName` for display) |
|
|
| `benefAccount` | yes | Account number |
|
|
| `benefType` | yes | `L`, `I`, or `S` |
|
|
| `bankColor` | yes | Hex color for placeholder avatar background |
|
|
| `benefBankName` | yes | Bank display name. Shown as transfer subtitle and contact detail (`MibContactParser.kt:23, 26`). |
|
|
| `bankCode` | yes | Short bank code (e.g. `"BML"`, `"MIB"`) |
|
|
| `benefStatus` | yes | Beneficiary status (`"A"` = active) |
|
|
| `transferCyDesc` | yes | Currency (e.g. `"MVR"`, `"USD"`) |
|
|
| `customerImgHash` | yes | Hash for fetching profile photo. May be missing, blank, or the literal **string** `"null"` — the client filters all three (`MibContactsClient.kt:120`) so downstream code only sees a real hash or `null`. |
|
|
| `benefCategoryID` | yes | Category ID — `"0"` means uncategorized |
|
|
| `benefSwiftCode` | server-only | SWIFT BIC of the beneficiary's bank — present in payload, not read by the app |
|
|
| `benefBankId` | server-only | Numeric bank ID — not consumed |
|
|
| `transferCy` | server-only | Currency numeric code (e.g. `"462"`) — only `transferCyDesc` is consumed |
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
---
|
|
|
|
|
|
|
|
---
|
|
|
|
[← Transfer](08-transfer.md)
|