basedbank/docs/fahipayapi/01-login.md

Login

Authenticate a user with their Fahipay ID card number and password.

---

Endpoint

POST https://fahipay.mv/api/app/login/

---

Request

Content-Type: multipart/form-data

Form Fields

Field	Value	Notes
email	A123456	The user's national ID card number (e.g. A123456)
password	••••••••••••••	The user's Fahipay password
grant_type	auth_id	Always auth_id
lang	en	Always en
version	2.0.0	App version string
platform	BasedBank	Client identifier (original app sends app)
device[available]	true	See common device fields
device[platform]	Android
device[uuid]	a1b2c3d4e5f60718	Persistent 16-char hex UUID, generated once per install
device[model]	22101320I	Build.MODEL
device[manufacturer]	Xiaomi	Build.MANUFACTURER
device[isVirtual]	false
device[serial]	unknown

Note: The field name is email but the value is the ID card number, not an email address.

---

curl Example

curl --request POST \
  --url https://fahipay.mv/api/app/login/ \
  --compressed \
  --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 'email=A123456' \
  --form 'password=your_password' \
  --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 — 2FA required

The user has TOTP two-factor authentication enabled. Proceed to the OTP step.

{
  "two_factor_required": true,
  "two_factor_method": "totp",
  "title": "Success",
  "msg": "You are now logged in.",
  "type": "success"
}

Field	Type	Description
two_factor_required	bool	true — must call /api/app/otp/ next
two_factor_method	string	"totp" — standard TOTP (RFC 6238)
type	string	"success" on success, "error" on failure

The server sets the __Secure-sess session cookie on this response. It must be included in all subsequent requests.

---

Success — No 2FA

The user does not have 2FA enabled. The authID is returned directly — no OTP step needed.

{
  "two_factor_required": false,
  "authID": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "title": "Success",
  "msg": "You are now logged in.",
  "type": "success"
}

Field	Type	Description
two_factor_required	bool	false — login is complete
authID	string	40-char hex token; use as authid header for all subsequent requests

---

Failure

{
  "title": "Error",
  "msg": "Invalid credentials",
  "type": "error"
}

type is "error" and msg contains a human-readable reason.

---

Session Cookie

The __Secure-sess cookie is set by the server on the first response and must be sent on every subsequent request. It is a standard HTTP cookie with the Secure flag.

Set-Cookie: __Secure-sess=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx; Path=/; Secure; HttpOnly; SameSite=Strict

Store both the cookie value and the authID together to represent a persisted session.

---

Next Steps

• If two_factor_required is true → proceed to OTP / 2FA
• If two_factor_required is false → skip to Profile

---

 

---

← README     Next → OTP / 2FA