add support for fahipay login and view history

docs/fahipayapi/04-balance.md

@@ -0,0 +1,109 @@
+# Wallet Balance
+
+Fetch the current balance of the authenticated user's Fahipay wallet.
+
+---
+
+## Endpoint
+
+```
+GET https://fahipay.mv/actions/getbalance/?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` |
+| `content-type` | `multipart/form-data` |
+| `User-Agent` | `okhttp/4.12.0` |
+| `Accept-Encoding` | `gzip` |
+| `Connection` | `Keep-Alive` |
+| `Cookie` | `__Secure-sess=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
+
+### Query Parameters
+
+| Parameter | Value | Description |
+|---|---|---|
+| `lang` | `en` | Language — always `en` |
+
+---
+
+## curl Example
+
+```bash
+curl --request GET \
+  --url 'https://fahipay.mv/actions/getbalance/?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' \
+  --header 'content-type: multipart/form-data'
+```
+
+---
+
+## Response
+
+### Success
+
+```json
+{
+  "balance": 1.01,
+  "rewards": "0",
+  "error": false,
+  "type": "success"
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `balance` | `number` | Current wallet balance in MVR |
+| `rewards` | `string` | Rewards/cashback points balance |
+| `error` | `bool` | `false` on success |
+| `type` | `string` | `"success"` |
+
+> All Fahipay wallet balances are in **MVR** (Maldivian Rufiyaa). There is no multi-currency wallet.
+
+---
+
+### Error
+
+```json
+{
+  "error": true,
+  "type": "error",
+  "msg": "Unauthorized"
+}
+```
+
+If `error` is `true` or `type` is `"error"`, the session is invalid. Re-run the [login flow](01-login.md).
+
+---
+
+## Notes
+
+- This endpoint only returns the Fahipay wallet balance, not any linked bank account balances.
+- The `rewards` field is returned as a string even though it represents a numeric value. Parse it with `toDoubleOrNull()`.
+- Call this endpoint after [fetching the profile](03-profile.md) to construct the full account object with both account number and balance.
+
+---
+
+ 
+
+---
+
+[← Profile](03-profile.md)     **Next →** [Transaction History](05-history.md)