# Card Statement

Fetch transaction history for a card account (prepaid, credit, or debit). Returns three sets of entries: outstanding authorisations, unbilled transactions, and billed statement entries.

---

## Endpoint

```
POST https://www.bankofmaldives.com.mv/internetbanking/api/mobile/card/statement
```

---

## Prerequisites

- Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)
- Internal card ID (`id` field from [dashboard](04-dashboard.md)) and a target month

---

## Request

**Content-Type:** `application/json`

### Body

```json
{
  "card": "card001",
  "month": "2026-05"
}
```

| Field | Description |
|---|---|
| `card` | Internal card ID — the `id` field from the dashboard response (not the card number) |
| `month` | Target month in `YYYY-MM` format |

### Headers

| Header | Value |
|---|---|
| `Authorization` | `Bearer <access_token>` |
| `User-Agent` | `bml-mobile-banking/348 ({manufacturer}; Android {version}; {model})` |
| `x-app-version` | `2.1.44.348` |

```bash
curl --request POST \
  --url 'https://www.bankofmaldives.com.mv/internetbanking/api/mobile/card/statement' \
  --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 'Content-Type: application/json' \
  --data '{"card":"card001","month":"2026-05"}'
```

---

## Response

The payload contains up to three distinct sections, each may be absent or `null`:

```json
{
  "success": true,
  "payload": {
    "outstanding": {
      "CardOutStdAuthDetails": [
        {
          "TranApprCode": "123456",
          "DateTime": "2026-05-16T15:10:25",
          "TranDesc": "Online Purchase - Amazon",
          "BillingAmount": 50.00,
          "BillingCcy": "USD"
        }
      ]
    },
    "unbilled": {
      "CardUnbillTxnDetails": [
        {
          "TranApprCode": "789012",
          "DateTime": "2026-05-15T10:30:00",
          "TranDesc": "Supermarket",
          "BillingAmount": 120.00,
          "BillingCcy": "MVR"
        }
      ]
    },
    "cardstatement": [
      {
        "TranRef": "STMT20260501001",
        "TransDate": "2026-05-01",
        "TranDate": "2026-05-01",
        "TranDesc": "Monthly Fee",
        "Description": "Monthly Fee",
        "TranAmount": 25.00,
        "TranCcy": "MVR"
      }
    ]
  }
}
```

---

## Response Sections

### `outstanding.CardOutStdAuthDetails` — Pending Authorisations

Transactions that have been authorised but not yet posted. Amounts are in the billing currency.

| Field | Type | Description |
|---|---|---|
| `TranApprCode` | `string` | Authorisation approval code |
| `DateTime` | `string` | Authorisation timestamp |
| `TranDesc` | `string` | Merchant or transaction description |
| `BillingAmount` | `number` | Amount in billing currency (positive) |
| `BillingCcy` | `string` | Billing currency code |

### `unbilled.CardUnbillTxnDetails` — Unbilled Transactions

Transactions posted to the card but not yet included in a statement cycle.

Same field structure as `CardOutStdAuthDetails`.

### `cardstatement` — Billed Statement Entries

Previously billed transactions from the statement cycle for the requested month.

| Field | Type | Description |
|---|---|---|
| `TranRef` | `string` | Statement reference |
| `TransDate` / `TranDate` | `string` | Transaction date (check both keys; `TransDate` takes priority) |
| `TranDesc` / `Description` | `string` | Description (check both keys; `TranDesc` takes priority) |
| `TranAmount` | `number` | Amount — **stored as positive, displayed as debit** (negate for sign convention) |
| `TranCcy` | `string` | Transaction currency |

> The `TranAmount` in `cardstatement` is always positive in the API response. Negate it to `−TranAmount` so it follows the standard debit-negative convention.

---

## Amount Sign Convention

| Section | Sign in response | Meaning |
|---|---|---|
| `outstanding` / `unbilled` | Positive | Debit (charge to card) |
| `cardstatement` | Positive (negate on display) | Debit (charge to card) |

---

## Error Responses

| HTTP Code | Meaning |
|---|---|
| `401` / `419` | Access token expired — attempt [token refresh](03-oauth-token.md#token-refresh) |

---

&nbsp;

---

[← Account History](06-account-history.md) &nbsp;&nbsp;&nbsp; **Next →** [Transfer](08-transfer.md)