release v1.0.23

app/build.gradle.kts

@@ -21,8 +21,8 @@ android {
         applicationId = "sh.sar.basedbank"
         minSdk = 26
         targetSdk = 36
-        versionCode = 22
+        versionCode = 24
-        versionName = "1.0.21"
+        versionName = "1.0.23"
 
         testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
 

app/src/main/java/sh/sar/basedbank/ui/home/PayMvQrFragment.kt

@@ -83,6 +83,7 @@ class PayMvQrFragment : Fragment() {
             val eligible = accounts.filter {
                 it.profileType != "BML_PREPAID" && it.profileType != "BML_CREDIT" && it.profileType != "BML_DEBIT" && it.profileType != "BML_LOAN" &&
                 it.bank != "MIB" && // TODO: MIB does not support PayMV QR
+                it.bank != "MFAISA" && // TODO: M-Faisa PayMV QR not implemented yet
                 !(it.bank == "BML" && it.currencyName.contains("USD", ignoreCase = true)) // TODO: BML USD not supported by MMA
             }
             val adapter = QrAccountAdapter(requireContext(), eligible)

app/src/main/java/sh/sar/basedbank/ui/home/TransferReceiptFragment.kt

@@ -11,17 +11,13 @@ import android.graphics.BitmapFactory
 import android.graphics.Canvas
 import android.graphics.Color
 import android.graphics.Paint
-import android.graphics.Rect
 import android.net.Uri
 import android.os.Build
 import android.os.Bundle
 import android.os.Environment
-import android.os.Handler
-import android.os.Looper
 import android.provider.MediaStore
 import android.util.Base64
 import android.view.LayoutInflater
-import android.view.PixelCopy
 import android.view.View
 import android.view.ViewGroup
 import android.widget.Toast
@@ -159,9 +155,6 @@ class TransferReceiptFragment : Fragment() {
             }
         })
 
-        view.findViewById<MaterialButton>(R.id.btnDone).setOnClickListener {
-            parentFragmentManager.popBackStack()
-        }
         view.findViewById<MaterialButton>(R.id.btnShare).setOnClickListener {
             shareReceipt()
         }
@@ -377,21 +370,19 @@ class TransferReceiptFragment : Fragment() {
     // ── Helpers ───────────────────────────────────────────────────────────────
 
     /**
-     * Captures the receipt card using PixelCopy, which correctly handles
+     * Draws the receipt card to an offscreen bitmap at its natural (unscaled)
-     * hardware-accelerated views (avoids the black-square problem with view.draw()).
+     * dimensions, so the captured image isn't affected by the on-screen scale
+     * applied to fit small viewports and doesn't pick up overlapping siblings.
      */
     private fun captureReceiptBitmap(callback: (Bitmap?) -> Unit) {
         val view = _receiptCard ?: run { callback(null); return }
         if (view.width == 0 || view.height == 0) { callback(null); return }
 
         val bitmap = Bitmap.createBitmap(view.width, view.height, Bitmap.Config.ARGB_8888)
-        val location = IntArray(2)
+        val canvas = Canvas(bitmap)
-        view.getLocationInWindow(location)
+        canvas.drawColor(Color.WHITE)
-        val srcRect = Rect(location[0], location[1], location[0] + view.width, location[1] + view.height)
+        view.draw(canvas)
-
+        callback(bitmap)
-        PixelCopy.request(requireActivity().window, srcRect, bitmap, { result ->
-            callback(if (result == PixelCopy.SUCCESS) bitmap else null)
-        }, Handler(Looper.getMainLooper()))
     }
 
     private fun formatBmlTimestamp(raw: String): String {
@@ -494,13 +485,9 @@ class TransferReceiptFragment : Fragment() {
         (activity as? HomeActivity)?.setBottomNavVisible(false)
     }
 
-    override fun onPause() {
-        super.onPause()
-        (activity as? HomeActivity)?.setBottomNavVisible(true)
-    }
-
     override fun onDestroyView() {
         super.onDestroyView()
+        (activity as? HomeActivity)?.setBottomNavVisible(true)
         _receiptCard = null
         pendingToAvatarBitmap = null
     }

app/src/main/java/sh/sar/basedbank/ui/home/transfer/BmlTransferHandler.kt

@@ -0,0 +1,730 @@
+package sh.sar.basedbank.ui.home.transfer
+
+import android.graphics.Bitmap
+import android.view.Gravity
+import android.view.View
+import android.widget.ImageView
+import android.widget.LinearLayout
+import android.widget.TextView
+import android.widget.Toast
+import androidx.appcompat.app.AlertDialog
+import androidx.lifecycle.lifecycleScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import sh.sar.basedbank.BasedBankApp
+import sh.sar.basedbank.R
+import sh.sar.basedbank.api.bml.BmlAccountClient
+import sh.sar.basedbank.api.bml.BmlOtpChannel
+import sh.sar.basedbank.api.bml.BmlQrPayClient
+import sh.sar.basedbank.api.bml.BmlQrPayInfo
+import sh.sar.basedbank.api.bml.BmlQrPayResult
+import sh.sar.basedbank.api.bml.BmlSession
+import sh.sar.basedbank.api.bml.BmlTransferClient
+import sh.sar.basedbank.api.bml.BmlValidateClient
+import sh.sar.basedbank.api.models.BankAccount
+import sh.sar.basedbank.api.models.BankContact
+import sh.sar.basedbank.api.mib.MibIpsAccountInfo
+import sh.sar.basedbank.databinding.FragmentTransferBinding
+import sh.sar.basedbank.ui.home.HomeActivity
+import sh.sar.basedbank.ui.home.HomeViewModel
+import sh.sar.basedbank.ui.home.TransferFragment
+import sh.sar.basedbank.ui.home.TransferReceiptData
+import sh.sar.basedbank.util.CredentialStore
+import sh.sar.basedbank.util.RecentPick
+import sh.sar.basedbank.util.RecentsCache
+import sh.sar.basedbank.util.Totp
+
+/**
+ * Owns the BML-only parts of the Transfer screen: session lookup, the CASA/card transfer itself,
+ * the business-profile OTP state machine (channel pick → initiate → verify), and merchant QR
+ * payment (card/gateway QR lookup + pre-initiate/initiate/confirm).
+ *
+ * Lives alongside [TransferFragment], which dispatches to it whenever the selected source's
+ * [BankAccount.bank] is "BML", and mirrors [MfaisaTransferHandler]'s shape: the fragment keeps
+ * the shared confirm dialog, the "To" lookup and the form state; the handler keeps everything
+ * BML-specific.
+ *
+ * Lifetime is bound to the fragment's view: it captures [binding] + [viewModel] + [fragment] (for
+ * [androidx.fragment.app.Fragment.viewLifecycleOwner] and Context) — and must be re-created when
+ * the view is recreated.
+ */
+class BmlTransferHandler(
+    private val fragment: TransferFragment,
+    private val binding: FragmentTransferBinding,
+    private val viewModel: HomeViewModel,
+    /** Reads the fragment's currently-selected source account. */
+    private val currentSource: () -> BankAccount?,
+    /** Asks the fragment to make [BankAccount] the source (amount prefix + from-card + Send state). */
+    private val selectSource: (BankAccount) -> Unit,
+    /** Hook called whenever handler state changes in a way that affects the Send button. */
+    private val onStateChanged: () -> Unit,
+    /** Hook called on a successful transfer; fragment navigates to the receipt and refreshes balances. */
+    private val onTransferSuccess: (TransferReceiptData, Bitmap?) -> Unit,
+) {
+
+    private val app get() = fragment.requireActivity().application as BasedBankApp
+    private val ctx get() = fragment.requireContext()
+    private val host get() = fragment.activity as? HomeActivity
+
+    // ─── State ───────────────────────────────────────────────────────────────
+
+    /** Business-profile OTP flow. NONE means the Send button behaves normally. */
+    private enum class OtpState { NONE, SELECTING_CHANNEL, AWAITING_OTP }
+    private var otpState = OtpState.NONE
+    private var otpChannel: String? = null
+
+    private data class PendingTransfer(
+        val src: BankAccount,
+        val debitAccount: String,
+        val creditAccount: String,
+        val amount: Double,
+        val amountStr: String,
+        val remarks: String,
+        val transferType: String,
+        val currency: String,
+        val bank: String?,
+        val destDisplay: String,
+        val destAccount: String,
+        val toBank: String,
+        val toAvatar: Bitmap?
+    )
+    private var pendingTransfer: PendingTransfer? = null
+
+    /** Merchant QR payment mode (set when navigated from a card/gateway QR scan). */
+    var qrInfo: BmlQrPayInfo? = null
+        private set
+    /** True for pay.bml.com.mv QRs, which need an extra pre-initiate step. */
+    private var gatewayQr = false
+    /** Prevents re-running the lookup after the user clears the merchant. */
+    var qrLookupAttempted = false
+        private set
+
+    // ─── Public API the fragment calls ───────────────────────────────────────
+
+    /** Whether the business OTP flow is mid-way — the fragment freezes the Send button while it is. */
+    val isOtpFlowActive: Boolean get() = otpState != OtpState.NONE
+
+    /** Whether the Send button should verify an OTP instead of starting a new transfer. */
+    val isAwaitingOtp: Boolean get() = otpState == OtpState.AWAITING_OTP
+
+    /** Whether a merchant QR is loaded — counts as a resolved recipient for the Send button. */
+    val hasQrMerchant: Boolean get() = qrInfo != null
+
+    fun sessionFor(account: BankAccount?): BmlSession? =
+        account?.let { app.bmlSessionFor(it) } ?: app.anyBmlSession()
+
+    fun isBusinessProfile(account: BankAccount): Boolean {
+        val loginId = account.loginTag.removePrefix("bml_")
+        val profiles = app.bmlProfilesMap[loginId] ?: return false
+        return profiles.firstOrNull { it.profileId == account.profileId }?.profileType == "business"
+    }
+
+    /**
+     * Resolves a destination through BML — `verifyMibAccount` when [verifyAsMib], otherwise the
+     * regular alias/account validation. Blocking; call from IO. Returns null when BML can't
+     * resolve it, so the caller can fall back to the MIB IPS lookup.
+     *
+     * The result is mapped onto [MibIpsAccountInfo] because that is the Transfer screen's common
+     * "resolved recipient" shape, whichever bank did the resolving. Note that the MIB-verify
+     * endpoint leaves `currency` blank — the caller enriches it via
+     * [MibTransferHandler.lookupCurrency] when a MIB session is available.
+     */
+    fun validateDestination(
+        session: BmlSession,
+        accountNumber: String,
+        verifyAsMib: Boolean
+    ): MibIpsAccountInfo? {
+        val result = try {
+            if (verifyAsMib) BmlValidateClient().verifyMibAccount(session, accountNumber)
+            else BmlValidateClient().validateAccount(session, accountNumber)
+        } catch (_: Exception) { null } ?: return null
+        val bankId = when (result.trnType) {
+            "IAT" -> "MALBMVMV"
+            else  -> result.agnt ?: result.account
+        }
+        return MibIpsAccountInfo(
+            accountName = result.name,
+            accountNumber = result.account,
+            bankId = bankId,
+            currency = result.currency
+        )
+    }
+
+    /** Drops the loaded merchant and unlocks the amount/remarks fields the QR mode had frozen. */
+    fun clearQrMerchant() {
+        if (qrInfo == null) return
+        qrInfo = null
+        gatewayQr = false
+        binding.tilAmount.isEnabled = true
+        binding.tilRemarks.isEnabled = true
+        binding.tilRemarks.alpha = 1f
+        binding.etAmount.setText("")
+    }
+
+    /** Called when the view tears down — an in-flight OTP flow cannot sensibly resume. */
+    fun clearState() {
+        otpState = OtpState.NONE
+        otpChannel = null
+        pendingTransfer = null
+    }
+
+    // ─── Merchant QR ─────────────────────────────────────────────────────────
+
+    fun lookupQrMerchant(qrUrl: String) {
+        qrLookupAttempted = true
+        gatewayQr = qrUrl.startsWith("https://pay.bml.com.mv/app/")
+        val base64Url = android.util.Base64.encodeToString(
+            qrUrl.toByteArray(Charsets.UTF_8), android.util.Base64.NO_WRAP)
+        val session = app.anyBmlSession() ?: return
+
+        // Lock the "To" input row while loading
+        binding.tilTo.visibility = View.GONE
+        binding.btnPickContact.visibility = View.GONE
+        binding.btnScanQr.visibility = View.GONE
+        host?.setRefreshing(true)
+
+        fragment.viewLifecycleOwner.lifecycleScope.launch {
+            val info = withContext(Dispatchers.IO) {
+                try { BmlQrPayClient().lookupPayRequest(session, base64Url) }
+                catch (_: Exception) { null }
+            }
+            host?.setRefreshing(false)
+            if (info == null) {
+                Toast.makeText(ctx, R.string.bml_qr_lookup_failed, Toast.LENGTH_LONG).show()
+                fragment.requireActivity().onBackPressedDispatcher.onBackPressed()
+                return@launch
+            }
+            qrInfo = info
+            if (info.amount == 0.0) {
+                RecentsCache.save(ctx, RecentPick(
+                    accountNumber = "bmlqr:$qrUrl",
+                    displayName   = info.merchantName,
+                    subtitle      = info.merchantAddress.ifBlank { "BML Merchant" },
+                    colorHex      = "#0066A1",
+                    imageHash     = null,
+                    isProfileImage = false
+                ))
+            }
+
+            // Auto-select the user's default BML card if no card was pre-selected
+            if (currentSource() == null) {
+                val defaultNum = CredentialStore(ctx).getDefaultCardAccountNumber()
+                if (defaultNum != null) {
+                    val allAccounts = viewModel.accounts.value ?: emptyList()
+                    val defaultCard = allAccounts.firstOrNull {
+                        it.accountNumber == defaultNum && isCard(it) &&
+                        it.statusDesc.equals("Active", ignoreCase = true)
+                    }
+                    if (defaultCard != null) selectSource(defaultCard)
+                }
+            }
+
+            // Show merchant in the "To" card — clear button hidden (can't change recipient for QR)
+            binding.tvToAccountName.text = info.merchantName
+            binding.tvToBankBic.text = info.merchantAddress.ifBlank { "BML Merchant" }
+            binding.tvToAccountDetails.visibility = View.GONE
+            binding.tvToBalance.visibility = View.GONE
+            binding.ivToPhoto.scaleType = android.widget.ImageView.ScaleType.CENTER_CROP
+            binding.ivToPhoto.setImageBitmap(fragment.makeInitialsBitmap(info.merchantName, "#0066A1"))
+            binding.cardToInfo.visibility = View.VISIBLE
+
+            // Pre-fill amount if dynamic QR
+            if (info.amount > 0.0) {
+                binding.etAmount.setText("%.2f".format(info.amount))
+                binding.tilAmount.isEnabled = false
+            }
+
+            // Remarks not applicable for merchant QR payments
+            binding.tilRemarks.isEnabled = false
+            binding.tilRemarks.alpha = 0.4f
+
+            onStateChanged()
+        }
+    }
+
+    /**
+     * Confirm-then-pay for a loaded merchant QR. Uses the fragment's shared confirm dialog and
+     * reports the outcome inside it — there is no receipt screen for merchant payments.
+     */
+    fun submitQrPayment() {
+        val info = qrInfo ?: return
+        val src = currentSource() ?: run {
+            Toast.makeText(ctx, R.string.transfer_session_unavailable, Toast.LENGTH_SHORT).show()
+            return
+        }
+        val amountStr = binding.etAmount.text?.toString()?.trim() ?: ""
+        val amount = amountStr.toDoubleOrNull()
+        if (amount == null || amount <= 0) { binding.tilAmount.error = "Enter a valid amount"; return }
+        binding.tilAmount.error = null
+        val debitAccount = src.internalId.ifBlank {
+            Toast.makeText(ctx, R.string.transfer_missing_internal_id, Toast.LENGTH_SHORT).show()
+            return
+        }
+        val fromTypeLabel = sh.sar.basedbank.util.AccountListParser.from(src)?.typeLabel
+            ?: sh.sar.basedbank.util.bmlapi.BmlDashboardParser.productLabel(src.accountTypeName)
+        val fromDetail = listOfNotNull("BML", fromTypeLabel.ifBlank { null }).joinToString(" · ")
+        val confirmView = fragment.buildTransferConfirmView(
+            amountCurrency = info.currency,
+            amountValue = "%.2f".format(amount),
+            fromName = src.accountBriefName,
+            fromNumber = src.accountNumber,
+            fromDetail = fromDetail,
+            toName = info.merchantName,
+            toNumber = "",
+            toDetail = info.merchantAddress.ifBlank { "BML Merchant" }
+        )
+        fragment.showConfirmWithBiometric(
+            title = ctx.getString(R.string.transfer),
+            customView = confirmView,
+            biometricSubtitle = "${info.currency} ${"%.2f".format(amount)} → ${info.merchantName}",
+            onConfirmed = { dialog, frame ->
+                fragment.showProcessingInDialog(dialog, frame)
+                executeQrPayment(src, debitAccount, info, amount, dialog, frame)
+            }
+        )
+    }
+
+    private fun executeQrPayment(
+        src: BankAccount,
+        debitAccount: String,
+        info: BmlQrPayInfo,
+        amount: Double,
+        dialog: AlertDialog,
+        frame: android.widget.FrameLayout
+    ) {
+        val loginId = src.loginTag.removePrefix("bml_")
+        val session = sessionFor(src) ?: run {
+            dialog.dismiss()
+            Toast.makeText(ctx, R.string.transfer_session_unavailable, Toast.LENGTH_SHORT).show()
+            return
+        }
+        val otp = CredentialStore(ctx).loadBmlCredentials(loginId)?.otpSeed
+            ?.let { Totp.generate(it) }
+            ?: run { dialog.dismiss(); Toast.makeText(ctx, "OTP unavailable", Toast.LENGTH_SHORT).show(); return }
+
+        binding.btnTransfer.isEnabled = false
+
+        fragment.viewLifecycleOwner.lifecycleScope.launch {
+            val result = withContext(Dispatchers.IO) {
+                try {
+                    if (gatewayQr) {
+                        val preOk = BmlQrPayClient().preInitiatePayment(
+                            session, debitAccount, info.requestId, amount, info.currency)
+                        if (!preOk) return@withContext null
+                    }
+                    val initiated = BmlQrPayClient().initiatePayment(
+                        session, debitAccount, info.requestId, amount, info.currency)
+                    if (!initiated) return@withContext null
+                    val confirmOtp = CredentialStore(ctx).loadBmlCredentials(loginId)
+                        ?.otpSeed?.let { Totp.generate(it) } ?: otp
+                    BmlQrPayClient().confirmPayment(
+                        session, debitAccount, info.requestId, amount, info.currency, confirmOtp)
+                } catch (e: Exception) {
+                    BmlQrPayResult(false, errorMessage = e.message ?: "Payment failed")
+                }
+            }
+            if (fragment.view == null) return@launch
+
+            if (result == null) {
+                dialog.dismiss()
+                binding.btnTransfer.isEnabled = true
+                Toast.makeText(ctx, "Failed to initiate payment", Toast.LENGTH_LONG).show()
+                return@launch
+            }
+            if (result.success) {
+                fragment.showSuccessInDialog(
+                    dialog, frame,
+                    amountCurrency = result.currency.ifBlank { info.currency },
+                    amountValue = result.amount.ifBlank { "%.2f".format(amount) },
+                    fromName = src.accountBriefName,
+                    toName = result.merchant.ifBlank { info.merchantName }
+                ) {
+                    fragment.clearForm()
+                    host?.triggerRefresh()
+                }
+            } else {
+                dialog.dismiss()
+                binding.btnTransfer.isEnabled = true
+                Toast.makeText(ctx, result.errorMessage, Toast.LENGTH_LONG).show()
+            }
+        }
+    }
+
+    // ─── Personal-profile transfer (token OTP, no user interaction) ──────────
+
+    /**
+     * Runs initiate + confirm on the calling (IO) thread and returns
+     * `(ok, message, receipt)`. Message is "CONNECTIVITY" when the network was unreachable.
+     */
+    fun doTransfer(
+        src: BankAccount,
+        destAccount: String,
+        destDisplay: String,
+        amount: Double,
+        amountStr: String,
+        remarks: String,
+        isSrcCard: Boolean,
+        isDestMib: Boolean,
+        currency: String,
+        allAccounts: List<BankAccount>,
+        allContacts: List<BankContact>
+    ): Triple<Boolean, String, TransferReceiptData?> {
+        val loginId = src.loginTag.removePrefix("bml_")
+        val sess = sessionFor(src) ?: return Triple(false, ctx.getString(R.string.transfer_session_unavailable), null)
+        val otp = CredentialStore(ctx).loadBmlCredentials(loginId)?.otpSeed
+            ?.let { Totp.generate(it) }
+            ?: return Triple(false, "OTP unavailable", null)
+        val debitAccount = src.internalId.ifBlank {
+            return Triple(false, ctx.getString(R.string.transfer_missing_internal_id), null)
+        }
+
+        val routed = routeTransfer(destAccount, isSrcCard, isDestMib, currency, allAccounts, allContacts)
+            ?: return Triple(false, "BML contact not found for this account", null)
+        val (transferType, creditAccount, bank) = routed
+        val toBank = bank ?: if (isDestMib) "MIB" else "BML"
+
+        // Step 1: initiate
+        val initiated = try {
+            BmlTransferClient().initiateTransfer(sess, debitAccount, creditAccount, amount, transferType, currency, bank)
+        } catch (e: Exception) { return Triple(false, if (e is java.io.IOException) "CONNECTIVITY" else (e.message ?: "Initiation failed"), null) }
+
+        if (!initiated) return Triple(false, "Failed to initiate transfer — check your session", null)
+
+        // Step 2: confirm with fresh OTP
+        val confirmOtp = CredentialStore(ctx).loadBmlCredentials(loginId)?.otpSeed
+            ?.let { Totp.generate(it) } ?: otp
+
+        return try {
+            val result = BmlTransferClient().confirmTransfer(sess, debitAccount, creditAccount, amount, transferType, currency, confirmOtp, remarks, bank)
+            if (result.success) {
+                val receipt = TransferReceiptData(
+                    bank = "BML",
+                    amount = "%.2f".format(amount),
+                    currency = currency,
+                    fromLabel = src.accountBriefName,
+                    fromColorHex = "#0066A1",
+                    toLabel = destDisplay.ifBlank { destAccount },
+                    toAccount = destAccount,
+                    toBank = toBank,
+                    remarks = remarks,
+                    bmlFromName = src.accountBriefName,
+                    bmlReference = result.reference,
+                    bmlTimestamp = result.timestamp,
+                    bmlMessage = result.message
+                )
+                val time = result.timestamp.take(19).replace("T", " ")
+                Triple(true, "Reference: ${result.reference}\n$time", receipt)
+            } else {
+                Triple(false, result.errorMessage.ifBlank { "Transfer failed" }, null)
+            }
+        } catch (e: Exception) {
+            Triple(false, if (e is java.io.IOException) "CONNECTIVITY" else (e.message ?: "Transfer failed"), null)
+        }
+    }
+
+    // ─── Business profile OTP flow ───────────────────────────────────────────
+
+    fun startBusinessOtpFlow(
+        src: BankAccount,
+        destAccount: String,
+        destDisplay: String,
+        amount: Double,
+        amountStr: String,
+        remarks: String,
+        isSrcCard: Boolean,
+        isDestMib: Boolean,
+        currency: String,
+        allAccounts: List<BankAccount>,
+        allContacts: List<BankContact>,
+        toAvatar: Bitmap?
+    ) {
+        val debitAccount = src.internalId.ifBlank {
+            Toast.makeText(ctx, ctx.getString(R.string.transfer_missing_internal_id), Toast.LENGTH_SHORT).show()
+            return
+        }
+        val routed = routeTransfer(destAccount, isSrcCard, isDestMib, currency, allAccounts, allContacts)
+        if (routed == null) {
+            Toast.makeText(ctx, "BML contact not found for this account", Toast.LENGTH_SHORT).show()
+            return
+        }
+        val (transferType, creditAccount, bank) = routed
+        val toBank = bank ?: if (isDestMib) "MIB" else "BML"
+
+        pendingTransfer = PendingTransfer(
+            src           = src,
+            debitAccount  = debitAccount,
+            creditAccount = creditAccount,
+            amount        = amount,
+            amountStr     = amountStr,
+            remarks       = remarks,
+            transferType  = transferType,
+            currency      = currency,
+            bank          = bank,
+            destDisplay   = destDisplay,
+            destAccount   = destAccount,
+            toBank        = toBank,
+            toAvatar      = toAvatar
+        )
+
+        otpState = OtpState.SELECTING_CHANNEL
+        binding.btnTransfer.isEnabled = false
+        host?.setRefreshing(true)
+
+        fragment.viewLifecycleOwner.lifecycleScope.launch {
+            val sess = sessionFor(src)
+            val channels = if (sess != null) {
+                withContext(Dispatchers.IO) {
+                    try { BmlAccountClient().fetchTransferChannels(sess) }
+                    catch (_: Exception) { emptyList() }
+                }
+            } else emptyList<BmlOtpChannel>()
+
+            host?.setRefreshing(false)
+
+            if (channels.isEmpty()) {
+                Toast.makeText(ctx, "Could not load OTP channels", Toast.LENGTH_SHORT).show()
+                resetOtpState()
+                onStateChanged()
+                return@launch
+            }
+
+            showChannelSelection(channels)
+        }
+    }
+
+    private fun showChannelSelection(channels: List<BmlOtpChannel>) {
+        val dp = ctx.resources.displayMetrics.density
+        binding.containerBmlChannels.removeAllViews()
+
+        for (channel in channels) {
+            val iconRes = when (channel.channel) {
+                "email"  -> R.drawable.ic_channel_email
+                "mobile" -> R.drawable.ic_channel_sms
+                else     -> R.drawable.ic_channel_sms
+            }
+            val iconSize = (24 * dp).toInt()
+
+            val textCol = LinearLayout(ctx).apply {
+                orientation = LinearLayout.VERTICAL
+                gravity = Gravity.CENTER_VERTICAL
+                layoutParams = LinearLayout.LayoutParams(0, LinearLayout.LayoutParams.WRAP_CONTENT, 1f).apply {
+                    marginStart = (12 * dp).toInt()
+                }
+            }
+            textCol.addView(TextView(ctx).apply {
+                text = channel.description
+                setTextAppearance(com.google.android.material.R.style.TextAppearance_Material3_BodyLarge)
+            })
+            textCol.addView(TextView(ctx).apply {
+                text = channel.masked
+                setTextAppearance(com.google.android.material.R.style.TextAppearance_Material3_BodySmall)
+                alpha = 0.6f
+            })
+
+            val row = LinearLayout(ctx).apply {
+                orientation = LinearLayout.HORIZONTAL
+                gravity = Gravity.CENTER_VERTICAL
+                val ta = ctx.obtainStyledAttributes(intArrayOf(android.R.attr.selectableItemBackground))
+                background = ta.getDrawable(0); ta.recycle()
+                isClickable = true; isFocusable = true
+                val hp = (16 * dp).toInt(); val vp = (12 * dp).toInt()
+                setPadding(hp, vp, hp, vp)
+            }
+            row.addView(ImageView(ctx).apply { setImageResource(iconRes) },
+                LinearLayout.LayoutParams(iconSize, iconSize))
+            row.addView(textCol)
+            row.setOnClickListener { selectOtpChannel(channel) }
+            binding.containerBmlChannels.addView(row)
+        }
+
+        disableTransferFields()
+        binding.layoutBmlChannelSelection.visibility = View.VISIBLE
+    }
+
+    private fun selectOtpChannel(channel: BmlOtpChannel) {
+        otpChannel = channel.channel
+        binding.layoutBmlChannelSelection.visibility = View.GONE
+
+        val pending = pendingTransfer ?: return
+        val sess = sessionFor(pending.src) ?: run {
+            Toast.makeText(ctx, ctx.getString(R.string.transfer_session_unavailable), Toast.LENGTH_SHORT).show()
+            resetOtpState()
+            onStateChanged()
+            return
+        }
+
+        binding.btnTransfer.isEnabled = false
+        host?.setRefreshing(true)
+
+        fragment.viewLifecycleOwner.lifecycleScope.launch {
+            val initiated = withContext(Dispatchers.IO) {
+                try {
+                    BmlTransferClient().initiateTransfer(
+                        sess, pending.debitAccount, pending.creditAccount,
+                        pending.amount, pending.transferType, pending.currency,
+                        pending.bank, channel.channel
+                    )
+                } catch (_: Exception) { false }
+            }
+            host?.setRefreshing(false)
+
+            if (!initiated) {
+                Toast.makeText(ctx, "Failed to initiate transfer — check your session", Toast.LENGTH_SHORT).show()
+                resetOtpState()
+                onStateChanged()
+                return@launch
+            }
+
+            otpState = OtpState.AWAITING_OTP
+            binding.tvBmlOtpSentVia.text = "OTP code sent via: ${channel.description} (${channel.masked})"
+            binding.tvBmlOtpSentVia.visibility = View.VISIBLE
+            binding.tilBmlOtp.visibility = View.VISIBLE
+            binding.etBmlOtp.requestFocus()
+            binding.btnTransfer.text = ctx.getString(R.string.transfer_verify_payment)
+            binding.btnTransfer.isEnabled = true
+        }
+    }
+
+    /** Send-button action while [isAwaitingOtp]: confirms the pending transfer with the typed code. */
+    fun verifyOtp() {
+        val otp = binding.etBmlOtp.text?.toString()?.trim() ?: ""
+        if (otp.isEmpty()) {
+            binding.tilBmlOtp.error = "Enter the verification code"
+            return
+        }
+        binding.tilBmlOtp.error = null
+        val pending = pendingTransfer ?: return
+        val channel = otpChannel ?: return
+        val sess = sessionFor(pending.src) ?: run {
+            Toast.makeText(ctx, ctx.getString(R.string.transfer_session_unavailable), Toast.LENGTH_SHORT).show()
+            return
+        }
+
+        binding.btnTransfer.isEnabled = false
+        host?.setRefreshing(true)
+
+        val capturedToAvatar = pending.toAvatar
+
+        fragment.viewLifecycleOwner.lifecycleScope.launch {
+            val (ok, msg, receipt) = withContext(Dispatchers.IO) {
+                try {
+                    val result = BmlTransferClient().confirmTransfer(
+                        sess, pending.debitAccount, pending.creditAccount,
+                        pending.amount, pending.transferType, pending.currency,
+                        otp, pending.remarks, pending.bank, channel
+                    )
+                    if (result.success) {
+                        val r = TransferReceiptData(
+                            bank         = "BML",
+                            amount       = "%.2f".format(pending.amount),
+                            currency     = pending.currency,
+                            fromLabel    = pending.src.accountBriefName,
+                            fromColorHex = "#0066A1",
+                            toLabel      = pending.destDisplay.ifBlank { pending.destAccount },
+                            toAccount    = pending.destAccount,
+                            toBank       = pending.toBank,
+                            remarks      = pending.remarks,
+                            bmlFromName  = pending.src.accountBriefName,
+                            bmlReference = result.reference,
+                            bmlTimestamp = result.timestamp,
+                            bmlMessage   = result.message
+                        )
+                        Triple(true, "", r)
+                    } else {
+                        Triple(false, result.errorMessage.ifBlank { "Transfer failed" }, null as TransferReceiptData?)
+                    }
+                } catch (e: Exception) {
+                    Triple(false, if (e is java.io.IOException) "CONNECTIVITY" else (e.message ?: "Transfer failed"), null as TransferReceiptData?)
+                }
+            }
+            host?.setRefreshing(false)
+
+            if (ok && receipt != null) {
+                resetOtpState()
+                onTransferSuccess(receipt, capturedToAvatar)
+            } else {
+                binding.btnTransfer.isEnabled = true
+                if (msg == "CONNECTIVITY") {
+                    host?.showConnectivityBanner(ctx.getString(R.string.connectivity_no_internet))
+                } else {
+                    binding.tilBmlOtp.error = msg
+                }
+            }
+        }
+    }
+
+    /** Tears down the OTP UI and re-enables the form. Safe to call when no flow is running. */
+    fun resetOtpState() {
+        otpState = OtpState.NONE
+        otpChannel = null
+        pendingTransfer = null
+        if (fragment.view == null) return
+        binding.layoutBmlChannelSelection.visibility = View.GONE
+        binding.tvBmlOtpSentVia.visibility = View.GONE
+        binding.tilBmlOtp.visibility = View.GONE
+        binding.etBmlOtp.setText("")
+        binding.tilBmlOtp.error = null
+        enableTransferFields()
+        binding.btnTransfer.text = ctx.getString(R.string.transfer)
+    }
+
+    private fun disableTransferFields() {
+        binding.tilAmount.isEnabled = false
+        binding.tilRemarks.isEnabled = false
+        binding.cardFromInfo.alpha = 0.5f
+        binding.btnClearFromInfo.isEnabled = false
+        binding.cardToInfo.alpha = 0.5f
+        binding.btnClearToInfo.isEnabled = false
+    }
+
+    private fun enableTransferFields() {
+        binding.tilAmount.isEnabled = true
+        binding.tilRemarks.isEnabled = true
+        binding.cardFromInfo.alpha = 1f
+        binding.btnClearFromInfo.isEnabled = true
+        binding.cardToInfo.alpha = 1f
+        binding.btnClearToInfo.isEnabled = true
+    }
+
+    // ─── Shared routing ──────────────────────────────────────────────────────
+
+    /**
+     * Picks the BML transfer type and the credit-account identifier the API expects.
+     * Returns null only for the USD → MIB case with no matching saved BML contact, which both
+     * callers report as "BML contact not found".
+     */
+    private fun routeTransfer(
+        destAccount: String,
+        isSrcCard: Boolean,
+        isDestMib: Boolean,
+        currency: String,
+        allAccounts: List<BankAccount>,
+        allContacts: List<BankContact>
+    ): Triple<String, String, String?>? {
+        val isDestMyCard = allAccounts.any { isCard(it) && it.accountNumber == destAccount }
+        return when {
+            isSrcCard -> {
+                // CAD: card → own BML account
+                val destBml = allAccounts.firstOrNull { it.accountNumber == destAccount && it.profileType == "BML" }
+                Triple("CAD", destBml?.internalId?.ifBlank { destAccount } ?: destAccount, null)
+            }
+            isDestMyCard -> {
+                // CPA: BML CASA → own card top-up
+                val card = allAccounts.first { isCard(it) && it.accountNumber == destAccount }
+                Triple("CPA", card.internalId.ifBlank { destAccount }, null)
+            }
+            isDestMib && currency == "MVR" -> Triple("DOT", destAccount, "MIB")
+            isDestMib -> {
+                // USD DOT: requires BML contact numeric ID
+                val contact = allContacts.firstOrNull { it.benefCategoryId == "BML" && it.benefAccount == destAccount }
+                    ?: return null
+                Triple("DOT", contact.benefNo.removePrefix("bml_"), null)
+            }
+            else -> Triple("IAT", destAccount, null)
+        }
+    }
+
+    private fun isCard(account: BankAccount) =
+        account.profileType == "BML_PREPAID" || account.profileType == "BML_CREDIT" || account.profileType == "BML_DEBIT"
+}

app/src/main/java/sh/sar/basedbank/ui/home/transfer/FahipayTransferHandler.kt

@@ -0,0 +1,198 @@
+package sh.sar.basedbank.ui.home.transfer
+
+import android.view.View
+import androidx.lifecycle.lifecycleScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
+import sh.sar.basedbank.R
+import sh.sar.basedbank.api.dhiraagu.DhiraaguClient
+import sh.sar.basedbank.api.fahipay.OoredooClient
+import sh.sar.basedbank.databinding.FragmentTransferBinding
+import sh.sar.basedbank.ui.home.HomeViewModel
+import sh.sar.basedbank.ui.home.TransferFragment
+import sh.sar.basedbank.util.AccountInputParser
+
+/**
+ * A service a Fahipay wallet can pay out to. The carrier lookup decides which of these apply to
+ * a given number; [label] names it in the recipient card, [destinationLabel] in the confirm
+ * dialog's "To" block.
+ *
+ * Wallet-to-wallet Fahipay transfer is not here yet — there is no send path for it (see the
+ * class KDoc on [FahipayTransferHandler]). Add it as a constant once that lands, and the
+ * exhaustive `when`s over this enum will point at every site that needs updating.
+ */
+enum class FahipayService(val label: String, val destinationLabel: String) {
+    RAASTAS("Raastas", "Ooredoo · Raastas"),
+    OOREDOO_BILL("Ooredoo Bill Pay", "Ooredoo · Bill Pay"),
+    DHIRAAGU_RELOAD("Dhiraagu Reload", "Dhiraagu · Reload"),
+    DHIRAAGU_BILL("Dhiraagu Bill Pay", "Dhiraagu · Bill Pay"),
+}
+
+/**
+ * Owns the Fahipay-only parts of the Transfer screen: the carrier lookup that turns a phone
+ * number into a set of payable services, the chip picker shown when more than one applies, and
+ * the selected service that the confirm dialog labels the destination with.
+ *
+ * Mirrors [BmlTransferHandler] / [MfaisaTransferHandler]: the fragment keeps the shared confirm
+ * dialog, the recipient card and the form state; the handler keeps everything Fahipay-specific.
+ *
+ * **There is no send path yet.** A Fahipay source currently falls through to the MIB branch of
+ * `initiateTransfer`, which signs the request with a MIB session. When the real payout API is
+ * wired up it belongs here, as a `doTransfer(...)` alongside the lookup — same shape as the
+ * other handlers.
+ *
+ * Lifetime is bound to the fragment's view: it captures [binding] + [viewModel] + [fragment]
+ * (for `viewLifecycleOwner` and Context) — and must be re-created when the view is recreated.
+ */
+class FahipayTransferHandler(
+    private val fragment: TransferFragment,
+    private val binding: FragmentTransferBinding,
+    private val viewModel: HomeViewModel,
+) {
+
+    private val ctx get() = fragment.requireContext()
+
+    /** The service picked for the current recipient; null until a lookup resolves one. */
+    var service: FahipayService? = null
+        private set
+
+    /** How the confirm dialog names the destination, or "" when nothing is selected. */
+    val destinationLabel: String get() = service?.destinationLabel.orEmpty()
+
+    // ─── Public API the fragment calls ───────────────────────────────────────
+
+    /**
+     * Resolves a destination for a Fahipay source. Only phone numbers are payable, so anything
+     * else is rejected inline on the "To" field.
+     */
+    fun lookupRecipient(rawInput: String) {
+        if (AccountInputParser.detect(rawInput) != AccountInputParser.InputType.PHONE) {
+            binding.tilTo.error = ctx.getString(R.string.transfer_fahipay_phone_only)
+            return
+        }
+        lookupCarrier(rawInput)
+    }
+
+    /** Clears the selected service and hides the chip picker. */
+    fun clearState() {
+        service = null
+        binding.layoutServiceSelector.visibility = View.INVISIBLE
+    }
+
+    // ─── Carrier lookup ──────────────────────────────────────────────────────
+
+    private data class CarrierResult(
+        val dhiraagu: DhiraaguClient.Result,
+        val ooredoo: OoredooClient.CustType
+    )
+
+    private fun lookupCarrier(number: String) {
+        fragment.startLookupLoading()
+        fragment.viewLifecycleOwner.lifecycleScope.launch {
+            val result = withContext(Dispatchers.IO) { queryCarriers(number) }
+            fragment.stopLookupLoading()
+
+            val dhiraaguName = result.dhiraagu.ownerName.takeIf { it.isNotBlank() }
+            val services = servicesFor(result)
+
+            if (services.isEmpty()) return@launch
+
+            // Only one option — auto-select, no chip UI needed
+            if (services.size == 1) {
+                selectService(services[0], number, dhiraaguName)
+                return@launch
+            }
+
+            // Multiple options (Ooredoo HYBRID) — show chips
+            showServiceChips(services, number, dhiraaguName)
+        }
+    }
+
+    /**
+     * Asks the likelier carrier first based on the leading digit and only falls back to the
+     * other when the first says it doesn't know the number. Blocking — call from IO.
+     */
+    private fun queryCarriers(number: String): CarrierResult =
+        if (number.startsWith("7")) {
+            // Dhiraagu first, fall back to Ooredoo
+            val d = dhiraagu(number)
+            val o = if (d.type == DhiraaguClient.CustType.UNSUPPORTED) ooredoo(number)
+                    else OoredooClient.CustType.UNSUPPORTED
+            CarrierResult(d, o)
+        } else {
+            // Ooredoo first, fall back to Dhiraagu
+            val o = ooredoo(number)
+            val d = if (o == OoredooClient.CustType.UNSUPPORTED) dhiraagu(number)
+                    else DhiraaguClient.Result(DhiraaguClient.CustType.UNSUPPORTED)
+            CarrierResult(d, o)
+        }
+
+    private fun dhiraagu(number: String) =
+        try { DhiraaguClient().validateNumber(number) }
+        catch (_: Exception) { DhiraaguClient.Result(DhiraaguClient.CustType.UNSUPPORTED) }
+
+    private fun ooredoo(number: String) =
+        try { OoredooClient().validateNumber(number) }
+        catch (_: Exception) { OoredooClient.CustType.UNSUPPORTED }
+
+    private fun servicesFor(result: CarrierResult): List<FahipayService> = buildList {
+        if (result.dhiraagu.type == DhiraaguClient.CustType.RELOAD)   add(FahipayService.DHIRAAGU_RELOAD)
+        if (result.dhiraagu.type == DhiraaguClient.CustType.BILL_PAY) add(FahipayService.DHIRAAGU_BILL)
+        if (result.ooredoo == OoredooClient.CustType.PRE  || result.ooredoo == OoredooClient.CustType.HYBRID) add(FahipayService.RAASTAS)
+        if (result.ooredoo == OoredooClient.CustType.POST || result.ooredoo == OoredooClient.CustType.HYBRID) add(FahipayService.OOREDOO_BILL)
+    }
+
+    // ─── Service picker ──────────────────────────────────────────────────────
+
+    private fun showServiceChips(
+        services: List<FahipayService>,
+        number: String,
+        dhiraaguName: String?
+    ) {
+        binding.chipDhiraaguReload.visibility = visibilityFor(FahipayService.DHIRAAGU_RELOAD in services)
+        binding.chipDhiraaguBill.visibility   = visibilityFor(FahipayService.DHIRAAGU_BILL   in services)
+        binding.chipRaastas.visibility        = visibilityFor(FahipayService.RAASTAS         in services)
+        binding.chipOoredooBill.visibility    = visibilityFor(FahipayService.OOREDOO_BILL    in services)
+        binding.layoutServiceSelector.visibility = View.VISIBLE
+        binding.chipGroupService.clearCheck()
+
+        // Dhiraagu is the only carrier that hands back an owner name, so the Ooredoo chips
+        // resolve their display name from saved contacts instead.
+        bindChip(binding.chipDhiraaguReload, FahipayService.DHIRAAGU_RELOAD, number, dhiraaguName)
+        bindChip(binding.chipDhiraaguBill,   FahipayService.DHIRAAGU_BILL,   number, dhiraaguName)
+        bindChip(binding.chipRaastas,        FahipayService.RAASTAS,         number, null)
+        bindChip(binding.chipOoredooBill,    FahipayService.OOREDOO_BILL,    number, null)
+    }
+
+    private fun bindChip(
+        chip: com.google.android.material.chip.Chip,
+        picked: FahipayService,
+        number: String,
+        ownerName: String?
+    ) {
+        chip.setOnCheckedChangeListener { _, checked ->
+            if (checked) {
+                selectService(picked, number, ownerName)
+                binding.layoutServiceSelector.visibility = View.INVISIBLE
+            }
+        }
+    }
+
+    private fun visibilityFor(shown: Boolean) = if (shown) View.VISIBLE else View.GONE
+
+    private fun selectService(picked: FahipayService, number: String, ownerName: String?) {
+        service = picked
+        val contacts = viewModel.contacts.value ?: emptyList()
+        val displayName = ownerName
+            ?: contacts.firstOrNull { it.benefAccount == number }?.benefNickName
+            ?: number
+        fragment.prefillToDirectly(
+            accountNumber = number,
+            displayName   = displayName,
+            subtitle      = "${picked.label} · $number",
+            colorHex      = "#FF6B00",
+            imageHash     = null
+        )
+    }
+}

app/src/main/java/sh/sar/basedbank/ui/home/transfer/MfaisaTransferHandler.kt

@@ -8,6 +8,7 @@ import android.view.View
 import android.widget.LinearLayout
 import android.widget.TextView
 import android.widget.Toast
+import androidx.appcompat.app.AlertDialog
 import androidx.biometric.BiometricManager
 import androidx.biometric.BiometricPrompt
 import androidx.core.content.ContextCompat
@@ -22,6 +23,7 @@ import kotlinx.coroutines.withContext
 import sh.sar.basedbank.BasedBankApp
 import sh.sar.basedbank.R
 import sh.sar.basedbank.api.mfaisa.MfaisaInvalidOtpException
+import sh.sar.basedbank.api.mfaisa.MfaisaQrPayClient
 import sh.sar.basedbank.api.mfaisa.MfaisaRecipientNotFoundException
 import sh.sar.basedbank.api.mfaisa.MfaisaSessionExpiredException
 import sh.sar.basedbank.api.mfaisa.MfaisaTransferClient
@@ -37,16 +39,25 @@ import sh.sar.basedbank.util.RecentsCache
 
 /**
  * Owns the M-Faisa-only parts of the Transfer screen: phone-based recipient lookup,
- * initiate-with-OTP, and confirm-with-OTP. Lives alongside [sh.sar.basedbank.ui.home.TransferFragment]
+ * initiate-with-OTP and confirm-with-OTP for wallet transfers, plus merchant QR pay
- * which dispatches to it whenever [BankAccount.bank] == "MFAISA" is the selected source.
+ * (qrCodeId lookup + initiate/confirm purchase). Lives alongside [TransferFragment] which
+ * dispatches to it whenever [BankAccount.bank] == "MFAISA" is the selected source, or whenever
+ * an M-Faisa merchant QR is loaded.
+ *
+ * Mirrors [BmlTransferHandler]: the fragment keeps the shared confirm dialog, the recipient card
+ * and the form state; the handler keeps everything M-Faisa-specific.
  *
  * Lifetime is bound to the fragment's view: it captures [binding] + [viewModel] + [fragment] (for
  * [Fragment.viewLifecycleOwner] and Context) — and must be re-created when the view is recreated.
  */
 class MfaisaTransferHandler(
-    private val fragment: Fragment,
+    private val fragment: TransferFragment,
     private val binding: FragmentTransferBinding,
     private val viewModel: HomeViewModel,
+    /** Reads the fragment's currently-selected source account. */
+    private val currentSource: () -> BankAccount?,
+    /** Asks the fragment to make [BankAccount] the source (amount prefix + from-card + Send state). */
+    private val selectSource: (BankAccount) -> Unit,
     /** Hook called when M-Faisa successfully resolves or clears a recipient — fragment uses this to update Send-button state. */
     private val onRecipientChanged: () -> Unit,
     /** Hook called on a successful transfer; fragment navigates to the receipt and refreshes account balances. */
@@ -55,11 +66,16 @@ class MfaisaTransferHandler(
 
     private val app get() = fragment.requireActivity().application as BasedBankApp
     private val ctx get() = fragment.requireContext()
+    private val host get() = fragment.activity as? HomeActivity
 
     /** Set to the resolved recipient after a successful search; null otherwise. */
     var recipient: MfaisaTransferClient.Recipient? = null
         private set
 
+    /** Merchant QR payment mode (set when the scanned QR is an M-Faisa qrCodeId). */
+    var qrInfo: MfaisaQrPayClient.QrMerchant? = null
+        private set
+
     private var lookupInFlight = false
 
     // ─── Public API the fragment calls ───────────────────────────────────────
@@ -80,7 +96,7 @@ class MfaisaTransferHandler(
         }
         binding.tilTo.error = null
 
-        val source = currentSource() ?: return
+        val source = mfaisaSource() ?: return
         val session = app.mfaisaSessionFor(source) ?: run {
             Toast.makeText(ctx, R.string.transfer_session_unavailable, Toast.LENGTH_SHORT).show()
             return
@@ -122,7 +138,7 @@ class MfaisaTransferHandler(
 
     /** Triggered when the user taps the Send button (and source bank is MFAISA). */
     fun submit() {
-        val source = currentSource() ?: return
+        val source = mfaisaSource() ?: return
         val r = recipient ?: run {
             Toast.makeText(ctx, "Search for a recipient first", Toast.LENGTH_SHORT).show()
             return
@@ -153,20 +169,232 @@ class MfaisaTransferHandler(
         }
     }
 
+    /** Whether a merchant QR is loaded — counts as a resolved recipient for the Send button. */
+    val hasQrMerchant: Boolean get() = qrInfo != null
+
     /** Called when the source account changes away from M-Faisa (or the view tears down). */
     fun clearState() {
         recipient = null
         lookupInFlight = false
     }
 
+    /** Drops the loaded merchant and unlocks the amount/remarks fields the QR mode had frozen. */
+    fun clearQrMerchant() {
+        if (qrInfo == null) return
+        qrInfo = null
+        binding.tilAmount.isEnabled = true
+        binding.tilRemarks.isEnabled = true
+        binding.tilRemarks.alpha = 1f
+        binding.etAmount.setText("")
+    }
+
+    // ─── Merchant QR ─────────────────────────────────────────────────────────
+
+    /**
+     * Resolves an M-Faisa qrCodeId to a merchant, paints it in the "To" card, auto-selects an
+     * M-Faisa source if none is selected (or the current one is the wrong bank), and pre-fills
+     * the amount if the QR is dynamic.
+     */
+    fun lookupQrMerchant(qrCodeId: String) {
+        val source = mfaisaSource() ?: run {
+            Toast.makeText(ctx, "No M-Faisa account available", Toast.LENGTH_SHORT).show()
+            return
+        }
+        val session = app.mfaisaSessionFor(source) ?: run {
+            Toast.makeText(ctx, R.string.transfer_session_unavailable, Toast.LENGTH_SHORT).show()
+            return
+        }
+
+        // Auto-switch from a non-MFAISA source so the user doesn't have to fix it manually
+        if (currentSource()?.bank != "MFAISA") selectSource(source)
+
+        // Lock the "To" input row while loading
+        binding.tilTo.visibility = View.GONE
+        binding.btnPickContact.visibility = View.GONE
+        binding.btnScanQr.visibility = View.GONE
+        host?.setRefreshing(true)
+
+        fragment.viewLifecycleOwner.lifecycleScope.launch {
+            val merchant = withContext(Dispatchers.IO) {
+                try {
+                    MfaisaQrPayClient().fetchQrDetails(session, qrCodeId)
+                } catch (_: MfaisaSessionExpiredException) {
+                    val fresh = app.refreshMfaisaSession(source.loginTag.removePrefix("mfaisa_"))
+                        ?: return@withContext null
+                    try { MfaisaQrPayClient().fetchQrDetails(fresh, qrCodeId) }
+                    catch (_: Exception) { null }
+                } catch (_: Exception) { null }
+            }
+            host?.setRefreshing(false)
+            if (merchant == null) {
+                Toast.makeText(ctx, "Could not look up M-Faisa QR", Toast.LENGTH_LONG).show()
+                fragment.resetToFieldVisibility()
+                return@launch
+            }
+            qrInfo = merchant
+
+            // Static QRs (no preset amount) make sense to keep in Recents — the merchant is
+            // reusable. Dynamic QRs are one-off so we skip them, same rule as BML QR pay.
+            if (merchant.txnAmount.isNullOrBlank()) {
+                RecentsCache.save(ctx, RecentPick(
+                    accountNumber = "mfaisaqr:${merchant.qrCodeId}",
+                    displayName   = merchant.merchantName,
+                    subtitle      = "M-Faisa merchant · ${merchant.merchantMsisdn}",
+                    colorHex      = "#ED1C24",
+                    imageHash     = null,
+                    isProfileImage = false,
+                    bank          = "MFAISA"
+                ))
+            }
+
+            // Show merchant in the "To" card — clear button is the only way to back out
+            binding.tvToAccountName.text = merchant.merchantName
+            binding.tvToBankBic.text = "M-Faisa merchant · ${merchant.merchantMsisdn}"
+            binding.tvToAccountDetails.visibility = View.GONE
+            binding.tvToBalance.visibility = View.GONE
+            binding.ivToPhoto.scaleType = android.widget.ImageView.ScaleType.FIT_CENTER
+            binding.ivToPhoto.setImageResource(R.drawable.ooredoo_logo)
+            binding.cardToInfo.visibility = View.VISIBLE
+
+            // Pre-fill + lock amount if the QR is dynamic
+            val dynamicAmount = merchant.txnAmount?.toDoubleOrNull()
+            if (dynamicAmount != null && dynamicAmount > 0.0) {
+                binding.etAmount.setText("%.2f".format(dynamicAmount))
+                binding.tilAmount.isEnabled = false
+            }
+
+            onRecipientChanged()
+        }
+    }
+
+    /**
+     * Confirm-then-pay for a loaded merchant QR. Uses the fragment's shared confirm dialog —
+     * the /initiateNewBuy + /confirmNewBuy pair does NOT require OTP for wallet QR pay
+     * (2FARequired=NONE), so unlike [submit] there is no code to enter.
+     */
+    fun submitQrPayment() {
+        val merchant = qrInfo ?: return
+        val src = currentSource() ?: run {
+            Toast.makeText(ctx, R.string.transfer_session_unavailable, Toast.LENGTH_SHORT).show()
+            return
+        }
+        if (src.bank != "MFAISA") {
+            Toast.makeText(ctx, "Switch to an M-Faisa account to pay this QR", Toast.LENGTH_SHORT).show()
+            return
+        }
+        val amountStr = binding.etAmount.text?.toString()?.trim() ?: ""
+        val amount = amountStr.toDoubleOrNull()
+        if (amount == null || amount <= 0) { binding.tilAmount.error = "Enter a valid amount"; return }
+        binding.tilAmount.error = null
+        val remarks = binding.etRemarks.text?.toString()?.trim().orEmpty()
+        val amountValue = "%.2f".format(amount)
+
+        val confirmView = fragment.buildTransferConfirmView(
+            amountCurrency = merchant.currencyCode,
+            amountValue = amountValue,
+            fromName = src.accountBriefName,
+            fromNumber = src.accountNumber,
+            fromDetail = "M-Faisa",
+            toName = merchant.merchantName,
+            toNumber = merchant.merchantMsisdn,
+            toDetail = "Ooredoo M-Faisa merchant"
+        )
+        fragment.showConfirmWithBiometric(
+            title = ctx.getString(R.string.transfer),
+            customView = confirmView,
+            biometricSubtitle = "${merchant.currencyCode} $amountValue → ${merchant.merchantName}",
+            onConfirmed = { dialog, frame ->
+                fragment.showProcessingInDialog(dialog, frame)
+                executeQrPayment(src, merchant, amountValue, remarks, dialog)
+            }
+        )
+    }
+
+    private fun executeQrPayment(
+        src: BankAccount,
+        merchant: MfaisaQrPayClient.QrMerchant,
+        amountStr: String,
+        remarks: String,
+        dialog: AlertDialog
+    ) {
+        val loginId = src.loginTag.removePrefix("mfaisa_")
+        val initialSession = app.mfaisaSessionFor(src) ?: run {
+            dialog.dismiss()
+            Toast.makeText(ctx, R.string.transfer_session_unavailable, Toast.LENGTH_SHORT).show()
+            return
+        }
+        // M-Faisa expects the user's MSISDN with the "960" country prefix (the session stores the
+        // bare 7-digit form). The pocket itself is identified by [BankAccount.accountNumber].
+        val sourceMdn = "960${initialSession.msisdn}"
+
+        binding.btnTransfer.isEnabled = false
+
+        fragment.viewLifecycleOwner.lifecycleScope.launch {
+            val outcome = withContext(Dispatchers.IO) {
+                val client = MfaisaQrPayClient()
+                try {
+                    val refId = try {
+                        client.initiatePurchase(initialSession, src.accountNumber, sourceMdn, merchant, amountStr, remarks)
+                    } catch (_: MfaisaSessionExpiredException) {
+                        val fresh = app.refreshMfaisaSession(loginId)
+                            ?: throw IllegalStateException("Could not refresh M-Faisa session")
+                        client.initiatePurchase(fresh, src.accountNumber, "960${fresh.msisdn}", merchant, amountStr, remarks)
+                    }
+                    val confirmSession = app.mfaisaSessionFor(src) ?: initialSession
+                    try {
+                        client.confirmPurchase(confirmSession, refId)
+                    } catch (_: MfaisaSessionExpiredException) {
+                        val fresh = app.refreshMfaisaSession(loginId)
+                            ?: throw IllegalStateException("Could not refresh M-Faisa session")
+                        client.confirmPurchase(fresh, refId)
+                    }
+                    Result.success(refId)
+                } catch (e: Exception) {
+                    Result.failure<String>(e)
+                }
+            }
+            if (fragment.view == null) return@launch
+
+            outcome.fold(
+                onSuccess = { _ ->
+                    val receipt = TransferReceiptData(
+                        bank         = "MFAISA",
+                        amount       = amountStr,
+                        currency     = merchant.currencyCode,
+                        fromLabel    = src.accountBriefName,
+                        fromColorHex = "#ED1C24",
+                        toLabel      = merchant.merchantName,
+                        toAccount    = merchant.merchantMsisdn,
+                        toBank       = "Ooredoo M-Faisa",
+                        remarks      = remarks,
+                        mfaisaTransactionType = "Merchant payment",
+                        mfaisaFromName        = src.accountBriefName,
+                        mfaisaFromMsisdn      = src.accountNumber,
+                        mfaisaToMsisdn        = merchant.merchantMsisdn,
+                        mfaisaTimestamp       = System.currentTimeMillis()
+                    )
+                    dialog.dismiss()
+                    onTransferSuccess(receipt, null)
+                },
+                onFailure = { e ->
+                    dialog.dismiss()
+                    binding.btnTransfer.isEnabled = true
+                    showError(e, fallback = "Payment failed")
+                }
+            )
+        }
+    }
+
     // ─── Internal ────────────────────────────────────────────────────────────
 
-    private fun currentSource(): BankAccount? =
+    /**
-        viewModel.accounts.value?.firstOrNull { it.bank == "MFAISA" && it.accountNumber == sourceAccountNumberFromCard() }
+     * The M-Faisa account to act on: the selected source when it is one, otherwise the first
-            ?: viewModel.accounts.value?.firstOrNull { it.bank == "MFAISA" }  // fallback if from-card field isn't easily readable
+     * M-Faisa account available. The fallback is what lets a scanned merchant QR auto-switch
-
+     * the source away from another bank.
-    private fun sourceAccountNumberFromCard(): String =
+     */
-        binding.tvFromAccountNumber.text?.toString().orEmpty()
+    private fun mfaisaSource(): BankAccount? =
+        currentSource()?.takeIf { it.bank == "MFAISA" }
+            ?: viewModel.accounts.value?.firstOrNull { it.bank == "MFAISA" }
 
     private fun showResolvedRecipient(r: MfaisaTransferClient.Recipient) {
         // Reuse the same recipient card the fragment uses for other banks. The fragment owns the
@@ -241,7 +469,6 @@ class MfaisaTransferHandler(
         refId: String,
         errorMsg: String?
     ) {
-        val tf = fragment as? TransferFragment ?: return
         val view = fragment.view ?: return
         val dp = ctx.resources.displayMetrics.density
         val colorMuted = MaterialColors.getColor(
@@ -250,7 +477,7 @@ class MfaisaTransferHandler(
             view, com.google.android.material.R.attr.colorOutlineVariant, Color.LTGRAY)
 
         val amountValue = try { "%.2f".format(amountStr.toDouble()) } catch (_: Exception) { amountStr }
-        val confirmView = tf.buildTransferConfirmView(
+        val confirmView = fragment.buildTransferConfirmView(
             amountCurrency = "MVR",
             amountValue    = amountValue,
             fromName       = source.accountBriefName,
@@ -415,11 +642,11 @@ class MfaisaTransferHandler(
         }
     }
 
-    private fun showError(e: Exception) {
+    private fun showError(e: Throwable, fallback: String = "Transfer failed") {
         val msg = when {
             e is java.io.IOException -> ctx.getString(R.string.connectivity_no_internet)
             !e.message.isNullOrBlank() -> e.message!!
-            else -> "Transfer failed"
+            else -> fallback
         }
         Toast.makeText(ctx, msg, Toast.LENGTH_LONG).show()
     }

app/src/main/java/sh/sar/basedbank/ui/home/transfer/MibTransferHandler.kt

@@ -0,0 +1,173 @@
+package sh.sar.basedbank.ui.home.transfer
+
+import android.graphics.Bitmap
+import android.graphics.BitmapFactory
+import android.util.Base64
+import androidx.fragment.app.Fragment
+import sh.sar.basedbank.BasedBankApp
+import sh.sar.basedbank.R
+import sh.sar.basedbank.api.mib.MibContactsClient
+import sh.sar.basedbank.api.mib.MibIpsAccountInfo
+import sh.sar.basedbank.api.mib.MibLookupException
+import sh.sar.basedbank.api.mib.MibSession
+import sh.sar.basedbank.api.mib.MibTransferClient
+import sh.sar.basedbank.api.models.BankAccount
+import sh.sar.basedbank.ui.home.TransferReceiptData
+import sh.sar.basedbank.util.AccountInputParser
+import sh.sar.basedbank.util.CredentialStore
+import sh.sar.basedbank.util.Totp
+
+/**
+ * Owns the MIB-only parts of the Transfer screen: session resolution, IPS destination lookup,
+ * the transfer itself (profile switch + TOTP + `MibTransferClient`), and the profile/contact
+ * avatar API that every bank's "To" card borrows.
+ *
+ * Unlike [BmlTransferHandler] and [MfaisaTransferHandler] this one holds no view binding and
+ * paints nothing — every method is either a session accessor or a blocking API call meant for
+ * `Dispatchers.IO`. [sh.sar.basedbank.ui.home.TransferFragment] keeps the coroutine plumbing and
+ * the view updates, so this handler can outlive a view recreation.
+ */
+class MibTransferHandler(
+    private val fragment: Fragment,
+    /** Reads the fragment's currently-selected source account. */
+    private val currentSource: () -> BankAccount?,
+) {
+
+    private val app get() = fragment.requireActivity().application as BasedBankApp
+    private val ctx get() = fragment.requireContext()
+
+    /** The selected source's MIB session, falling back to any logged-in MIB session. */
+    val session: MibSession?
+        get() = currentSource()?.let { app.mibSessionFor(it) } ?: app.anyMibSession()
+
+    /** Any logged-in MIB session, ignoring which source is selected. */
+    val anySession: MibSession? get() = app.anyMibSession()
+
+    // ─── Destination lookup ──────────────────────────────────────────────────
+
+    /** Either a resolved destination or the message to show the user — never both. */
+    data class LookupOutcome(val info: MibIpsAccountInfo?, val error: String?)
+
+    /**
+     * IPS lookup for a destination account/alias. Blocking — call from IO.
+     * A missing MIB session is reported as "account not found", same as a failed lookup.
+     */
+    fun lookupDestination(accountNumber: String): LookupOutcome {
+        val sess = session ?: return LookupOutcome(null, notFound())
+        return try {
+            LookupOutcome(MibTransferClient().lookup(sess, accountNumber), null)
+        } catch (e: MibLookupException) {
+            LookupOutcome(null, e.message)
+        } catch (_: Exception) {
+            LookupOutcome(null, notFound())
+        }
+    }
+
+    /**
+     * Currency-only lookup, used to enrich a BML "verify MIB account" result — that endpoint
+     * resolves the name but not the currency. Blocking; returns "" when it can't be determined.
+     */
+    fun lookupCurrency(accountNumber: String): String {
+        val sess = session ?: return ""
+        return try { MibTransferClient().lookup(sess, accountNumber).currency }
+        catch (_: Exception) { "" }
+    }
+
+    private fun notFound() = ctx.getString(R.string.transfer_account_not_found)
+
+    // ─── Avatars ─────────────────────────────────────────────────────────────
+
+    /**
+     * Fetches and decodes a profile image (P41, [isProfile] true) or a saved contact's image.
+     * Blocking — call from IO. Returns null on any failure, including a missing image.
+     *
+     * The session is passed in rather than read from [session] because callers differ: the "To"
+     * card uses the selected source's session, the account dropdown uses [anySession].
+     */
+    fun fetchAvatar(session: MibSession, hash: String, isProfile: Boolean): Bitmap? = try {
+        val base64 = if (isProfile) {
+            app.anyMibFlow()?.fetchProfileImage(session, hash)
+        } else {
+            MibContactsClient().fetchProfileImageBase64(session, hash)
+        }
+        if (base64 == null) null else {
+            val bytes = Base64.decode(base64, Base64.DEFAULT)
+            BitmapFactory.decodeByteArray(bytes, 0, bytes.size)
+        }
+    } catch (_: Exception) { null }
+
+    // ─── Transfer ────────────────────────────────────────────────────────────
+
+    /**
+     * Switches to the profile that owns [src], then runs the transfer with a freshly generated
+     * TOTP. Blocking — call from IO. Returns `(ok, message, receipt)`; the message is
+     * "CONNECTIVITY" when the network was unreachable.
+     */
+    fun doTransfer(
+        src: BankAccount,
+        destAccount: String,
+        destName: String,
+        destDisplay: String,
+        amount: String,
+        remarks: String,
+        bankName: String
+    ): Triple<Boolean, String, TransferReceiptData?> {
+        val sess = session ?: return Triple(false, ctx.getString(R.string.transfer_session_unavailable), null)
+        val loginId = src.loginTag.removePrefix("mib_")
+        val otp = CredentialStore(ctx).loadMibCredentials(loginId)?.otpSeed
+            ?.let { Totp.generate(it) }
+            ?: return Triple(false, "OTP unavailable", null)
+        val currencyCode = if (src.currencyName == "USD") "840" else "462"
+        val currency = if (src.currencyName == "USD") "USD" else "MVR"
+        val isDestMib = AccountInputParser.detect(destAccount) == AccountInputParser.InputType.MIB_ACCOUNT
+        val bankNo = if (isDestMib) 2 else 3
+        val toBank = when {
+            isDestMib -> "MIB"
+            else -> when (bankName.uppercase()) {
+                "MALBMVMV" -> "BML"
+                "MADVMVMV" -> "MIB"
+                else -> bankName.ifBlank { "LOCAL" }
+            }
+        }
+        return try {
+            // Switch to the profile that owns the source account
+            if (src.profileId.isNotBlank()) {
+                val profiles = app.mibProfilesMap[loginId] ?: emptyList()
+                val profile = profiles.firstOrNull { it.profileId == src.profileId }
+                if (profile != null) app.mibFlowFor(loginId).switchProfile(sess, profile)
+            }
+            val result = MibTransferClient().transfer(
+                session = sess,
+                fromAccount = src.accountNumber,
+                toAccount = destAccount,
+                amount = amount,
+                currencyCode = currencyCode,
+                benefName = destName.ifBlank { "Recipient" },
+                bankNo = bankNo,
+                purpose = remarks,
+                otp = otp
+            )
+            if (result.success) {
+                val receipt = TransferReceiptData(
+                    bank = "MIB",
+                    amount = "%.2f".format(amount.toDoubleOrNull() ?: 0.0),
+                    currency = currency,
+                    fromLabel = src.accountBriefName,
+                    fromColorHex = "#FE860E",
+                    fromProfileImageHash = src.profileImageHash,
+                    toLabel = destDisplay.ifBlank { destName },
+                    toAccount = destAccount,
+                    toBank = toBank,
+                    remarks = remarks,
+                    mibReferenceNo = result.trxId,
+                    mibTransactionDate = result.date
+                )
+                Triple(true, "BankTransaction ID: ${result.trxId}\n${result.date}", receipt)
+            } else {
+                Triple(false, result.errorMessage.ifBlank { "Transfer failed" }, null)
+            }
+        } catch (e: Exception) {
+            Triple(false, if (e is java.io.IOException) "CONNECTIVITY" else (e.message ?: "Transfer failed"), null)
+        }
+    }
+}

app/src/main/java/sh/sar/basedbank/util/bmlapi/BmlCardParser.kt

@@ -36,9 +36,9 @@ object BmlCardParser {
         "C8902", "C8907", "C8909", "C8912", "C8992", "C8996", "C8997", "C8982", "C8983" -> "cards/bml/master_islamic.png"
         "C8101" -> "cards/bml/master_masveriyaa.png"
         "C8102" -> "cards/bml/master_odiveriyaa.png"
-        "C8010", "C8011" -> "cards/bml/master_platinum.png"
+        "C8010", "C8011", "C8033" -> "cards/bml/master_platinum.png"
         "C8040", "C8044" -> "cards/bml/master_world.png"
-        "C8030", "C8033" -> "cards/bml/master_business_debit.png"
+        "C8030" -> "cards/bml/master_business_debit.png"
         "C8901", "C8991", "C8980", "C8981" -> "cards/bml/master_passport.png"
         "C1090", "C1130", "C1033", "C1133" -> "cards/bml/visa_corporate.png"
         "C8905", "C8995" -> "cards/bml/visa_credit.png"

app/src/main/res/layout/fragment_receipt_bml.xml

@@ -246,18 +246,10 @@
             android:layout_width="0dp"
             android:layout_height="wrap_content"
             android:layout_weight="1"
-            android:layout_marginHorizontal="4dp"
+            android:layout_marginStart="4dp"
             android:text="Save"
             app:icon="@drawable/ic_save" />
 
-        <com.google.android.material.button.MaterialButton
-            android:id="@+id/btnDone"
-            android:layout_width="0dp"
-            android:layout_height="wrap_content"
-            android:layout_weight="1"
-            android:layout_marginStart="4dp"
-            android:text="Done" />
-
     </LinearLayout>
 
 </LinearLayout>

app/src/main/res/layout/fragment_receipt_mfaisa.xml

@@ -376,18 +376,10 @@
             android:layout_width="0dp"
             android:layout_height="wrap_content"
             android:layout_weight="1"
-            android:layout_marginHorizontal="4dp"
+            android:layout_marginStart="4dp"
             android:text="Save"
             app:icon="@drawable/ic_save" />
 
-        <com.google.android.material.button.MaterialButton
-            android:id="@+id/btnDone"
-            android:layout_width="0dp"
-            android:layout_height="wrap_content"
-            android:layout_weight="1"
-            android:layout_marginStart="4dp"
-            android:text="Done" />
-
     </LinearLayout>
 
 </LinearLayout>

app/src/main/res/layout/fragment_receipt_mib.xml

@@ -273,18 +273,10 @@
             android:layout_width="0dp"
             android:layout_height="wrap_content"
             android:layout_weight="1"
-            android:layout_marginHorizontal="4dp"
+            android:layout_marginStart="4dp"
             android:text="Save"
             app:icon="@drawable/ic_save" />
 
-        <com.google.android.material.button.MaterialButton
-            android:id="@+id/btnDone"
-            android:layout_width="0dp"
-            android:layout_height="wrap_content"
-            android:layout_weight="1"
-            android:layout_marginStart="4dp"
-            android:text="Done" />
-
     </LinearLayout>
 
 </LinearLayout>

docs/bmlapi/04-dashboard.md

@@ -190,9 +190,9 @@ Known asset mappings:
 |---|---|---|
 | `C8201`, `C8001`, `C8009` | Mastercard Prepaid | `master_prepaid` |
 | `C8205`, `C8005`, `C8008` | Mastercard Prepaid Travel | `master_prepaid_travel` |
-| `C8010`, `C8011` | Mastercard Platinum | `master_platinum` |
+| `C8010`, `C8011`, `C8033` | Mastercard Platinum | `master_platinum` |
 | `C8020`, `C8022` | Mastercard Gold | `master_gold` |
-| `C8030`, `C8033` | Mastercard Business Debit | `master_business_debit` |
+| `C8030` | Mastercard Business Debit | `master_business_debit` |
 | `C8040`, `C8044` | Mastercard World | `master_world` |
 | `C8101` | Mastercard Masveriyaa | `master_masveriyaa` |
 | `C8102` | Mastercard Odiveriyaa | `master_odiveriyaa` |

docs/mfaisaapi/04-transfer.md

@@ -279,4 +279,4 @@ python tmp/mfaisa_transfer.py <myMsisdn> <myMpin> <recipientMsisdn>
 
 ---
 
-> **← Back to** [Transaction History](03-history.md) | [README](README.md)
+> **← Back to** [Transaction History](03-history.md) | [README](README.md) | **Next →** [QR Merchant Payment](05-qr-pay.md)

docs/mfaisaapi/05-qr-pay.md

@@ -0,0 +1,265 @@
+# QR Merchant Payment ("Smart Pay")
+
+Pay an Ooredoo M-Faisa merchant by scanning their QR. The QR encodes only a numeric `qrCodeId` (e.g. `1594103440350`) — no URL, no EMV TLV envelope. The flow is three calls and **does not require OTP** (`2FARequired=NONE`).
+
+> **Currency / pocket constraints:** captures cover MVR→MVR purchases from the user's EMONEY pocket only. The `transactionCurrency` field is taken from the QR lookup; we have not seen a non-MVR variant.
+
+---
+
+## Flow
+
+```
+Client                                            Server
+  |                                                 |
+  |  POST /QRCodeUtility/fetchQRCodeById            |   ← user scanned a QR
+  |  formData = { qrCodeId, tenantCode }            |
+  |------------------------------------------------>|
+  |  [{ success, response:[{ commercialName,        |
+  |       customerId, mobileNumber, currencyCode,   |
+  |       txnAmount, status, ... }] }]              |
+  |<------------------------------------------------|
+  |                                                 |
+  |   (show merchant, accept amount + remarks)
+  |                                                 |
+  |  POST /initiateNewBuy                           |
+  |  formData = { merchantId, mobileNumber,         |
+  |               sourceDetails, transactionAmount, |
+  |               transactionType:"PURCHASE", … }   |
+  |------------------------------------------------>|
+  |  [{ 2FARequired:"NONE",                         |
+  |     authenticationType:"NONE",                  |
+  |     success:true,                               |
+  |     response:[{ responseObject:{ referenceId,   |
+  |       chargeDetails, … } }] }]                  |
+  |<------------------------------------------------|
+  |                                                 |
+  |   (no OTP — go straight to confirm)
+  |                                                 |
+  |  POST /confirmNewBuy                            |
+  |  formData = { referenceId }                     |
+  |  transactionAuthDetails = "null"   ← literal    |
+  |------------------------------------------------>|
+  |  [{ success:true,                               |
+  |     message:"Payment Completed Successfully",   |
+  |     response:[{ responseObject:{ isCompleted,   |
+  |       balanceInquiryDTO, ... } }] }]            |
+  |<------------------------------------------------|
+```
+
+All three endpoints carry the standard anti-replay pair (`rndValue` + `csValue`) derived from each request's `formData` JSON — see [01-encryption.md → rndValue / csValue](01-encryption.md#anti-replay-envelope-rndvalue--csvalue).
+
+Unlike the transfer flow, **every endpoint here returns its envelope as a JSON array** `[{...}]` for both success and error.
+
+---
+
+## Step 1: `QRCodeUtility/fetchQRCodeById` — resolve merchant
+
+### Endpoint
+
+```
+POST https://superapp.ooredoo.mv/api/mfaisaa-bff/mfino/v1.1/web/QRCodeUtility/fetchQRCodeById
+```
+
+### Request
+
+**Content-Type:** `application/x-www-form-urlencoded`
+
+| Field | Value |
+|---|---|
+| `role` | **`R01`** (the other two endpoints use `RETAIL_SUBSCRIBER` — this one does not) |
+| `channel` | `C03` |
+| `loginExchangeKey` | From login |
+| `rndValue` / `csValue` | [Standard anti-replay](01-encryption.md#anti-replay-envelope-rndvalue--csvalue) |
+| `formData` | JSON below ([html-safe `=` escaping](01-encryption.md#html-safe-gson--escape)) |
+
+```json
+{
+  "qrCodeId":   "<numeric id from QR>",
+  "tenantCode": "ooredoo"
+}
+```
+
+### Response — happy path
+
+```json
+[
+  {
+    "success": true,
+    "message": "QRCode fetched Successfully.",
+    "response": [
+      {
+        "mobileNumber":   "9609569506",         /* merchant's '960' + msisdn */
+        "customerId":     "72518",              /* used as merchantId in step 2 */
+        "commercialName": "Family Room",        /* merchant display name */
+        "qrCodeId":       "1594103440350",
+        "qrImageString":  "<base64 PNG>",       /* unused */
+        "accountNumber":  null,
+        "txnAmount":      null,                 /* static QR; dynamic QRs put a number here */
+        "currencyCode":   "MVR",
+        "status":         "Active",
+        "role":           "AGENT",
+        "tenantCode":     "ooredoo",
+        "...":            "..."
+      }
+    ]
+  }
+]
+```
+
+`accountNumber` / `txnAmount` are JSON `null` for **static QRs** (the user chooses the amount). For **dynamic QRs** the server returns the fixed amount in `txnAmount` and the client should lock the amount field.
+
+The `mobileNumber` field already includes the `960` country prefix.
+
+### Response — QR not found / inactive
+
+```json
+[{ "success": false, "message": "QRCode not found." }]
+```
+
+The client also rejects entries with `status != "Active"`.
+
+---
+
+## Step 2: `initiateNewBuy` — initiate purchase (no OTP triggered)
+
+### Endpoint
+
+```
+POST https://superapp.ooredoo.mv/api/mfaisaa-bff/mfino/v1.1/web/initiateNewBuy
+```
+
+### Request
+
+**Content-Type:** `application/x-www-form-urlencoded`
+
+| Field | Value |
+|---|---|
+| `role` | `RETAIL_SUBSCRIBER` |
+| `channel` | `C03` (top-level differs from inner `formData.channel`, which is `SubscriberApp`) |
+| `loginExchangeKey` | From login |
+| `rndValue` / `csValue` | Standard anti-replay (derived from the `formData` below) |
+| `formData` | JSON below |
+
+```json
+{
+  "channel":             "SubscriberApp",
+  "commodityType":       "WALLET",
+  "description":         "<remarks>",            /* free text, may be empty */
+  "merchantId":          "<customerId from step 1>",
+  "mobileNumber":        "<merchant '960' msisdn from step 1>",
+  "sourceDetails": {
+    "MDNId":         "960<myMsisdn>",            /* PLAINTEXT — '960' + my phone */
+    "actorRoleType": "RETAIL_SUBSCRIBER",
+    "pocketId":      "<my source pocket id>"     /* EMONEY pocket from login */
+  },
+  "transactionAmount":   "<amount>",             /* string, e.g. "7.56" */
+  "transactionCurrency": "MVR",
+  "transactionType":     "PURCHASE"
+}
+```
+
+Unlike the transfer flow's `initiateFTRequest`, this endpoint does **not** take an `identifier` header field or `tPin`.
+
+### Response — happy path
+
+```json
+[
+  {
+    "2FARequired":        "NONE",        /* ← the key difference */
+    "authenticationType": "NONE",
+    "success":            true,
+    "message":            "Purchase Initiated Successfully",
+    "response": [
+      {
+        "requestObject":  { "...": "..." },
+        "responseObject": {
+          "referenceId":       "685011023630",
+          "transactionAmount": { "amount": 7.56, "currencyCode": "MVR" },
+          "netAmount":         { "amount": 7.56, "currencyCode": "MVR" },
+          "chargeDetailsDTO":  { "totalFeesInTenantCurrency": { "amount": 0.0, "...": "..." }, "...": "..." },
+          "isCompleted":       false,
+          "authenticationType":"NONE",
+          "...":               "..."
+        }
+      }
+    ]
+  }
+]
+```
+
+Cache `referenceId` for step 3. No SMS is sent — proceed straight to confirm.
+
+> **Defensive check:** the Thijooree client throws if it ever sees `2FARequired != "NONE"` on this endpoint so a no-op confirm can't silently complete. If Ooredoo ever turns 2FA on for QR pay, you'll see a clear error instead of a partial transaction.
+
+---
+
+## Step 3: `confirmNewBuy` — settle purchase
+
+### Endpoint
+
+```
+POST https://superapp.ooredoo.mv/api/mfaisaa-bff/mfino/v1.1/web/confirmNewBuy
+```
+
+### Request
+
+**Content-Type:** `application/x-www-form-urlencoded`
+
+| Field | Value |
+|---|---|
+| `role` | `RETAIL_SUBSCRIBER` |
+| `channel` | `C03` |
+| `loginExchangeKey` | From login |
+| `rndValue` / `csValue` | Anti-replay derived from `formData` below |
+| `formData` | `{"referenceId": "<from step 2>"}` |
+| `transactionAuthDetails` | **literal string `"null"`** (not a JSON null, not an empty string — the captured request sends the four-character string `null`) |
+
+### Response — happy path
+
+```json
+[
+  {
+    "success": true,
+    "message": "Payment Completed Successfully",
+    "response": [
+      {
+        "responseObject": {
+          "isCompleted": true,
+          "balanceInquiryDTO": {
+            "currencyCode":    "MVR",
+            "pocketAmount":    92.85,
+            "pocketId":        "<source pocket id>",
+            "pocketBalanceMap": { "...": "..." }
+          },
+          "status": { "replyCode": 0.0 },
+          "...":    "..."
+        }
+      }
+    ]
+  }
+]
+```
+
+### Session expiry
+
+Same envelope as elsewhere — `attributeValue: "SESSION_EXPIRED"` with HTTP 200; the client throws `MfaisaSessionExpiredException`. See [03-history.md → Session expiry](03-history.md#session-expiry).
+
+---
+
+## Optional: `save/smart-pay-recipient` — bookkeeping
+
+After a successful confirm the official Ooredoo app saves the merchant to a server-side "recent recipients" list:
+
+```
+POST https://superapp.ooredoo.mv/api/mfaisaa-bff/save/smart-pay-recipient
+```
+
+This is **not** required for the payment itself — the transfer is final once `confirmNewBuy` succeeds. Thijooree skips it; the merchant is kept in the local picker `RecentsCache` under an `mfaisaqr:<qrCodeId>` synthetic accountNumber (mirroring the BML QR `bmlqr:` scheme).
+
+---
+
+&nbsp;
+
+---
+
+> **← Back to** [Transfer Money](04-transfer.md) | [README](README.md)

docs/mfaisaapi/README.md

@@ -88,6 +88,7 @@ Client                                                Server
 | 2 | [Login](02-login.md) | Subscriber lookup + mPIN login |
 | 3 | [Transaction History](03-history.md) | Paginated history per session |
 | 4 | [Transfer Money](04-transfer.md) | Three-step wallet-to-wallet send: recipient lookup → initiate (server SMSes OTP) → confirm |
+| 5 | [QR Merchant Payment](05-qr-pay.md) | Three-step "smart pay" scan-to-merchant: QR lookup → initiate → confirm. **No OTP** (`2FARequired=NONE`) |
 
 ---