# 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
  |                                   |
  |  GET /api/app/lang/data/          |  ← session init (obtains __Secure-sess cookie)
  |---------------------------------->|
  |  Set-Cookie: __Secure-sess=...    |
  |<----------------------------------|
  |                                   |
  |  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)