add fahipay contact fetch docs

docs/fahipayapi/07-contacts.md

@@ -0,0 +1,131 @@
+# Saved Favourites (Contacts)
+
+Fetch the authenticated user's saved favourites for Fahipay payment services. Each service group is fetched individually by page name.
+
+---
+
+## Endpoint
+
+```
+GET https://fahipay.mv/api/app/favs/?page={serviceName}&lang=en
+```
+
+---
+
+## Prerequisites
+
+- Valid `authID` from [login](01-login.md) or [OTP](02-otp.md)
+- Valid `__Secure-sess` session cookie
+
+---
+
+## Request
+
+### Headers
+
+| Header | Value |
+|---|---|
+| `authid` | `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
+| `User-Agent` | `okhttp/4.12.0` |
+| `Accept-Encoding` | `gzip` |
+| `Connection` | `Keep-Alive` |
+| `Cookie` | `__Secure-sess=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
+
+### Query Parameters
+
+| Parameter | Description |
+|---|---|
+| `page` | Service group name — see table below |
+| `lang` | Language — always `en` |
+
+---
+
+## Service Groups
+
+Call this endpoint once per service group:
+
+| `page` value | Service | Description |
+|---|---|---|
+| `ooredooraastas` | Ooredoo Raastas | Ooredoo mobile top-up |
+| `dhiraagureload` | Dhiraagu Reload | Dhiraagu mobile top-up |
+| `ooredoobillpay` | Ooredoo Bill | Ooredoo bill payment |
+| `dhiraagubillpay` | Dhiraagu Bill | Dhiraagu bill payment |
+
+---
+
+## curl Example
+
+```bash
+curl --request GET \
+  --url 'https://fahipay.mv/api/app/favs/?page=ooredooraastas&lang=en' \
+  --compressed \
+  --header 'Accept-Encoding: gzip' \
+  --header 'Connection: Keep-Alive' \
+  --header 'Cookie: __Secure-sess=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
+  --header 'User-Agent: okhttp/4.12.0' \
+  --header 'authid: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
+```
+
+---
+
+## Response
+
+### With Entries
+
+The top-level response is a JSON object. The key matching the `page` query parameter contains an object of saved entries, keyed by an arbitrary server-assigned string.
+
+```json
+{
+  "ooredooraastas": {
+    "1": {
+      "number": "9600000001",
+      "name": "Ali"
+    },
+    "2": {
+      "number": "7600000002",
+      "name": "Mohamed"
+    }
+  }
+}
+```
+
+### Empty Group
+
+When the user has no saved favourites for a service, the value for the page key is an empty **array** (not an object):
+
+```json
+{
+  "ooredooraastas": []
+}
+```
+
+> Parse with `optJSONObject(page)` — this returns `null` for the empty-array case, so empty groups are safely skipped.
+
+---
+
+## Entry Object
+
+| Field | Type | Description |
+|---|---|---|
+| `number` | `string` | The saved phone number or account number |
+| `name` | `string` | User-assigned display name for this favourite |
+
+Only entries where `number` is a valid 7-digit Maldivian mobile number (starting with `7` or `9`) are used as transfer contacts.
+
+---
+
+## Usage
+
+Fetch all four service groups in sequence. For each group:
+1. Call `GET /api/app/favs/?page={serviceName}&lang=en`
+2. Check that `response[serviceName]` is a JSON object (not an array)
+3. Iterate keys; for each entry, validate `number` as a phone number
+4. Build a contact entry with the service group as the bank/category label
+
+---
+
+ 
+
+---
+
+[← Profile Picture](06-profile-picture.md)

docs/fahipayapi/README.md

@@ -124,6 +124,7 @@ Client                              Server
 | 4 | [Balance](04-balance.md) | Fetch wallet balance |
 | 5 | [Transaction History](05-history.md) | Paginated activity/transaction history |
 | 6 | [Profile Picture](06-profile-picture.md) | Fetch user profile picture |
+| 7 | [Saved Favourites](07-contacts.md) | Fetch saved contacts per payment service |
 
 ---