android/docs/thijooree/07-transfer.md

# Transfer

The transfer screen initiates account-to-account fund transfers and phone payments. It supports MIB, BML, Fahipay and M-Faisa as sources and handles all bank-specific authentication and OTP steps. A phone number can also be paid as a carrier service (reload, Raastas, bill pay) from the Fahipay wallet or, for Dhiraagu Reload, a verified BML card.

---

## Fragment — `TransferFragment`

Opened via:
- Navigation menu
- Quick-transfer button on an account row (source pre-selected)
- `OPEN_TRANSFER` intent action
- `OPEN_SCAN_QR` intent — opens the QR scanner immediately (`newInstanceWithAutoScan()`)
- QR scan result (recipient and optional amount pre-filled)
- Donate buttons in Settings → About (`newInstance(...)` with pre-filled recipient)

### Factory Methods

All defined in `TransferFragment.kt:179-242`:

| Method | Use case |
|---|---|
| `newInstance(accountNumber, displayName, subtitle, colorHex, imageHash)` | Pre-fill recipient (contact tap, recents, donate) |
| `newInstanceFrom(account)` | Pre-select a source account (quick-transfer from accounts list) |
| `newInstanceFromQr(accountNumber, displayName, amount, remarks, fromAccountNumber?)` | PayMV QR scan |
| `newInstanceFromBmlQr(qrUrl, fromAccountNumber?)` | BML ebanking / pay.bml URL scan — locks recipient |
| `newInstanceWithAutoScan()` | Open the QR scanner on load |

See [Transfer Flows](20-transfer-flows.md) for the full routing logic.

---

## Source Account Selection

A dropdown lists all visible accounts parsed via `AccountListParser.from(acc)?.balance`. The selected source account determines which bank's transfer flow is used.

---

## Recipient Entry

The user can specify a recipient in these ways:

1. **Manual entry** — type an account number or phone number directly
2. **Contact picker** — opens `ContactPickerSheetFragment` to select a saved contact. A Fahipay favourite opens as its payout service straight away
3. **QR scan** — launches [QrScannerActivity](25-qr-scanner.md); a PayMV QR result pre-fills the account number, amount, and remarks; a BML ebanking / pay.bml URL switches the form into [BML QR merchant payment](20-transfer-flows.md#bml-qr-merchant-payment-flow) mode
4. **BML Merchant Services transaction ID or link** — paid through BML Pay (QR flow) or, for card-only merchants, a verified card ([Card Verification & Merchant Card Pay](29-card-verification-and-merchant-card-pay.md))

---

## Fields

| Field | Notes |
|---|---|
| Source account | Dropdown; balance shown below |
| Recipient account number | Text input or filled from contact/QR |
| Recipient name | Auto-looked up from bank API after account number entry |
| Amount | Numeric; pre-filled from QR if available |
| Remarks / purpose | Free text; pre-filled from QR if available |

---

## Recipient Lookup

After the user finishes entering a recipient account number, the app calls the source bank's name-lookup API:

- **MIB**: account name lookup via MIB API
- **BML**: beneficiary lookup via BML API
- **Fahipay**: phone numbers only — the Dhiraagu / Ooredoo carrier lookup decides which payout services apply

The resolved name is displayed below the account number field for the user to confirm.

### Phone numbers — Transfer Type picker

A phone number searched with no source yet (or from a BML card that can pay by card) is looked up every way it can be paid, in parallel: Favara (MIB / BML), and the carrier lookup when the user has a Fahipay wallet or a verified BML card. Each result is a **transfer type**:

| Type | Example | Pays from |
|---|---|---|
| Favara Transfer | bank account behind the number | MIB or BML account |
| Fahipay service | Raastas, Ooredoo Bill Pay, Dhiraagu Reload, Dhiraagu Bill Pay | Fahipay wallet |
| Card service | Dhiraagu Reload, Dhiraagu Bill Pay, Raastas, Ooredoo Bill Pay (BML badge) | Verified BML card |

One option is applied straight away; with more, a picker opens and Send stays disabled until one is chosen. Picking a type also picks a source that can pay it. Fahipay and card services clear and disable the Remarks field and apply their own amount rules (minimum, maximum, whole amounts, 8% GST note). Details: [Transfer Flows → Transfer Type picker](20-transfer-flows.md#transfer-type-picker).

---

## Biometric Gate

If both `biometrics_enabled` and `biometrics_transfer_confirm` are set in Settings → Security (`SettingsSecurityFragment.kt:59`), `BiometricPrompt` is shown before the transfer is submitted. A failed or cancelled biometric blocks submission.

---

## BML USD → MIB Auto-Add Contact

When the source is a BML USD account and the destination is a MIB account but no saved BML contact exists for it, the app shows a "Contact required" dialog with a **Save** button that opens `AddContactSheetFragment.newInstance(bmlProfileId, accountNumber, recipientName, currency)` pre-filled (`TransferFragment.kt:1136-1164`). The user must save the contact through this sheet before BML can issue a USD cross-bank transfer.

---

## Bank-Specific Flows

### MIB Transfer

1. Validates fields
2. (If biometric gate) prompts biometrics
3. Submits transfer via `MibLoginFlow` using active MIB session (serialized through `mibMutex`)
4. On success, shows `TransferReceiptFragment`

### BML Transfer

1. Validates fields
2. (If biometric gate) prompts biometrics
3. Initiates BML transfer — server responds with OTP required
4. Navigates to `OtpFragment` to collect the TOTP
5. Re-submits with OTP
6. On success, shows `TransferReceiptFragment`

### Fahipay Payout (reload, Raastas, bill pay)

1. Checks the amount against the picked service's rules
2. Confirm dialog (with the GST note for Raastas), then the biometric gate if enabled
3. One POST to the service's Fahipay payment endpoint ([Fahipay API → Payments](../fahipayapi/09-payments.md))
4. On success, the result shows inside the dialog (no receipt page yet), then the form clears

See [Transfer Flows → Fahipay source](20-transfer-flows.md#fahipay-source).

### Carrier Service by BML Card (Dhiraagu Reload / Bill Pay, Ooredoo Raastas / Bill Pay)

1. Checks the amount against the carrier's rules (Dhiraagu reload: MVR 20–1000, whole amounts, 8% GST included; Dhiraagu bill pay: from MVR 1, up to 2 decimals, no GST; Raastas: from MVR 20, whole amounts, 8% GST added on top; Ooredoo bill pay: from MVR 10, up to 2 decimals, no GST)
2. A "Processing..." dialog shows while the carrier creates the order and its BML merchant transaction ([Dhiraagu API → Reload](../dhiraaguapi/02-reload.md), [→ Bill Pay](../dhiraaguapi/03-bill-pay.md), [Ooredoo API → Raastas](../ooredooapi/02-raastas.md), [→ Bill Pay](../ooredooapi/03-bill-pay.md))
3. From there it is the card-only merchant flow: the same confirm dialog and warning, biometric gate, card + 3-D Secure payment, and the return to the carrier (`?wait=1`) that tops the number up or posts the bill payment. A decline (e.g. insufficient funds) or a rejected token code ends it with the bank's message
4. On success, the result shows inside the dialog; if Dhiraagu couldn't be notified, a toast gives the BML transaction id

See [Transfer Flows → Carrier services by BML card](20-transfer-flows.md#carrier-services-by-bml-card).

### BML Merchant Payment (QR / card-only link)

A BML QR, or a BML Merchant Services link whose merchant takes BML Pay, is paid from a BML card through the QR flow. A card-only merchant link is paid with a verified card (Pomelo + 3-D Secure), followed by the return to the merchant. Neither saves a receipt. See [Transfer Flows → BML QR Merchant Payment Flow](20-transfer-flows.md#bml-qr-merchant-payment-flow) and [Card Verification & Merchant Card Pay](29-card-verification-and-merchant-card-pay.md).

---

## Transfer Receipt

On success of a bank transfer (MIB, BML, M-Faisa) the fragment navigates to `TransferReceiptFragment` passing the completed transfer details. Fahipay payouts, card services and merchant payments show their result inside the confirm dialog instead.

---

## Error Handling

All bank API errors are shown as a `Snackbar` or inline error message. Session expiry triggers a re-authentication prompt rather than a crash.

---

 

---

[← Transfer History](06-transfer-history.md)     **Next →** [Contacts](08-contacts.md)