diff --git a/docs/fahipayapi/07-contacts.md b/docs/fahipayapi/07-contacts.md new file mode 100644 index 0000000..65308c7 --- /dev/null +++ b/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) diff --git a/docs/fahipayapi/README.md b/docs/fahipayapi/README.md index 57e239d..7658bb5 100644 --- a/docs/fahipayapi/README.md +++ b/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 | ---