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

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

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:

Global defaults via sdk.styleConfiguration — applied to all SDK views.
Per-instance overrides via UILibrary.TransactionsCard parameters — take precedence over global defaults.

`TransactionsCardProperties`

High-level toggles for the standalone card widget.

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.

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

val style = TransactionsCardStyleProperties(
    internalHorizontalPadding = 12f,
    radius = 8f
)

Usage example

Summary card (embedded on a screen)

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:

object UILibrary {
    @Composable
    fun TransactionsCard(
        transactions: List<Transaction>,
        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.

// 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

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.

// 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.