# Transaction History - Headless / API

# Transaction History: Headless / Data API

Fetch transaction history directly without using the UI microfrontends. Use these APIs when building a custom transaction list or analytics UI.

Prerequisites: SDK initialized and a `CardEntity` available. See [Card List - API](../card-list/api.md) for fetching cards.

## Fetch transaction history

Returns the `CardEntity` enriched with `transactionHistory` and an updated balance.

### Android (Kotlin)

```kotlin
// All SDK data calls are suspend — invoke from a coroutine scope
val cardWithTx = sdk.getTransactionHistory(card)
val transactions = cardWithTx.transactionHistory ?: emptyList()
```

### iOS (Swift)

```swift
let cardWithTx = try await sdk.getTransactionHistory(card: card)
let transactions = cardWithTx.transactionHistory ?? []
```

### Transaction model

| Field                                      | Type    | Description                          |
| ------------------------------------------ | ------- | ------------------------------------ |
| `transactionId`                            | String  | Unique identifier                    |
| `transactionType`                          | Enum    | `LOAD`, `DEDUCTION`, `AUTHORISATION` |
| `transactionAmount`                        | Double  | Transaction amount                   |
| `transactionDescription`                   | String  | Merchant or description text         |
| `transactionDate` / `transactionTimestamp` | String  | ISO 8601 date/time                   |
| `merchantCategoryCode`                     | String? | MCC code (if available)              |

## Threading

* **Android**: all calls are `suspend`; invoke from a ViewModel or coroutine scope.
* **iOS**: all calls are `async`; use `try await` from an async context. Wrap UI updates in `@MainActor`.

## Error handling

* **Auth errors (401/403)**: refresh the token via `updateAuthToken(newToken)` and retry.
* **Network errors**: implement retry logic with back-off; expose a retry action in your UI.
* The SDK does not paginate on-device; transactions are returned in backend order (typically newest first).