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,147 @@
+# Foreign Transaction Limits
+
+Fetch the user's USD foreign currency transaction limits per card, broken down by channel (ATM, ECOM, POS) and category (general, medical).
+
+This endpoint uses a **different base URL** from the main REST API.
+
+---
+
+## Endpoint
+
+```
+GET https://app.bankofmaldives.com.mv/api/v2/foreign-limits
+```
+
+---
+
+## Prerequisites
+
+- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
+
+---
+
+## Request
+
+### Headers
+
+| Header | Value |
+|---|---|
+| `Authorization` | `Bearer <access_token>` |
+| `User-Agent` | `bml-mobile-banking/348 (Xiaomi; Android 14; 22101320I)` |
+| `x-app-version` | `2.1.44.348` |
+| `Accept` | `application/json` |
+
+```bash
+curl --request GET \
+  --url 'https://app.bankofmaldives.com.mv/api/v2/foreign-limits' \
+  --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 'Accept: application/json'
+```
+
+---
+
+## Response
+
+```json
+{
+  "success": true,
+  "payload": [
+    {
+      "type": "Debit",
+      "used": 150.00,
+      "totalLimit": 1000.00,
+      "generalCap": 1000.00,
+      "generalRemaining": 850.00,
+      "medicalRemaining": 500.00,
+      "isAtmEnabled": true,
+      "isPosEnabled": true,
+      "usageByCategory": {
+        "ATM": {
+          "remaining": 350.00,
+          "limit": 500.00
+        },
+        "ECOM": {
+          "remaining": 200.00,
+          "limit": 300.00
+        },
+        "POS": {
+          "remaining": 300.00,
+          "limit": 500.00
+        }
+      }
+    },
+    {
+      "type": "Credit",
+      "used": 0.00,
+      "totalLimit": 2000.00,
+      "generalCap": 2000.00,
+      "generalRemaining": 2000.00,
+      "medicalRemaining": 1000.00,
+      "isAtmEnabled": true,
+      "isPosEnabled": true,
+      "usageByCategory": {
+        "ATM": { "remaining": 500.00, "limit": 500.00 },
+        "ECOM": { "remaining": 500.00, "limit": 500.00 },
+        "POS": { "remaining": 1000.00, "limit": 1000.00 }
+      }
+    }
+  ]
+}
+```
+
+---
+
+## Response Fields
+
+### Top-level
+
+| Field | Type | Description |
+|---|---|---|
+| `success` | `bool` | `true` on success |
+| `payload` | `array` | One entry per card type (e.g. Debit, Credit, Prepaid) |
+
+### Limit Object
+
+| Field | Type | Description |
+|---|---|---|
+| `type` | `string` | Card type — e.g. `"Debit"`, `"Credit"`, `"Prepaid"` |
+| `used` | `number` | Total amount used this period (USD) |
+| `totalLimit` | `number` | Overall foreign transaction limit (USD) |
+| `generalCap` | `number` | General spending cap (USD) |
+| `generalRemaining` | `number` | Remaining general limit (USD) |
+| `medicalRemaining` | `number` | Remaining medical category limit (USD) |
+| `isAtmEnabled` | `bool` | Whether ATM withdrawals are enabled |
+| `isPosEnabled` | `bool` | Whether POS payments are enabled |
+
+### `usageByCategory` — Channel Breakdown
+
+| Channel | Description |
+|---|---|
+| `ATM` | ATM cash withdrawals |
+| `ECOM` | E-commerce / online purchases |
+| `POS` | Point-of-sale payments |
+
+Each channel object:
+
+| Field | Type | Description |
+|---|---|---|
+| `remaining` | `number` | Remaining limit for this channel (USD) |
+| `limit` | `number` | Total limit for this channel (USD) |
+
+---
+
+## Error Responses
+
+| HTTP Code | Meaning |
+|---|---|
+| `401` / `419` | Access token expired — attempt [token refresh](03-oauth-token.md#token-refresh) |
+
+---
+
+&nbsp;
+
+---
+
+[← Account Validation](10-validate.md)