update bml api docs

2026-05-23 23:33:31 +05:00
parent a3f8852163
commit 0a27de4a34
12 changed files with 2250 additions and 0 deletions
@@ -0,0 +1,164 @@
+# Card Statement
+
+Fetch transaction history for a card account (prepaid, credit, or debit). Returns three sets of entries: outstanding authorisations, unbilled transactions, and billed statement entries.
+
+---
+
+## Endpoint
+
+```
+POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/card/statement
+```
+
+---
+
+## Prerequisites
+
+- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
+- Internal card ID (`id` field from [dashboard](04-dashboard.md)) and a target month
+
+---
+
+## Request
+
+**Content-Type:** `application/json`
+
+### Body
+
+```json
+{
+  "card": "card001",
+  "month": "2026-05"
+}
+```
+
+| Field | Description |
+|---|---|
+| `card` | Internal card ID — the `id` field from the dashboard response (not the card number) |
+| `month` | Target month in `YYYY-MM` format |
+
+### Headers
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <access_token>` |
+| `User-Agent` | `bml-mobile-banking/348 (Xiaomi; Android 14; 22101320I)` |
+| `x-app-version` | `2.1.44.348` |
+
+```bash
+curl --request POST \
+  --url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/card/statement' \
+  --header 'Authorization: Bearer <access_token>' \
+  --header 'User-Agent: bml-mobile-banking/348 (Xiaomi; Android 14; 22101320I)' \
+  --header 'x-app-version: 2.1.44.348' \
+  --header 'Content-Type: application/json' \
+  --data '{"card":"card001","month":"2026-05"}'
+```
+
+---
+
+## Response
+
+The payload contains up to three distinct sections, each may be absent or `null`:
+
+```json
+{
+  "success": true,
+  "payload": {
+    "outstanding": {
+      "CardOutStdAuthDetails": [
+        {
+          "TranApprCode": "123456",
+          "DateTime": "2026-05-16T15:10:25",
+          "TranDesc": "Online Purchase - Amazon",
+          "BillingAmount": 50.00,
+          "BillingCcy": "USD"
+        }
+      ]
+    },
+    "unbilled": {
+      "CardUnbillTxnDetails": [
+        {
+          "TranApprCode": "789012",
+          "DateTime": "2026-05-15T10:30:00",
+          "TranDesc": "Supermarket",
+          "BillingAmount": 120.00,
+          "BillingCcy": "MVR"
+        }
+      ]
+    },
+    "cardstatement": [
+      {
+        "TranRef": "STMT20260501001",
+        "TransDate": "2026-05-01",
+        "TranDate": "2026-05-01",
+        "TranDesc": "Monthly Fee",
+        "Description": "Monthly Fee",
+        "TranAmount": 25.00,
+        "TranCcy": "MVR"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Response Sections
+
+### `outstanding.CardOutStdAuthDetails` — Pending Authorisations
+
+Transactions that have been authorised but not yet posted. Amounts are in the billing currency.
+
+| Field | Type | Description |
+|---|---|---|
+| `TranApprCode` | `string` | Authorisation approval code |
+| `DateTime` | `string` | Authorisation timestamp |
+| `TranDesc` | `string` | Merchant or transaction description |
+| `BillingAmount` | `number` | Amount in billing currency (positive) |
+| `BillingCcy` | `string` | Billing currency code |
+
+### `unbilled.CardUnbillTxnDetails` — Unbilled Transactions
+
+Transactions posted to the card but not yet included in a statement cycle.
+
+Same field structure as `CardOutStdAuthDetails`.
+
+### `cardstatement` — Billed Statement Entries
+
+Previously billed transactions from the statement cycle for the requested month.
+
+| Field | Type | Description |
+|---|---|---|
+| `TranRef` | `string` | Statement reference |
+| `TransDate` / `TranDate` | `string` | Transaction date (check both keys; `TransDate` takes priority) |
+| `TranDesc` / `Description` | `string` | Description (check both keys; `TranDesc` takes priority) |
+| `TranAmount` | `number` | Amount — **stored as positive, displayed as debit** (negate for sign convention) |
+| `TranCcy` | `string` | Transaction currency |
+
+> The `TranAmount` in `cardstatement` is always positive in the API response. Negate it to `−TranAmount` so it follows the standard debit-negative convention.
+
+---
+
+## Amount Sign Convention
+
+| Section | Sign in response | Meaning |
+|---|---|---|
+| `outstanding` / `unbilled` | Positive | Debit (charge to card) |
+| `cardstatement` | Positive (negate on display) | Debit (charge to card) |
+
+---
+
+## Error Responses
+
+| HTTP Code | Meaning |
+|---|---|
+| `401` / `419` | Access token expired — attempt [token refresh](03-oauth-token.md#token-refresh) |
+
+---
+
+&nbsp;
+
+---
+
+[← Account History](06-account-history.md) &nbsp;&nbsp;&nbsp; **Next →** [Transfer](08-transfer.md)