122 lines
2.9 KiB
Markdown
122 lines
2.9 KiB
Markdown
# 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 |
|
|
|
|
---
|
|
|
|
|
|
|
|
---
|
|
|
|
[← Notifications](14-notifications.md)
|