ahusan/fksar
1
0
Fork 0
forked from thijooree/android
Code Pull Requests Activity
Files
2764c6e452aa3a0124be8237f0a2c1809d609e39
fksar/docs/mibapi/09-contacts.md
T
shihaam 2764c6e452 update mib api docs
2026-10-23 05:38:33 +05:00

7.8 KiB
Raw Blame History

Contacts (Beneficiaries)

Manage the user's saved beneficiary list. All endpoints are on the encrypted API (sfunc=n, session key) — see README for the request format.

Contacts belong to the currently selected profile — call P47 for the profile first (see 03-accounts.md).

Every write returns a beneficiaryVersion counter that increments on each change.

List Contacts — routePath: B41

Request:

{
  "sfunc": "n",
  "xxid": "<session xxid>",
  "data": {
    "start": 1,
    "end": 10,
    "benefType": "A",
    "search": "",
    "includeCount": 1,
    "searchCategoryId": 0,
    "sortBenef": "",
    "nonce": "<computed nonce>",
    "appId": "<appId>",
    "sodium": "<random 20-bit int>",
    "routePath": "B41",
    "xxid": "<session xxid>"
  }
}
Field Example Description
start 1 First row (rnum, 1-based, inclusive)
end 10 Last row (inclusive)
benefType A A=All, L=Local, I=Internal, S=Swift
search `` Search query (empty = all)
includeCount 1 Include total_count
searchCategoryId 0 Category filter (0 = all)
sortBenef `` Sort field (empty = default)

Pagination

Rows are selected by their 1-based rnum, both ends inclusive. The client pages in windows of 10:

Page start end
1 1 10
2 11 20
N (N-1)*10 + 1 N*10

The last row of the final page has last: "1". Stop there, or when total fetched equals total_count.

Beneficiary Types

benefType Meaning
I Internal (MIB to MIB)
L Local (other Maldivian banks, e.g. BML)
S Swift (international)

Response

{
  "success": true,
  "responseCode": "1",
  "reasonCode": "103",
  "reasonText": "beneficiary retrieval success",
  "total_count": "47",
  "pos": "0",
  "data": [
    {
      "benefNo": "100001",
      "benefName": "Person Name",
      "benefAccount": "7700000000001",
      "benefType": "L",
      "bankColor": "#AC0000",
      "benefBankName": "Bank of Maldives PLC",
      "bankCode": "BML",
      "benefStatus": "A",
      "benefBankId": "3",
      "benefNickName": "Nickname",
      "benefSwiftCode": "MALBMVMV",
      "transferCy": "462",
      "transferCyDesc": "MVR",
      "customerImgHash": "<image hash>",
      "benefImgHash": "<image hash>",
      "benefCategoryID": "100002",
      "createdDate": "2025-05-25 10:38:49",
      "rnum": "1",
      "last": "0"
    }
  ],
  "categories": [
    {
      "id": "100002",
      "categoryName": "Friends",
      "icon": "f095",
      "createdDate": "2023-05-18 14:35:22",
      "modifiedDate": "2023-05-19 12:06:05",
      "numBenef": "23"
    }
  ]
}
Field Consumed Description
benefNo yes Unique beneficiary ID — use for update and 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).
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 the contact photo via B46. May be missing, blank, or the literal string "null" — the client filters all three so downstream code only sees a real hash or null.
benefCategoryID yes Category ID — "0" means uncategorized
benefImgHash server-only Photo set on the beneficiary itself; equals customerImgHash when set
benefSwiftCode server-only SWIFT BIC — 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
rnum / last server-only Row number and last-row flag, used for paging

Categories

Every B41 response carries the full category list in categories — there is no separate categories call.

Field Description
id Category ID — use as searchCategoryId / categoryId
categoryName Display name
numBenef Number of beneficiaries in this category (string)
icon Icon code

Get Contact Photo — routePath: B46

Request — route fields:

{ "imageHash": "<customerImgHash>", "routePath": "B46" }

Response

{
  "success": true,
  "msg": "image found",
  "message": "image found",
  "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 — routePath: B43

Request — route fields:

{
  "benefName": "RECIPIENT NAME",
  "benefAccount": "7700000000001",
  "bankNo": "3",
  "nickName": "Nickname",
  "transferCy": "462",
  "categoryId": "0",
  "image": "<base64 JPEG, optional>",
  "bankName": "Bank of Maldives PLC",
  "bankSwift": "MALBMVMV",
  "routePath": "B43"
}
Field Description
benefName Full name (from account lookup)
benefAccount Beneficiary account number
bankNo "2" = MIB, "3" = BML
nickName Display nickname — max 20 characters
transferCy Currency numeric code ("462" = MVR, "840" = USD)
categoryId Category ID ("0" = uncategorized)
image Base64 JPEG photo. Omit the field when there is no photo.
bankName Bank name from the login bank list (A41 bankData)
bankSwift Bank BIC from the same list
bankNo bankName bankSwift
2 Maldives Islamic Bank MADVMVMV
3 Bank of Maldives PLC MALBMVMV

Response

{
  "success": true,
  "responseCode": "1",
  "reasonCode": "102",
  "reasonText": "beneficiary creation success",
  "data": [ { "benefNo": "1336023", "benefNickName": "Nickname", "customerImgHash": "<image hash>", ... } ],
  "beneficiaryVersion": 8
}

Errors

A nickname over 20 characters is rejected with HTTP 400:

{ "success": false, "responseCode": "2", "reasonCode": "201", "reasonText": "invalid nick name", "errorKey": "nickName" }

Update Contact — routePath: B52

Same fields as B43, plus:

Field Description
benefNo Beneficiary to update
imageChanged "1" when a new image is sent, "0" to keep the current photo

Request — route fields:

{
  "benefName": "RECIPIENT NAME",
  "benefAccount": "7700000000001",
  "bankNo": "3",
  "nickName": "New nickname",
  "transferCy": "462",
  "categoryId": "100002",
  "benefNo": "240301",
  "imageChanged": "0",
  "bankName": "Bank of Maldives PLC",
  "bankSwift": "MALBMVMV",
  "routePath": "B52"
}

Response

{
  "success": true,
  "responseCode": "1",
  "reasonCode": "107",
  "reasonText": "Beneficiary Updated Successfully",
  "data": [ { "benefNo": "240301", "benefNickName": "New nickname", "customerImgHash": "<image hash>", ... } ],
  "beneficiaryVersion": 6
}

Reload the list with B41 afterwards to pick up the change.

Delete Contact — routePath: B48

Request — route fields:

{ "benefNo": "240301", "routePath": "B48" }

Response

{
  "success": true,
  "responseCode": "1",
  "reasonCode": "108",
  "reasonText": "Beneficiary deleted Successfully",
  "beneficiaryVersion": 7
}

 

← Transfer

View Git Blame Copy Permalink