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,158 @@
+# OTP / 2FA Verification
+
+Submit a TOTP code to complete login when `two_factor_required` was `true` in the [login response](01-login.md).
+
+---
+
+## Endpoint
+
+```
+POST https://fahipay.mv/api/app/otp/
+```
+
+---
+
+## Prerequisites
+
+- Completed the [login step](01-login.md) and received `two_factor_required: true`
+- The `__Secure-sess` session cookie from the login response must be present
+- A valid TOTP code from the user's authenticator app
+
+---
+
+## Request
+
+**Content-Type:** `multipart/form-data`
+
+### Form Fields
+
+| Field | Value | Notes |
+|---|---|---|
+| `code` | `123456` | 6-digit TOTP code from the user's authenticator app |
+| `channel` | `totp` | Always `totp` |
+| `action` | `login` | Always `login` for the login flow |
+| `grant_type` | `auth_id` | Always `auth_id` |
+| `lang` | `en` | Always `en` |
+| `version` | `2.0.0` | App version string |
+| `platform` | `BasedBank` | Client identifier |
+| `device[available]` | `true` | Same device fields as login — must match |
+| `device[platform]` | `Android` | |
+| `device[uuid]` | `a1b2c3d4e5f60718` | Must be the **same UUID** used in the login request |
+| `device[model]` | `22101320I` | |
+| `device[manufacturer]` | `Xiaomi` | |
+| `device[isVirtual]` | `false` | |
+| `device[serial]` | `unknown` | |
+
+> The `device[uuid]` must be identical to the one sent in the login request. The server uses this to tie the OTP challenge to the login attempt.
+
+---
+
+## curl Example
+
+```bash
+curl --request POST \
+  --url https://fahipay.mv/api/app/otp/ \
+  --compressed \
+  --header 'Cookie: __Secure-sess=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
+  --header 'accept: application/json' \
+  --header 'accept-encoding: gzip, deflate, br' \
+  --header 'connection: keep-alive' \
+  --header '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' \
+  --form 'code=123456' \
+  --form 'channel=totp' \
+  --form 'action=login' \
+  --form 'grant_type=auth_id' \
+  --form 'lang=en' \
+  --form 'version=2.0.0' \
+  --form 'platform=BasedBank' \
+  --form 'device[available]=true' \
+  --form 'device[platform]=Android' \
+  --form 'device[uuid]=a1b2c3d4e5f60718' \
+  --form 'device[model]=22101320I' \
+  --form 'device[manufacturer]=Xiaomi' \
+  --form 'device[isVirtual]=false' \
+  --form 'device[serial]=unknown'
+```
+
+---
+
+## Responses
+
+### Success
+
+```json
+{
+  "title": "Success",
+  "authID": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "msg": "Code verification successful",
+  "type": "success"
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `authID` | `string` | 40-char hex token — use as `authid` header for all subsequent requests |
+| `type` | `string` | `"success"` |
+| `msg` | `string` | Human-readable confirmation |
+
+---
+
+### Failure — Wrong code
+
+```json
+{
+  "title": "Error",
+  "msg": "Invalid OTP code",
+  "type": "error"
+}
+```
+
+---
+
+### Failure — Expired / session mismatch
+
+```json
+{
+  "title": "Error",
+  "msg": "Session expired. Please login again.",
+  "type": "error"
+}
+```
+
+If the session cookie has expired or the UUID does not match, re-run the full login flow from [Step 1](01-login.md).
+
+---
+
+## TOTP Details
+
+Fahipay uses standard RFC 6238 TOTP:
+
+| Parameter | Value |
+|---|---|
+| Algorithm | HMAC-SHA1 |
+| Period | 30 seconds |
+| Digits | 6 |
+| Encoding | Base32 secret |
+
+The user's TOTP seed is set up during initial Fahipay account creation and is the same secret used in any standard authenticator app (Google Authenticator, Aegis, etc.).
+
+---
+
+## Storing the Session
+
+After receiving `authID`, persist both values for future sessions:
+
+| Value | Description |
+|---|---|
+| `authID` | 40-char hex token — send as `authid` header |
+| `__Secure-sess` | Cookie value — send as `Cookie: __Secure-sess=<value>` |
+
+On app restart, attempt requests with the stored session before falling back to a full re-login.
+
+---
+
+&nbsp;
+
+---
+
+[← Login](01-login.md) &nbsp;&nbsp;&nbsp; **Next →** [Profile](03-profile.md)