update docs

2026-06-13 21:30:12 +05:00
parent 281864347e
commit a8cd22cbe1
51 changed files with 1830 additions and 469 deletions
@@ -0,0 +1,121 @@
+# Card Freeze / Unfreeze
+
+Lock or unlock a BML card to block / allow new authorisations. The same endpoint handles both actions, distinguished by the `action` field.
+
+---
+
+## Endpoint
+
+```
+POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/services/card/freeze
+```
+
+---
+
+## Prerequisites
+
+- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
+- `cardId` is the **internal card UUID** (`BankAccount.internalId`, sourced from the `id` field of a `Card` entry in the [dashboard](04-dashboard.md) response) — NOT the displayed 16-digit card number
+
+---
+
+## Request
+
+### Body
+
+**Content-Type:** `application/json`
+
+```json
+{
+  "card": "<internalId>",
+  "action": "freeze"
+}
+```
+
+| Field | Type | Notes |
+|---|---|---|
+| `card` | `string` | Internal card UUID — the `id` from the dashboard Card object |
+| `action` | `string` | `"freeze"` to lock the card; `"unfreeze"` to unlock |
+
+### Headers
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <access_token>` |
+| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
+| `x-app-version` | `2.1.44.348` |
+| `accept` | `application/json` |
+| `Content-Type` | `application/json` |
+
+```bash
+curl --request POST \
+  --url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/services/card/freeze' \
+  --header 'Authorization: Bearer <access_token>' \
+  --header 'User-Agent: bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})' \
+  --header 'x-app-version: 2.1.44.348' \
+  --header 'accept: application/json' \
+  --header 'Content-Type: application/json' \
+  --data '{"card":"abc-123-def-456","action":"freeze"}'
+```
+
+---
+
+## Response
+
+```json
+{
+  "success": true,
+  "code": 0,
+  "payload": "Card frozen successfully",
+  "message": ""
+}
+```
+
+### Fields
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | `bool` | `true` on success |
+| `code` | `int` | `0` on success; non-zero indicates an error |
+| `payload` | `string` | Human-readable confirmation text (may be blank) |
+| `message` | `string` | Fallback error/info text |
+
+Success is determined by **both** `success == true` AND `code == 0` (`BmlCardClient.kt:46`). Either condition alone is not enough.
+
+### Display Message
+
+The client prefers `payload` for the confirmation text and falls back to `message` when `payload` is blank (`BmlCardClient.kt:49`):
+
+```
+payload (if non-blank) → fallback message
+```
+
+---
+
+## Failure
+
+```json
+{
+  "success": false,
+  "code": 1,
+  "payload": "",
+  "message": "Card cannot be frozen at this time"
+}
+```
+
+Returned with HTTP `200` for application-level errors. The `message` (or `payload`) field contains the reason.
+
+### Server / Auth Errors
+
+| HTTP Code | Behaviour |
+|---|---|
+| `401` / `419` | Throws `AuthExpiredException` — refresh the token or re-login |
+| `5xx` | Throws `BankServerException("BML")` — server-side failure, retry |
+
+---
+
+&nbsp;
+
+---
+
+[← Notifications](14-notifications.md)