Shihaam Abdul Rahman
256f216da4
All checks were successful
Auto Tag on Version Change / check-version (push) Successful in 4s
165 lines
4.3 KiB
Markdown
165 lines
4.3 KiB
Markdown
# 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) |
|
||
|
||
---
|
||
|
||
|
||
|
||
---
|
||
|
||
[← Account History](06-account-history.md) **Next →** [Transfer](08-transfer.md)
|