update docs

docs/bmlapi/16-card-payment.md

@@ -73,6 +73,8 @@ POST <ACS creq url>  otpValue=<token TOTP> → auto-POST form (cres → gateway)
 POST <gateway callback>  cres             → auto-POST form (→ mpgsNotification)
 POST transactions/mpgsNotification/<id>   → records the verdict
 POST  …next-action  POLL                                   → TRANSACTION_CONFIRMED
+GET  transaction…/<id>?wait=1             → 302 merchant redirectUrl (?…&state=CONFIRMED&signature=…)
+                                          → 302 merchant receipt page
 ```
 
 ---
@@ -223,8 +225,30 @@ Poll `next-action` until the recorded verdict surfaces:
 | `TRANSACTION_CONFIRMED` | Success |
 | `TRANSACTION_FAILED` | Declined |
 
-The merchant's own backend is also notified out-of-band (e.g.
-`fahipay.mv/api/bml/gateway/callback/?…state=CONFIRMED`).
+## 7. Return to the merchant
+
+The `mpgsNotification` response is a page whose script sends the browser to
+`https://transaction.merchants.bankofmaldives.com.mv/<id>?wait=1`. Once the transaction is
+confirmed, that 302s to the merchant's `redirectUrl` with a BML-signed result, then on to the
+merchant's own receipt page:
+
+```
+GET transaction…/<id>?wait=1
+→ 302 https://www.dhiraagu.com.mv/api/dhiraagu-bml-response.aspx?transactionId=<id>&state=CONFIRMED&signature=<sha1>
+→ 302 https://www.dhiraagu.com.mv/services/reload-receipt?pyid=<paymentId>
+```
+
+(FahiPay's is `fahipay.mv/api/bml/gateway/callback/?…state=CONFIRMED`.)
+
+**This hop is required.** It's how at least Dhiraagu learns it was paid: a test reload that
+stopped at `TRANSACTION_CONFIRMED` charged the card but never topped up, and opening the
+`?wait=1` URL in a browser afterwards delivered it. The signature is generated by BML, so the
+hop can be replayed later from the transaction id alone.
+
+`BmlMerchantCardPayClient` does it after every confirmed payment (`returnToMerchant`): a browser
+UA GET that follows the redirects, up to 3 tries, success = the chain ends on a 2xx page. The
+merchant host may be behind Cloudflare: plain `curl` got a 403 on `dhiraagu.com.mv`, okhttp got
+through.
 
 ---
 
@@ -243,6 +267,7 @@ learn of breakage from a failed live payment.
 | **Merchant detection** | BML adds other card providers (UnionPay, Apple/Google Pay); non-`mpgs` card provider | Misroute to the wrong flow |
 | **`window.appData` parsing** | Key moved/obfuscated or made dynamically signed | No `pomeloJsKey` |
 | **Double-charge** | Confirm poll times out but the charge went through | Retry risks paying twice |
+| **Return to merchant** | The merchant's `redirectUrl` host blocks the client (Cloudflare) or is down | Charged but not delivered — `Success(merchantNotified = false)`, the app toasts the BML transaction id; opening `…/<id>?wait=1` in a browser delivers it |
 
 **Maintenance:** re-capture a HAR whenever any party updates; expect to touch the ACS form parser
 most often; the flow is effectively untestable in CI (no deterministic 3-D Secure double). Keep the