# 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)