update docs: update payMV QR Design

2026-09-26 04:06:06 +05:00
parent 2688118f52
commit c7d3efa64e
6 changed files with 216 additions and 29 deletions
@@ -128,4 +128,4 @@ Fetch all four service groups in sequence. For each group:

 ---

-[← Profile Picture](06-profile-picture.md)
+[← Profile Picture](06-profile-picture.md) &nbsp;&nbsp;&nbsp; **Next →** [PayMV QR](08-paymv-qr.md)
@@ -0,0 +1,40 @@
+# PayMV QR (Receive)
+
+> ⚠️ **Work in progress.** Thijooree does not call this endpoint yet. It generates Fahipay QRs locally, and the Fahipay app currently rejects those as **"Invalid QR"**. See [PayMV QR Format → Fahipay](../thijooree/18-paymv-qr-format.md#fahipay-work-in-progress).
+
+Fahipay's app does **not** build its receive QR on the device. Its `PayMVQR` screen asks the server for a finished card image and displays it. Found by decompiling the app (v2.0.2, Hermes bundle), **not yet confirmed with a traffic capture**: request headers and the exact response shape are unverified.
+
+---
+
+## Endpoint
+
+```
+GET api/app/qr/?lang=<lang>&type=p2p&amount=<amount>
+```
+
+The app also has a `POST api/app/qr/` variant, sent as form data with `type=p2p`, `lang`, `version`, `platform=app`, `amount` and `device[...]` fields.
+
+## Response
+
+The app reads the image from the first of these fields that is present: `qr_image`, `qr`, `image`, `qr_url`, `qr_code`. The value is either an `http…` URL or raw base64, which the app prefixes with `data:image/png;base64,`. The payload text is read from `qr_code_text` / `qrCode`.
+
+## The card image
+
+A 1240 × 1322 PNG:
+- Blue `#005DA3` card with a 6 px border.
+- The square Fahipay icon plus the "FahiPay" wordmark top-left, and "PayMV QR" top-right.
+- A blue panel holding the holder's name and the QR.
+- The reference (`62→05`, e.g. `P2KVTPYL4E`) printed vertically in blue in the white margin right of the panel. The amount is not included in it.
+- A "MALDIVES NATIONAL QR" footer.
+
+Thijooree reproduces this layout in `PayMvQrFragment.renderFahipayQrCard()`; see [PayMV QR Screen](../thijooree/11-paymv-qr-screen.md#fahipay--renderfahipayqrcard).
+
+Server-issued payload fields that differ from a plain PayMV QR: `60` = `LD` + 4 digits, `62→05` = `P` + 9 chars, `62→08` = `PAYMENT`, and `54` = `***` when there is no amount. Full samples are in [PayMV QR Format](../thijooree/18-paymv-qr-format.md#real-receive-qrs-reference-samples).
+
+---
+
+&nbsp;
+
+---
+
+[← Saved Favourites](07-contacts.md)
@@ -127,6 +127,7 @@ Client                              Server
 | 5 | [Transaction History](05-history.md) | Paginated activity/transaction history |
 | 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 |

 ---

@@ -2,37 +2,102 @@

 Generates a receive-payment PayMV / Favara QR code. **Generation only** — the send/scan side of PayMV lives in `TransferFragment` via `newInstanceWithAutoScan()` and the [QR scanner](25-qr-scanner.md).

+> **Fahipay QRs are a work in progress.** Thijooree's Fahipay card matches Fahipay's design, but the Fahipay app currently rejects the QRs it generates as **"Invalid QR"**. BML QRs scan fine. See [PayMV QR Format → Fahipay](18-paymv-qr-format.md#fahipay-work-in-progress).
+
 ---

 ## Fragment — `PayMvQrFragment`

-A single screen (no tabs). Re-renders the QR live as the user edits the form.
+A single screen (no tabs). Re-renders the QR live (300 ms debounce) as the user edits the form. It can also be opened for a saved contact with `PayMvQrFragment.forContact(accountNumber, name, bank)`. The QR then pays into the contact's account, and the account picker and phone toggle are hidden.

 ### Fields

 | Field | Source / behaviour |
 |---|---|
-| Source account dropdown | `viewModel.accounts`, filtered to non-card MVR accounts (MIB and BML USD currently excluded — both flagged as TODO in source). Defaults to `CredentialStore.getDefaultAccountNumber()` when set |
-| Amount (`etAmount`) | Optional. Blank → open-amount QR |
-| Reference (`etReference`) | Free-text purpose; defaults to `paymvqr_reference_default` if blank — written to tag 62→08 |
-| Include phone (`switchIncludePhone`) | When on, writes the saved BML / Fahipay mobile to sub-tag 26→05 (auto-prefixed `+960` if 7-digit local) |
+| Source account dropdown | `viewModel.accounts`, filtered to non-card MVR accounts (MIB, M-Faisa and BML USD currently excluded — flagged as TODO in source). Defaults to `CredentialStore.getDefaultAccountNumber()` when set |
+| Amount (`etAmount`) | Optional. Blank / zero / unparseable → open-amount QR. Commas are stripped |
+| Reference (`etReference`) | Free-text purpose, written to tag 62→08. Blank → tag omitted (BML), or `PAYMENT` (Fahipay) |
+| Include phone (`switchIncludePhone`) | When on, writes the saved BML / Fahipay mobile to sub-tag 26→05, normalised to `+960XXXXXXX` |

-### Generation
+### What goes on the card

-`buildQrPayload()` assembles a decimal TLV payload per the [PayMV QR Format](18-paymv-qr-format.md):
+| Item | Value |
+|---|---|
+| Name | BML / MIB: `accountBriefName`. Fahipay: the holder's full name (`profileName`, falling back to the saved Fahipay profile's `fullName`) — **not** the generic "Fahipay Wallet" brief name. Contacts: the contact's name. Always uppercased |
+| QR | The payload below, white modules on the card blue, error correction M, no quiet zone |
+| Vertical text | The QR's reference (tag 62→05) — see below |
+| Amount | **Not printed** on the card (neither bank does); it only appears inside the QR, and in BML's vertical text |

-1. Tag 26 container: GUI (`mv.favara.mpqr`), acquirer BIC, account number, optional mobile, `IPAY`
-2. Acquirer BIC is derived from the source account's bank: `MALBMVMV` (BML) / `MADVMVMV` (MIB) / `FAHIMVMV` (Fahipay)
-3. Tag 62 container: random 9-char reference + the purpose text
-4. Tag 80 container: GUI + ISO timestamp
-5. Appends `"6304"` and computes CRC-16/CCITT-FALSE over the full string
+### Vertical text (reference)

-The rendered card image (bank-styled background plus QR) is shown in-place.
+Both banks print a short code vertically beside the QR, reading bottom-to-top. It is the same string as the payload's reference, **tag 62→05**, so Thijooree calculates the reference first and uses it for both.
+
+| Bank | Reference / vertical text | Example |
+|---|---|---|
+| BML | Account number converted to **base-32** (digits `0-9A-V`, uppercase), followed by the **amount exactly as typed** (commas removed, no forced decimals), capped at 25 chars | `7730000188362` → `70V3UKKUA`; with amount `100` → `70V3UKKUA100` |
+| Fahipay | `P` + 9 random uppercase alphanumeric chars. **No amount** | `P2KVTPYL4E` |
+| Other (MIB contacts) | 9 random uppercase alphanumeric chars | `WHQS0SX5O` |
+
+BML's base-32 is `AccountNumbertoBase32` from the BML app: `BigInt(account)`, repeatedly `% 32` into the alphabet `0123456789ABCDEFGHIJKLMNOPQRSTUV`. If the account number isn't numeric, Thijooree falls back to a random 9-char reference.
+
+---
+
+## Card Rendering
+
+Two renderers, chosen by the target's bank. Both return a `Bitmap` shown in `ivQrCard` (`fitCenter`) and used for Share / Save.
+
+### BML (and MIB) — `renderQrCard()`
+
+A 1:1 copy of BML app v2.1.47's `ReceiveCard` React Native component (decompiled from the Hermes bundle). All values are BML's StyleSheet values in dp, laid out for a 560 dp reference screen width (`SCREEN_WIDTH_DP`) and drawn at 2 px/dp (`PX_PER_DP`), so the card comes out about 1024 px wide.
+
+| Element | Spec |
+|---|---|
+| Colour | `mmaBlue` `#0E5CA4` everywhere |
+| Card | Width `sw − 48`. Blue background, radius 20. The white top section is inset 2 dp (top corners 18), which shows as a thin blue border |
+| Header row | 32 dp from top, 40 dp side margins. Left: `bml_logo_paymv` ("BANK OF MALDIVES" wordmark, from BML's assets) contained in `0.38·sw × 0.38·sw·0.1117`. Right: "PayMV QR", Sofia Pro Bold, `#0E5CA4`, sized to BML's `0.2·sw × 0.2·sw·0.1733` image box, shifted down 1 dp. MIB uses `mib_faisanet_logo` in the same box |
+| QR panel | 24 dp below the header, 40 dp side margins, radius 16, 24 dp bottom margin |
+| Name | Roboto (system default) regular, 14 sp, white; 8 + 12 dp above, 16 dp below |
+| QR | `0.5·sw` square; 37 dp padding below |
+| Vertical text | Roboto 10 sp, **black at 80 % opacity**, rotated −90°. Centred `railW/1.37 − railW/2` right of the QR's right edge and `(qr + railW/1.5)/2` down from the QR top, where `railW = sw/1.85`. Ellipsized to `railW` |
+| Footer | "MALDIVES NATIONAL QR", Sofia Pro Bold (`res/font/sofia_pro_bold.ttf`), `0.046·sw`, letter spacing 1.2 dp, 12 dp vertical padding |
+
+### Fahipay — `renderFahipayQrCard()`
+
+Fahipay's app doesn't draw its card; it shows an image generated by Fahipay's server (`api/app/qr/`). Thijooree copies that image's layout, measured in pixels on its **1240 × 1322** canvas. Text is sized so capital letters match the measured cap heights.
+
+| Element | Spec |
+|---|---|
+| Colour | `#005DA3` |
+| Card | Blue, radius 50. White area inset 6 px (top corners 44) down to y 1174. The blue below it is the footer |
+| Header row | Square app icon `fahipay_logo` at (94, 94)–(163, 163), then the "FahiPay" wordmark `fahipay_logo_long` at x 178, y 104, 48 px tall — **both, side by side** |
+| "PayMV QR" | Sofia Pro Bold, blue, right-aligned at x 1147, cap height 30 (cap top y 101) |
+| QR panel | (166, 218)–(1074, 1126), radius 55 |
+| Name | Roboto regular, white, centred at x 619, cap height 30 (cap top y 314). Shrinks to fit the panel minus 80 px |
+| QR | 562 px at (338, 417) |
+| Vertical text | Montserrat Regular (`res/font/montserrat_regular.ttf`), **blue**, cap height 27, rotated −90°. It sits in the **white margin right of the panel**: text starts at y 1087, baseline at x 1171 |
+| Footer | "MALDIVES NATIONAL QR", Sofia Pro Bold, white, cap height 55.5 (cap top y 1220), BML's letter spacing (1.2/25.76 em) |
+
+Fonts follow the BML card (Sofia Pro Bold, Roboto), except the vertical text, which keeps Fahipay's Montserrat.
+
+---
+
+## Generation
+
+`buildQrPayload()` assembles a decimal TLV payload per the [PayMV QR Format](18-paymv-qr-format.md#generating-a-receive-payment-qr):
+
+1. Tag 01: `11` (static). Fahipay QRs with an amount use `12` (dynamic)
+2. Tag 26: GUI (`mv.favara.mpqr`), acquirer BIC ×2 — `MALBMVMV` (BML) / `MADVMVMV` (MIB) / `FAHIMVMV` (Fahipay), account number, optional mobile, `IPAY`
+3. Tag 54: amount as `%.2f`. If there's no amount: omitted (BML), `***` (Fahipay)
+4. Tag 59: name, uppercased, max 25 chars
+5. Tag 60: Fahipay only — `LD` + 4 random digits
+6. Tag 62: the reference (above) + purpose
+7. Tag 80: GUI + timestamp `yyyy-MM-dd'T'HH:mm:ss.00000`
+8. Appends `"6304"` and computes CRC-16/CCITT-FALSE over the full string

 ### Actions

- **Share** (`btnShare`) — exports the rendered card via `FileProvider` + `ACTION_SEND`
- **Save** (`btnSave`, `PayMvQrFragment.kt:78`) — writes the PNG to `MediaStore.Images` / `Pictures/`
+- **Share** (`btnShare`) — writes `<name>_paymv_qr.png` to the cache and shares it via `FileProvider` + `ACTION_SEND`
+- **Save** (`btnSave`) — writes `<name>_PayMV_QR.png` to `MediaStore.Images` / `Pictures/`

 ---

@@ -31,10 +31,10 @@ Tags and lengths are always exactly 2 decimal digits. Fields are concatenated di
 | `35` | BML/gateway merchant info | Container — present in combined EMV+BML QRs and in BML POS QRs |
 | `52` | Merchant category code | `"0000"` (generic) |
 | `53` | Transaction currency | `"462"` = MVR (ISO 4217 numeric) |
-| `54` | Transaction amount | Decimal string (e.g. `"1.50"`); absent for open-amount QRs |
+| `54` | Transaction amount | Decimal string (e.g. `"1.50"`). Open-amount QRs: absent (Thijooree BML) or `"***"` (BML's and Fahipay's own QRs) |
 | `58` | Country code | `"MV"` |
-| `59` | Merchant / recipient name | Max 25 characters |
-| `60` | Merchant city / store code | BML POS QRs only |
+| `59` | Merchant / recipient name | Max 25 characters, uppercase in every real QR seen |
+| `60` | Merchant city / store code | `LD` + 4 digits (e.g. `LD0442`, `LD0745`). Seen in BML POS QRs and in BML's and Fahipay's own receive QRs; meaning of the digits unknown |
 | `62` | Additional data field | Container — see sub-tags below |
 | `63` | CRC | `6304` prefix + 4-char hex checksum — always last |
 | `80` | Supplementary data | Container — timestamp and domain |
@@ -66,8 +66,8 @@ Tags and lengths are always exactly 2 decimal digits. Fields are concatenated di

 | Sub-Tag | Field | Notes |
 |---|---|---|
-| `05` | Reference / bill number | 9 random uppercase alphanumeric characters |
-| `08` | Payment purpose | Free-form text entered by the payee |
+| `05` | Reference / bill number | Bank-specific — see [Reference (tag 62→05)](#reference-tag-6205). Also printed vertically on the QR card |
+| `08` | Payment purpose | Free-form text entered by the payee. BML's app defaults it to `Quickpay Transfer`, Fahipay to `PAYMENT` |

 ---

@@ -77,6 +77,7 @@ Tags and lengths are always exactly 2 decimal digits. Fields are concatenated di
 |---|---|---|
 | `00` | Domain | `"mv.favara.mpqr"` |
 | `01` | Timestamp | ISO 8601 format: `"yyyy-MM-dd'T'HH:mm:ss.00000"` |
+| `02` | Unknown | `"0005"` — only seen in Fahipay's own QR **with an amount**; not generated by Thijooree |

 ---

@@ -115,18 +116,98 @@ To create a QR that others can scan to pay you:
  10 04 IPAY
 52 04 0000                                 ← MCC
 53 03 462                                  ← MVR
-54 <len> <amount>                          ← Omit tag entirely if open-amount
+54 <len> <amount>                          ← "%.2f". Open amount: omit (BML) / "***" (Fahipay)
 58 02 MV
-59 <len> <name up to 25 chars>
+59 <len> <NAME UP TO 25 CHARS>             ← Uppercased
+60 06 LD<4 random digits>                  ← Fahipay only
 62 <len>
-  05 09 <9 random alphanum chars>          ← Reference
-  08 <len> <purpose text>
+  05 <len> <reference>                     ← Bank-specific, see below
+  08 <len> <purpose text>                  ← Omit if blank (BML) / "PAYMENT" (Fahipay)
 80 <len>
  00 15 mv.favara.mpqr
  01 <len> <yyyy-MM-dd'T'HH:mm:ss.00000>  ← Timestamp
 6304<CRC>
 ```

+For Fahipay, tag `01` is `12` (dynamic) when an amount is set.
+
+---
+
+## Reference (tag 62→05)
+
+The reference is also the **vertical text** printed beside the QR on both banks' cards, so it is calculated once and used for both (`PayMvQrFragment.generateQr()`).
+
+### BML — base-32 account number + amount
+
+```
+reference = base32(accountNumber) + amountAsTyped
+```
+
+- `base32` is BML's `AccountNumbertoBase32`: treat the account number as an integer and convert it to base 32 with the alphabet `0123456789ABCDEFGHIJKLMNOPQRSTUV`, most significant digit first
+- `amountAsTyped` is the amount field with commas removed and **no forced decimals** (`100` stays `100`, `100.5` stays `100.5`). Empty for open-amount QRs
+- Capped at 25 characters. A non-numeric account number falls back to 9 random characters
+
+| Account | Amount | Reference / vertical text |
+|---|---|---|
+| `7730000188362` | — | `70V3UKKUA` |
+| `7730000188362` | `100` | `70V3UKKUA100` |
+
+Confirmed by decoding a QR from BML's app: `62→05` = `70V3UKKUA`, the same as the vertical text on its card.
+
+### Fahipay — `P` + 9 random characters
+
+Fahipay's server issues references like `P135KOKXJY` and `P2KVTPYL4E`: `P` followed by 9 uppercase alphanumerics. The vertical text shows the reference only — **the amount is not appended** (confirmed on a QR carrying amount `55`). Thijooree generates `"P" + 9 random chars`.
+
+### Others
+
+9 random uppercase alphanumeric characters.
+
+---
+
+## Real Receive QRs (Reference Samples)
+
+Decoded from QR images generated by the official apps (CRC verified).
+
+**BML app** (open amount):
+
+```
+00020101021126920014mv.favara.mpqr0108MALBMVMV0208MALBMVMV031377300001883620511+96091980261004IPAY6006LD04425204000053034625403***5802MV5915SHIHAM A.RAHMAN6234050970V3UKKUA0817Quickpay Transfer80470014mv.favara.mpqr01252026-09-26T02:29:53.000006304F8E6
+```
+
+Note that BML's app places tag `60` *inside* tag `26` here (after `10 IPAY`, as `6006LD0442`).
+
+**Fahipay app**, open amount:
+
+```
+00020101021126810014mv.favara.mpqr0108FAHIMVMV0208FAHIMVMV03125008500611080511+96098074051004IPAY5204000053034625403***5802MV5912MOHAMED RAIF6006LD074562250510P135KOKXJY0807PAYMENT80470014mv.favara.mpqr01252026-09-26T03:44:36.0000063042707
+```
+
+**Fahipay app**, amount `55`:
+
+```
+00020101021226810014mv.favara.mpqr0108FAHIMVMV0208FAHIMVMV03125003600510030511+96091980261004IPAY5204000053034625402555802MV5919SHIHAM ABDUL RAHMAN6006LD097062250510P2KVTPYL4E0807PAYMENT80550014mv.favara.mpqr01252026-09-26T03:22:08.000000204000563045304
+```
+
+---
+
+## Fahipay (Work in Progress)
+
+> ⚠️ **Fahipay QRs generated by Thijooree do not work yet.** The Fahipay app rejects them as **"Invalid QR"**. BML QRs from Thijooree scan fine in the BML app.
+
+Fahipay's app doesn't build its QR locally: it fetches it from `GET api/app/qr/?lang=…&type=p2p&amount=…`, and the server returns the finished card image and payload. Things tried so far, with the Fahipay app still reporting invalid:
+
+| Change | Status |
+|---|---|
+| Mobile `26→05` normalised from Fahipay's stored `960XXXXXXX` to `+960XXXXXXX` | Done (was a real bug) |
+| Name `59` uppercased | Done |
+| `54` = `***` for open amount, `01` = `12` with an amount | Done |
+| `60` = `LD` + 4 random digits | Done |
+| `62→08` defaults to `PAYMENT` | Done |
+| `62→05` shaped `P` + 9 chars | Done |
+| `80→02` = `0005` (amount QRs only) | Not done |
+
+The CRC is correct (verified against all samples). With no amount, Thijooree's payload now has the same fields in the same order as Fahipay's own. The leading theory is that Fahipay's scanner looks up the `P…` reference on Fahipay's server, which issued it. If so, no locally generated QR can pass, and the fix would be to fetch the payload from `api/app/qr/` and render the card around it.
+
 ---

 ## Parsing a PayMV QR (Incoming Scan)
@@ -219,11 +300,11 @@ exactly one request is made either way.

 ## Example Payload

-Static QR for account `7700000000123`, holder `"AHMED ALI"`, open amount, purpose `"Rent"`:
+Static BML QR for account `7730000188362`, holder `"AHMED ALI"`, open amount, purpose `"Rent"`:

 ```
 000201010211268...520400005303462
-5802MV5909AHMED ALI6225050912345ABCDEF0804Rent
+5802MV5909AHMED ALI6221050970V3UKKUA0804Rent
 80...63044A2B
 ```

@@ -19,7 +19,7 @@ Documentation for app-specific logic — UI flows, routing decisions, and busine
 | [08 — Contacts](08-contacts.md) | Contact list, add/edit/delete, categories, contact picker sheet |
 | [09 — Activities](09-activities.md) | Local transfer log, TransferReceiptFragment, share/save receipt |
 | [10 — OTP Screen](10-otp-screen.md) | TOTP display, real-time countdown, enrolled bank authenticators |
-| [11 — PayMV QR Screen](11-paymv-qr-screen.md) | Generate receive-payment QR (send/scan lives in Transfer) |
+| [11 — PayMV QR Screen](11-paymv-qr-screen.md) | Generate receive-payment QR, BML/Fahipay card rendering, vertical reference text (Fahipay QRs WIP) |
 | [12 — BML QR Pay](12-bml-qr-pay.md) | (Stub — see Transfer Flows for the live BML QR merchant flow) |
 | [13 — Financing](13-financing.md) | MIB promotional deals, BML loans, BML foreign spend limits |
 | [14 — Settings](14-settings.md) | Settings hub: Logins (drag to reorder), Appearance, Privacy & Security, Notifications, Storage, About |
@@ -39,7 +39,7 @@ Documentation for app-specific logic — UI flows, routing decisions, and busine

 | Document | Description |
 |---|---|
-| [18 — PayMV QR Format](18-paymv-qr-format.md) | Decimal TLV encoding, all tags, CRC-16, QR generation recipe, parsing reference |
+| [18 — PayMV QR Format](18-paymv-qr-format.md) | Decimal TLV encoding, all tags, CRC-16, per-bank references, real samples, Fahipay WIP, parsing reference |
 | [19 — Parsers](19-parsers.md) | Account display parser architecture — how raw bank API data is normalised into a unified `AccountListDisplay` model |
 | [20 — Transfer Flows](20-transfer-flows.md) | TransferFragment entry points, recipient lookup, transfer type routing, rejected combinations, BML business OTP flow, BML QR merchant payments |
 | [AI Security Audit](AI_SECURITY_CHECK.md) | Full source security audit — credential storage, network layer, manifest, data privacy |