# 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 ({manufacturer}; Android {version}; {model})` |
| `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 ({manufacturer}; Android {version}; {model})' \
  --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)