add support for fahipay login and view history

2026-05-16 21:31:34 +05:00
parent 99a32dc9ed
commit 7864655a82
29 changed files with 2097 additions and 32 deletions
@@ -0,0 +1,129 @@
+# Fahipay API Documentation
+
+Reverse-engineered from traffic captures of the Fahipay Android WebView app (`fahipay.mv`).
+
+---
+
+## Overview
+
+Fahipay is a Maldivian digital wallet service. The API uses a mix of `multipart/form-data` POST requests for authentication and simple authenticated `GET` requests for data retrieval.
+
+Authentication is session-based:
+- A `__Secure-sess` cookie is set by the server on first contact and must be sent with every request.
+- After login (and optional TOTP verification), the server returns an `authID` token that must be sent as an `authid` header with every subsequent request.
+
+---
+
+## Base URL
+
+```
+https://fahipay.mv
+```
+
+---
+
+## Authentication Model
+
+| Value | How obtained | How used |
+|---|---|---|
+| `__Secure-sess` cookie | Set by server on first request | Sent automatically via cookie jar |
+| `authID` | Returned by `/api/app/login/` or `/api/app/otp/` | Sent as `authid: <value>` header |
+
+Both must be present on every authenticated request.
+
+---
+
+## Common Request Headers
+
+### Login / OTP endpoints
+```
+Content-Type: multipart/form-data; boundary=<boundary>
+accept: application/json
+accept-encoding: gzip, deflate, br
+connection: keep-alive
+user-agent: Mozilla/5.0 (Linux; Android 14; 22101320I Build/AP2A.240905.003; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/129.0.6668.70 Mobile Safari/537.36
+```
+
+### Authenticated data endpoints
+```
+Accept-Encoding: gzip
+Connection: Keep-Alive
+User-Agent: okhttp/4.12.0
+authid: <authID>
+content-type: multipart/form-data
+```
+
+---
+
+## Common Form Fields (Device Info)
+
+All login and OTP requests include a standard set of device fields:
+
+| Field | Example value | Notes |
+|---|---|---|
+| `device[available]` | `true` | Always `true` |
+| `device[platform]` | `Android` | Always `Android` |
+| `device[uuid]` | `a1b2c3d4e5f60718` | 16 hex chars, generated once per install, persisted |
+| `device[model]` | `22101320I` | Device model string |
+| `device[manufacturer]` | `Xiaomi` | Device manufacturer |
+| `device[isVirtual]` | `false` | Always `false` |
+| `device[serial]` | `unknown` | Always `unknown` |
+
+The `device[uuid]` must be consistent across all requests from the same install. Generate it once and store it permanently.
+
+---
+
+## Login Flow
+
+```
+Client                              Server
+  |                                   |
+  |  POST /api/app/login/             |
+  |  { email=IDCARD, password, ... }  |
+  |---------------------------------->|
+  |  { two_factor_required: bool }    |
+  |<----------------------------------|
+  |                                   |
+  |  (if two_factor_required=true)    |
+  |  POST /api/app/otp/               |
+  |  { code=TOTP, channel=totp, ... } |
+  |---------------------------------->|
+  |  { authID: "..." }                |
+  |<----------------------------------|
+  |                                   |
+  |  (if two_factor_required=false)   |
+  |  authID already in login response |
+  |                                   |
+  |  GET /actions/getprofile/         |
+  |  authid: <authID>                 |
+  |---------------------------------->|
+  |  { fullname, profileID, ... }     |
+  |<----------------------------------|
+  |                                   |
+  |  GET /actions/getbalance/         |
+  |  authid: <authID>                 |
+  |---------------------------------->|
+  |  { balance: 1.01 }                |
+  |<----------------------------------|
+```
+
+---
+
+## Documents
+
+| # | File | Description |
+|---|---|---|
+| 1 | [Login](01-login.md) | Authenticate with ID card and password |
+| 2 | [OTP / 2FA](02-otp.md) | TOTP verification when 2FA is enabled |
+| 3 | [Profile](03-profile.md) | Fetch user profile and linked bank accounts |
+| 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 |
+
+---
+
+&nbsp;
+
+---
+
+> **Next →** [Login](01-login.md)