add support for reload, raastas, ooredoo and dhiraagu bill pay via FahiPay

2026-10-02 22:04:05 +05:00
parent c0944d3809
commit 7a4b7a1712
11 changed files with 409 additions and 57 deletions
@@ -25,7 +25,7 @@ POST https://fahipay.mv/api/app/login/
 | `grant_type` | `auth_id` | Always `auth_id` |
 | `lang` | `en` | Always `en` |
 | `version` | `2.0.0` | App version string |
-| `platform` | `BasedBank` | Client identifier (`app` in the original Fahipay app) |
+| `platform` | `thijooree` | Client identifier (`app` in the original Fahipay app) |
 | `device[available]` | `true` | See [common device fields](README.md#common-form-fields-device-info) |
 | `device[platform]` | `Android` | |
 | `device[uuid]` | `a1b2c3d4e5f60718` | Persistent 16-char hex UUID, generated once per install |
@@ -53,7 +53,7 @@ curl --request POST \
  --form 'grant_type=auth_id' \
  --form 'lang=en' \
  --form 'version=2.0.0' \
-  --form 'platform=BasedBank' \
+  --form 'platform=thijooree' \
  --form 'device[available]=true' \
  --form 'device[platform]=Android' \
  --form 'device[uuid]=a1b2c3d4e5f60718' \
@@ -34,7 +34,7 @@ POST https://fahipay.mv/api/app/otp/
 | `grant_type` | `auth_id` | Always `auth_id` |
 | `lang` | `en` | Always `en` |
 | `version` | `2.0.0` | App version string |
-| `platform` | `BasedBank` | Client identifier (`app` in the original Fahipay app) |
+| `platform` | `thijooree` | Client identifier (`app` in the original Fahipay app) |
 | `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 |
@@ -64,7 +64,7 @@ curl --request POST \
  --form 'grant_type=auth_id' \
  --form 'lang=en' \
  --form 'version=2.0.0' \
-  --form 'platform=BasedBank' \
+  --form 'platform=thijooree' \
  --form 'device[available]=true' \
  --form 'device[platform]=Android' \
  --form 'device[uuid]=a1b2c3d4e5f60718' \
@@ -37,4 +37,4 @@ Server-issued payload fields that differ from a plain PayMV QR: `60` = `LD` + 4

 ---

-[← Saved Favourites](07-contacts.md)
+[← Saved Favourites](07-contacts.md) | [Payments →](09-payments.md)
@@ -0,0 +1,157 @@
+# Payments: Reload, Raastas & Bill Pay
+
+Pay a Dhiraagu or Ooredoo number from the Fahipay wallet. All four services use the same request; only the path differs.
+
+---
+
+## Endpoints
+
+| Service | Endpoint | Activity `subtype` |
+|---|---|---|
+| Ooredoo Raastas (prepaid top-up) | `POST https://fahipay.mv/actions/payment/ooredoo/recharge/` | `OORCH` |
+| Ooredoo Bill Pay | `POST https://fahipay.mv/actions/payment/ooredoo/billpay/` | `OOBPY` |
+| Dhiraagu Reload | `POST https://fahipay.mv/actions/payment/dhiraagu/recharge/` | `DHRCH` |
+| Dhiraagu Bill Pay | `POST https://fahipay.mv/actions/payment/dhiraagu/billpay/` | `DHBPY` |
+
+Which services a number supports comes from the carrier lookups: [Dhiraagu](../dhiraaguapi/01-number-lookup.md) and [Ooredoo](../ooredooapi/01-number-validation.md).
+
+---
+
+## Prerequisites
+
+- Valid `authID` from [login](01-login.md) or [OTP](02-otp.md)
+- Valid `__Secure-sess` session cookie
+
+There's no OTP or PIN step. The single POST moves the money.
+
+---
+
+## Request
+
+### Headers
+
+| Header | Value |
+|---|---|
+| `authid` | `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
+| `Content-Type` | `multipart/form-data; boundary=<boundary>` |
+| `Cookie` | `__Secure-sess=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
+
+The official app also sends a set of `x-app-*` / `x-device-*` headers and a `FahiPay-App/2.0.2 (...)` user agent. Thijooree sends `okhttp/4.12.0` like its other data calls.
+
+### Body (`multipart/form-data`)
+
+Thijooree builds it with lowercase `content-disposition` part headers, the way the app sends them (`FahipayForm.body`).
+
+| Field | Example | Notes |
+|---|---|---|
+| `number` | `9198026` | 7-digit phone number |
+| `amount` | `11` | MVR. Whole number for Raastas, Dhiraagu Reload and Dhiraagu Bill Pay. Ooredoo Bill Pay takes decimals (`10.1` seen) |
+| `lang` | `en` | |
+| `version` | `2.0.2` | App version |
+| `build` | `329` | App build |
+| `platform` | `app` | The official app sends `app`. Thijooree sends `thijooree` |
+| `device[...]` | | The standard [device fields](README.md#common-form-fields-device-info) |
+
+### Amount limits
+
+These are enforced in Thijooree before sending (see [Transfer Flows](../thijooree/20-transfer-flows.md#amount-rules)):
+
+| Service | Min | Max | Decimals |
+|---|---|---|---|
+| Raastas | 11 | none | no |
+| Ooredoo Bill Pay | 10 | 50,000 | yes |
+| Dhiraagu Reload | 8 | 1,000 | no |
+| Dhiraagu Bill Pay | 10 | 5,000 | no |
+
+The full `amount` is taken from the wallet. Raastas then has 8% GST taken out by Ooredoo, so the number is credited less than `amount`.
+
+---
+
+## curl Example
+
+```bash
+curl --request POST \
+  --url 'https://fahipay.mv/actions/payment/ooredoo/recharge/' \
+  --compressed \
+  --header 'authid: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
+  --header 'Cookie: __Secure-sess=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
+  --form 'number=9198026' \
+  --form 'amount=11' \
+  --form 'lang=en' \
+  --form 'version=2.0.2' \
+  --form 'build=329' \
+  --form 'platform=thijooree' \
+  --form 'device[available]=true' \
+  --form 'device[platform]=Android' \
+  --form 'device[uuid]=a1b2c3d4e5f60718' \
+  --form 'device[model]={model}' \
+  --form 'device[manufacturer]={manufacturer}' \
+  --form 'device[isVirtual]=false' \
+  --form 'device[serial]=unknown'
+```
+
+---
+
+## Response
+
+`200 OK`, `application/json`.
+
+### Success: reload / Raastas
+
+```json
+{"title":"Success!","msg":"Transaction successful.","type":"success","tid":"FP202610021957143XKQ"}
+```
+
+### Success: Ooredoo Bill Pay
+
+```json
+{"title":"Success!","msg":"Transaction successful.","type":"success"}
+```
+
+### Success: Dhiraagu Bill Pay
+
+```json
+{"title":"Success!","msg":"Transaction will be processed shortly.","type":"success"}
+```
+
+| Field | Description |
+|---|---|
+| `type` | `success` when the payment went through |
+| `title` / `msg` | Human-readable outcome |
+| `tid` | Fahipay transaction ID. Only returned by the recharge endpoints. Bill pays have one too, but it's only visible in [history](05-history.md) |
+
+### Failure
+
+Not captured yet. Thijooree treats any `type` other than `success` as a refusal and shows `msg` (or `title`).
+
+---
+
+## In history
+
+The payment shows up in [`actions/activity/`](05-history.md) straight away, with a negative `amount`:
+
+```json
+{
+    "date": "2026-10-02 19:57:14",
+    "name": "Ooredoo Raastas",
+    "details": "Mobile Recharge - 9198026",
+    "icon": "https://fahipay.mv/images/app/icons/services/oorch.png",
+    "transaction": "FP202610021957143XKQ",
+    "type": "payment",
+    "subtype": "OORCH",
+    "number": "9198026",
+    "amount": -11,
+    "success": 1,
+    "status": "Success"
+}
+```
+
+`name` / `details` per service: `Ooredoo Raastas` / `Mobile Recharge - <number>`, `Ooredoo BillPay` / `BillPay - <number>`, `Dhiraagu Reload` / `Mobile Recharge - <number>`, `Dhiraagu BillPay` / `BillPay - <number>`.
+
+---
+
+&nbsp;
+
+---
+
+[← PayMV QR](08-paymv-qr.md)
@@ -128,6 +128,7 @@ Client                              Server
 | 6 | [Profile Picture](06-profile-picture.md) | Local-only profile picture storage (no Fahipay endpoint) |
 | 7 | [Saved Favourites](07-contacts.md) | Fetch saved contacts per payment service |
 | 8 | [PayMV QR](08-paymv-qr.md) | Server-generated receive QR (`api/app/qr/`) — work in progress |
+| 9 | [Payments](09-payments.md) | Dhiraagu reload / bill pay, Ooredoo Raastas / bill pay |

 ---