ooredoo raastas via bml card

2026-10-03 01:08:33 +05:00
parent 0d4f0074c7
commit 8795d5f758
16 changed files with 370 additions and 42 deletions
@@ -129,4 +129,4 @@ Always fall back to the other provider's lookup if this API returns `custType: n

 ---

-[← README](README.md)
+[← README](README.md) · [Raastas →](02-raastas.md)
@@ -0,0 +1,107 @@
+# Raastas (Quick Pay recharge, paid by BML card)
+
+Recharge an Ooredoo prepaid number through the ooredoo.mv **Quick Pay** page. Ooredoo creates the
+order and hands back a **BML Merchant Services transaction**, which is paid like any card-only
+BML merchant link ([BML API → Merchant Card Payment](../bmlapi/16-card-payment.md)).
+
+Reconstructed from `docs/ooredooapi/tmp/ooredoo_raastas_bml_card.har` (a Firefox HAR, which also
+holds a rejected OTP and an insufficient-funds decline on the same transaction).
+
+---
+
+## Flow overview
+
+```
+GET  /ooredoo-prod/QuickPayPackage/v1/numberTypeValidation?…   → custType PRE (Number Validation)
+POST /ooredoo-prod/PaymentGateway/bml                          → orderID, bmlUrl  ──┐
+                                                                                    │
+        ── from here: the BML card-only merchant flow ──                            │
+GET  transaction.merchants…/<id>  ←──────────────────────────────────────────────────┘
+… Pomelo tokenise, next-action, Wibmo 3-D Secure, MPGS …  → TRANSACTION_CONFIRMED
+GET  transaction.merchants…/<id>?wait=1   → 302 my.ooredoo.mv/bml/response_new.php?…state=CONFIRMED
+     (200, auto-submits)                  → POST www.ooredoo.mv/ooredoo-prod/PaymentGateway/redirect/bml
+                                          → /payment-status?order_id=<orderID>&statusDesc=sucess&status=1
+```
+
+Unlike Dhiraagu, there's no nonce or cart: one POST makes the order and the BML transaction.
+
+---
+
+## 1. Order
+
+`POST https://www.ooredoo.mv/ooredoo-prod/PaymentGateway/bml`
+
+| Header | Value |
+|---|---|
+| `Content-Type` | `application/json` |
+| `Accept` | `application/json` |
+| `Origin` | `https://www.ooredoo.mv` |
+
+```json
+{"msisdn":"9609XXXXXX","purchaseAmount":"21.60","amountWithoutGst":"20",
+ "receiverMsisdn":"9609XXXXXX","transType":"recharge","serviceType":"prepaid",
+ "serviceTypeDisplayName":"Mobile"}
+```
+```json
+{"status":"OK","msg":"Successfully generated order id","code":"2000",
+ "data":{"orderID":"36447930","purchaseAmount":"2160","hashSignature":"…",
+         "shortUrl":"https://pay.bml.com.mv/7A86qLZ1QV",
+         "bmlUrl":"https://transaction.merchants.bankofmaldives.com.mv/6ac009f7bd9b264b80ba6abf", …}}
+```
+
+The 24-hex id at the end of `bmlUrl` is the transaction (`shortUrl` 301s to the same page). The
+page is card-only, no BML Pay. The transaction's `localId` is the MSISDN, `customerReference` the
+order id, and it expires after 7 days.
+
+### GST
+
+**Added on top**, not taken out: the number is credited `amountWithoutGst` and the card pays
+`purchaseAmount = amount + toFixed2(amount × 8 / 100)` (MVR 20 → 21.60). The page's payment
+method list gives `gstPercent: 8` for BML. This is the opposite of Raastas through Fahipay, where
+GST comes out of the amount.
+
+### Limits
+
+Whole MVR, minimum **20** (before GST, so the card pays at least 21.60). The maximum isn't known;
+the capture starts on the payment page.
+
+---
+
+## 2. Return to Ooredoo
+
+`?wait=1` 302s to `https://my.ooredoo.mv/bml/response_new.php?transactionId=<id>&state=CONFIRMED&signature=<hash>`.
+That page is a 200 that auto-submits:
+
+```html
+<body onload="document.forms['wtmpay'].submit()">
+<form method="POST" action="https://www.ooredoo.mv/ooredoo-prod/PaymentGateway/redirect/bml" name="wtmpay">
+  order_id=36447930  amount=21.60000000  msisdn=9609XXXXXX  transtype=2
+  bml_transaction_id=<id>  bml_hash=<hash>  bml_response=CONFIRMED
+  error_code=0  payment_status=success  ptype=bml
+```
+
+which ends on `https://www.ooredoo.mv/payment-status?order_id=36447930&statusDesc=sucess&status=1`
+(the receipt: `totalAmount 21.6`, `amountWithoutGst 20`, `gstAmt 1.6`). The card flow submits the
+form, see [BML API → Return to the merchant](../bmlapi/16-card-payment.md#7-return-to-the-merchant).
+
+A declined attempt sends `?wait=1` to `transaction…/<id>?error=1` instead, and the same
+transaction can be paid again.
+
+---
+
+## Cloudflare
+
+`ooredoo.mv` and `my.ooredoo.mv` are behind Cloudflare. The capture carries a `cf_clearance`
+cookie; okhttp from the phone gets through without one, as with
+[Number Validation](01-number-validation.md).
+
+---
+
+&nbsp;
+
+---
+
+**Related:** [Number Validation](01-number-validation.md) · [BML Merchant Card Payment](../bmlapi/16-card-payment.md) ·
+App side: [Transfer Flows](../thijooree/20-transfer-flows.md#carrier-services-by-bml-card)
+
+[← Number Validation](01-number-validation.md)
@@ -81,6 +81,7 @@ The API expects the full MSISDN including country code `960` (e.g. `9609654321`)
 | # | File | Description |
 |---|---|---|
 | 1 | [Number Validation](01-number-validation.md) | Validate an Ooredoo number and determine account type |
+| 2 | [Raastas](02-raastas.md) | Quick Pay recharge order → BML merchant transaction, paid by card |

 ---