# Android SDK # TransactionHistoryView (Android SDK) > Part of the **Digital Card Engine UI SDK** for Android (Jetpack Compose) This component displays a user's transaction history for a specific card. The host app supplies a `DigitalCardEngineSDK` instance, a `CardEntity`, and optional callbacks — data fetching, loading, and error states are managed internally. Prerequisites: * Setup and Initialize completed. * A `CardEntity` obtained from `sdk.getCards()` and a valid auth token. * If you use the bundled navigation fallback, ensure the SDK activities are included in your manifest (provided by the library). ## Callbacks `UILibrary.TransactionsCardView` exposes two callbacks: * `onSeeMoreClick()` — fired when the user taps the **See More** button. If not provided, the SDK launches `TransactionListActivity` automatically. * `onTransactionClick(Transaction)` — fired when the user taps a transaction row. If not provided, the SDK launches `TransactionDetailsActivity` automatically. ### Callback signatures ```kotlin object UILibrary { @Composable fun TransactionsCardView( sdk: DigitalCardEngineSDK, card: CardEntity, transactionLimit: Int = 5, onSeeMoreClick: (() -> Unit)? = null, onTransactionClick: ((Transaction) -> Unit)? = null ) } ``` ### `onSeeMoreClick` Triggered when the user taps the **See More** button (only shown when there are more transactions than `transactionLimit`). Omit to let the SDK navigate to the built-in `TransactionListActivity`. ### `onTransactionClick` Triggered when the user taps a transaction row. Receives a full `Transaction` model suitable for presenting a detail screen. Omit to let the SDK navigate to the built-in `TransactionDetailsActivity`. #### `Transaction` type ```kotlin data class Transaction( val transactionType: String, // e.g. "LOAD", "DEDUCTION", "AUTHORISATION" val transactionTypeDetail: String?, // Sub-type detail or MCC code val transactionDate: String, // ISO date-time string val transactionAmount: Double, // Absolute transaction amount val transactionId: String, // Unique transaction ID val transactionDescription: String? // Optional description / merchant name ) ``` ## Customization Customization works at two levels: 1. **Global defaults** via `sdk.styleConfiguration` — applied to all SDK views. 2. **Per-instance overrides** via `UILibrary.TransactionsCard` parameters — take precedence over global defaults. ### `TransactionsCardProperties` High-level toggles for the standalone card widget. ```kotlin data class TransactionsCardProperties( val title: Boolean = true // Show the "Transactions" section header ) ``` | Property | Type | Default | Description | | -------- | --------- | ------- | ------------------------------------------------------ | | `title` | `Boolean` | `true` | Show the "Transactions" section header above the list. | ### `TransactionsCardStyleProperties` Low-level visual tokens for the standalone card widget. ```kotlin data class TransactionsCardStyleProperties( val internalHorizontalPadding: Float = 16f, val internalVerticalPadding: Float = 16f, val externalPadding: Float = 16f, val internalGap: Float = 16f, val radius: Float = 16f, val containerColor: Color? = null, val titleTextStyle: TextStyle? = null ) ``` | Property | Type | Default | Applies to | | --------------------------- | ------------ | ------- | ----------------------------------------------------------- | | `internalHorizontalPadding` | `Float` | `16f` | Left/right padding inside the transactions card. | | `internalVerticalPadding` | `Float` | `16f` | Top/bottom padding inside the transactions card. | | `externalPadding` | `Float` | `16f` | Outer padding around the entire card. | | `internalGap` | `Float` | `16f` | Spacing between the title and the transaction list. | | `radius` | `Float` | `16f` | Corner radius for the card background. | | `containerColor` | `Color?` | `null` | Background color override. Falls back to `palette.surface`. | | `titleTextStyle` | `TextStyle?` | `null` | Typography override for the section title. | #### Usage ```kotlin val style = TransactionsCardStyleProperties( internalHorizontalPadding = 12f, radius = 8f ) ``` ## Usage example ### Summary card (embedded on a screen) ```kotlin import androidx.compose.runtime.Composable import androidx.compose.runtime.CompositionLocalProvider import com.paymentology.digital_card_engine_sdk_android.DigitalCardEngineSDK import com.paymentology.digital_card_engine_sdk_android.ui.UILibrary import com.paymentology.ei_card_provider_sdk.model.CardEntity @Composable fun TransactionsSection( sdk: DigitalCardEngineSDK, card: CardEntity ) { CompositionLocalProvider(UILibrary.LocalStyleConfiguration provides sdk.styleConfiguration) { UILibrary.TransactionsCardView( sdk = sdk, card = card, transactionLimit = 5, onSeeMoreClick = { /* navigate to full transaction list screen */ }, onTransactionClick = { txn -> /* navigate to transaction detail */ } ) } } ``` Behavior: * Fetches transaction history for the given card and displays up to `transactionLimit` rows. * Handles loading and error states; a retry button re-runs the fetch. * `cardEntity.transactionHasNext` and `cardEntity.transactionNextPageStartingAfter` indicate whether more pages are available (see pagination below). ## Standalone list variant (`TransactionsCard`) Use `UILibrary.TransactionsCard` when you already hold transaction data (e.g. from your ViewModel) and want full control over rendering: ```kotlin object UILibrary { @Composable fun TransactionsCard( transactions: List, isLoading: Boolean = false, errorMessage: String? = null, onRetry: (() -> Unit)? = null, transactionLimit: Int = 10, hasMoreTransactions: Boolean = false, onSeeMore: (() -> Unit)? = null, properties: TransactionsCardProperties = TransactionsCardProperties(), style: TransactionsCardStyleProperties = TransactionsCardStyleProperties(), styleConfiguration: StyleConfiguration = LocalStyleConfiguration.current ) } ``` ## Fetching data via core SDK `sdk.getTransactionHistory()` is a `suspend` function. It calls `sdk.selectCard(card)` internally and returns a `CardEntity` enriched with `transactionHistory`, updated balance, and pagination state. ```kotlin // Must be called from a coroutine scope or ViewModel val result: CardEntity = sdk.getTransactionHistory( card = card, periodStart = "2026-01-01T00:00:00", // ISO local date-time periodEnd = "2026-01-31T23:59:59", pageSize = 50 // 1–200; omit for default ) val transactions = result.transactionHistory ?: emptyList() ``` ### Full signature ```kotlin suspend fun DigitalCardEngineSDK.getTransactionHistory( card: CardEntity, periodStart: String, // ISO local date-time, e.g. "2026-01-01T00:00:00" periodEnd: String, // ISO local date-time, e.g. "2026-01-31T23:59:59" remarks: String? = null, // Optional filter string pageSize: Int? = null, // 1–200 nextPageStartingAfter: String? = null // Pagination cursor from previous response ): CardEntity ``` ### Pagination The response carries pagination state on `CardEntity`: * `transactionHasNext: Boolean?` — `true` if more pages exist. * `transactionNextPageStartingAfter: String?` — cursor to pass as `nextPageStartingAfter` in the next call. * `transactionCurrency: String?` — currency code for the returned transactions. ```kotlin // First page var result = sdk.getTransactionHistory(card, periodStart, periodEnd, pageSize = 50) val allTransactions = result.transactionHistory?.toMutableList() ?: mutableListOf() // Fetch next pages while available while (result.transactionHasNext == true) { result = sdk.getTransactionHistory( card = card, periodStart = periodStart, periodEnd = periodEnd, pageSize = 50, nextPageStartingAfter = result.transactionNextPageStartingAfter ) result.transactionHistory?.let { allTransactions.addAll(it) } } ``` ## Error handling tips * Initialize the SDK and ensure the token is valid before fetching. * On 401/403 or expired token, refresh via `EiCardProviderSDK.updateAuthToken(newToken)` then retry. * Surface `errorMessage` and provide a retry callback to re-run the fetch. * Use `transactionHasNext` and `isLoading` flags to gate pagination UI actions.