--- updatedAt: 2026-11-11T10:49:16.000Z agentTools: siteIndex: https://developer.paymentology.com/llms.txt projectIndex: https://developer.paymentology.com/lume/llms.txt --- # Data Models # Android SDK: Data Models Reference guide for the core data structures used throughout the Digital Card Engine SDK. ## CardEntity The primary model representing a complete card with all associated data. ```kotlin data class CardEntity( val receivedCard: ReceivedCard, val cardArt: String?, val isReceiver: Boolean = false, val transactionHistory: List?, val transactionCurrency: String?, val transactionHasNext: Boolean?, val transactionNextPageStartingAfter: String?, val events: List?, val assetType: AssetType?, val metadata: CardMetadata? ) ``` ### Properties | Property | Type | Nullable | Description | | ---------------------------------- | -------------------- | -------- | --------------------------------------------------------------------- | | `receivedCard` | `ReceivedCard` | No | Core card information (ID, balance, PAN, etc.) | | `cardArt` | `String?` | Yes | Base64-encoded image of the card front | | `isReceiver` | `Boolean` | No | Whether the current user is the card receiver (default `false`) | | `transactionHistory` | `List?` | Yes | List of transactions (fetched separately via `getTransactionHistory`) | | `transactionCurrency` | `String?` | Yes | ISO 4217 currency code for the returned transactions | | `transactionHasNext` | `Boolean?` | Yes | `true` if more transaction pages are available | | `transactionNextPageStartingAfter` | `String?` | Yes | Cursor to pass as `nextPageStartingAfter` in the next page request | | `events` | `List?` | Yes | Card lifecycle events (fetched separately) | | `assetType` | `AssetType?` | Yes | Type categorization for the card | | `metadata` | `CardMetadata?` | Yes | Additional extensible metadata | ### Usage ```kotlin // Fetch cards val cards: List = sdk.getCards() // Access card details val card = cards.first() val label = card.receivedCard.cardLabel val balance = card.receivedCard.balance val last4 = card.receivedCard.last4 ``` *** ## ReceivedCard Core card information including identifiers, balance, and cardholder details. ```kotlin data class ReceivedCard( val giftCardId: String, val expiryDate: String, val cardArtId: String, val balance: Double?, val name: String?, val lastName: String?, val last4: String?, val message: CardMessage?, val status: ActivationStatus?, val cardLabel: String? ) ``` ### Properties | Property | Type | Nullable | Description | | ------------ | ------------------- | -------- | --------------------------------- | | `giftCardId` | `String` | No | Unique card identifier | | `expiryDate` | `String` | No | Expiration date (ISO 8601 format) | | `cardArtId` | `String` | No | ID to fetch card artwork | | `balance` | `Double?` | Yes | Current card balance | | `name` | `String?` | Yes | Cardholder first name | | `lastName` | `String?` | Yes | Cardholder last name | | `last4` | `String?` | Yes | Last 4 digits of PAN | | `message` | `CardMessage?` | Yes | Optional card message/greeting | | `status` | `ActivationStatus?` | Yes | Card activation status | | `cardLabel` | `String?` | Yes | Display name for the card | ### Usage ```kotlin val receivedCard = cardEntity.receivedCard // Display card label val displayName = receivedCard.cardLabel ?: receivedCard.giftCardId // Format masked PAN val maskedPan = receivedCard.last4?.let { "•••• $it" } ?: "N/A" // Format balance val formattedBalance = receivedCard.balance?.let { "${sdk.styleConfiguration.currencySymbol}%.2f".format(it) } ?: "N/A" ``` *** ## Transaction Represents a single card transaction. ```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 ) ``` ### Properties | Property | Type | Nullable | Description | | ------------------------ | --------- | -------- | ------------------------------------------------------------------------ | | `transactionType` | `String` | No | Transaction type string, e.g. `"LOAD"`, `"DEDUCTION"`, `"AUTHORISATION"` | | `transactionTypeDetail` | `String?` | Yes | Sub-type detail or merchant category code | | `transactionDate` | `String` | No | Transaction date/time (ISO date-time format) | | `transactionAmount` | `Double` | No | Absolute transaction amount | | `transactionId` | `String` | No | Unique transaction identifier | | `transactionDescription` | `String?` | Yes | Optional description or merchant name | ### Usage ```kotlin // Fetch transactions val result = sdk.getTransactionHistory( card = card, periodStart = "2026-01-01T00:00:00", periodEnd = "2026-01-31T23:59:59" ) val transactions = result.transactionHistory ?: emptyList() // Display transaction transactions.forEach { txn -> val label = txn.transactionDescription ?: txn.transactionType println("${txn.transactionAmount} on ${txn.transactionDate}: $label") } // Filter by type val loads = transactions.filter { it.transactionType == "LOAD" } val deductions = transactions.filter { it.transactionType == "DEDUCTION" } ``` *** ## CardEvent Represents a lifecycle or activity event for a card. ```kotlin data class CardEvent( val eventTime: String, val eventType: CardEventType, val initialBalance: Double ) ``` ### Properties | Property | Type | Nullable | Description | | ---------------- | --------------- | -------- | ------------------------------------- | | `eventTime` | `String` | No | Event date/time (ISO 8601) | | `eventType` | `CardEventType` | No | Type enum (see below) | | `initialBalance` | `Double` | No | Card balance at the time of the event | ### CardEventType ```kotlin enum class CardEventType { Purchased, FundsLoaded, Sent, Activated, Declined, Expired } ``` ### Usage ```kotlin // Fetch events val cardWithEvents = sdk.getEventHistory(card) val events = cardWithEvents.events ?: emptyList() // Display recent events events.take(5).forEach { event -> println("${event.eventType} at ${event.eventTime}: balance=${event.initialBalance}") } // Filter by type val fundsLoaded = events.filter { it.eventType == CardEventType.FundsLoaded } val activations = events.filter { it.eventType == CardEventType.Activated } ``` *** ## CardMessage Optional message attached to a card (e.g., gift card greeting). ```kotlin data class CardMessage( val receiver: String?, val text: String? ) ``` ### Properties | Property | Type | Nullable | Description | | ---------- | --------- | -------- | ---------------------- | | `receiver` | `String?` | Yes | Receiver name/greeting | | `text` | `String?` | Yes | Message text | ### Usage ```kotlin val message = cardEntity.receivedCard.message if (message != null) { println("To: ${message.receiver ?: "You"}") println(message.text ?: "") } ``` *** ## ActivationStatus Card activation/lifecycle status. ```kotlin enum class ActivationStatus { Sent, Activated, Declined, Expired, InActivation, NotActivated, Rejected, InProgress, Failed, Blocked } ``` ### Usage ```kotlin val status = cardEntity.receivedCard.status when (status) { ActivationStatus.Activated -> showCard() ActivationStatus.Blocked -> showLockedState() ActivationStatus.Expired -> showExpiredMessage() ActivationStatus.Declined, ActivationStatus.Rejected, ActivationStatus.Failed -> showErrorState() else -> showPendingState() } ``` *** ## AssetType Categorization for different card types. ```kotlin enum class AssetType { GIFT_CARD, PREPAID_CARD, DEBIT_CARD, CREDIT_CARD, VIRTUAL_CARD, OTHER } ``` *** ## CardMetadata Extensible key-value metadata for cards. ```kotlin data class CardMetadata( val properties: Map ) ``` ### Usage ```kotlin val metadata = cardEntity.metadata val customField = metadata?.properties?.get("customField") ``` *** ## UI-Specific Models ### CardListItem UI wrapper for card list items returned in `onCardSelected` callbacks. ```kotlin data class CardListItemUi( val label: String, // Card display name or ID val number: String, // Masked PAN, e.g. "•••• 1234" val balance: String, // Formatted balance string val imageBase64: String?, // Base64-encoded card artwork val entity: CardEntity // Underlying model — pass to details/transactions ) typealias CardListItem = CardListItemUi ``` ### CardOverviewProperties Per-instance configuration for `UILibrary.CardOverview`. ```kotlin data class CardOverviewProperties( val cardInfo: CardInfo = CardInfo.Brief, val actionButton: Boolean = true, val cardStatus: CardStatus = CardStatus.Default, val cardWidgetStyle: CardWidgetStyle = CardWidgetStyle.Large, val slider: Boolean = false, val currencySymbol: String? = null ) enum class CardInfo { Brief, // Balance only Detail // Balance + masked PAN + expiry } enum class CardStatus { Default, // Normal state Details, // Secure fields visible Locked // Card locked state } enum class CardWidgetStyle { Default, // Compact Large // Full-width } ``` ### TransactionsCardProperties Configuration for the transactions card widget. ```kotlin data class TransactionsCardProperties( val title: Boolean = true // Show the "Transactions" section header ) ``` *** ## Complete Example ```kotlin import androidx.lifecycle.lifecycleScope import kotlinx.coroutines.launch class CardActivity : ComponentActivity() { private lateinit var sdk: DigitalCardEngineSDK override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) sdk = (application as MyApp).sdk lifecycleScope.launch { try { // Fetch all cards val cards = sdk.getCards() val card = cards.firstOrNull() ?: return@launch // Access card properties val receivedCard = card.receivedCard println("Card: ${receivedCard.cardLabel}") println("Balance: ${receivedCard.balance}") println("Last 4: ${receivedCard.last4}") println("Status: ${receivedCard.status}") // Fetch transactions (requires periodStart / periodEnd) val result = sdk.getTransactionHistory( card = card, periodStart = "2026-01-01T00:00:00", periodEnd = "2026-01-31T23:59:59" ) result.transactionHistory?.forEach { txn -> println("${txn.transactionType}: ${txn.transactionAmount} on ${txn.transactionDate}") } // Fetch events val cardWithEvents = sdk.getEventHistory(card) cardWithEvents.events?.forEach { event -> println("${event.eventType} at ${event.eventTime}: balance=${event.initialBalance}") } } catch (e: Exception) { Log.e("CardActivity", "Error: ${e.message}") } } } } ``` *** ## Nullability Guidelines Many properties are nullable to accommodate: * **Partial API responses**: Backend may not always return all fields * **Progressive loading**: Data fetched incrementally (e.g., transactions loaded separately) * **Optional features**: Not all cards have messages, metadata, etc. Always use safe calls (`?.`) or Elvis operators (`?:`) when accessing nullable properties. *** ## Type Conversions ### Date Formatting ```kotlin import java.time.LocalDateTime import java.time.format.DateTimeFormatter fun formatTransactionDate(isoDateTime: String): String { val dt = LocalDateTime.parse(isoDateTime) val formatter = DateTimeFormatter.ofPattern("MMM dd, yyyy HH:mm") return dt.format(formatter) } // Usage val displayDate = formatTransactionDate(transaction.transactionDate) ``` ### Currency Formatting ```kotlin import java.text.NumberFormat import java.util.Locale fun formatAmount(amount: Double, currencySymbol: String?): String { val formatted = NumberFormat.getInstance(Locale.US).format(amount) return "${currencySymbol ?: ""}$formatted" } // Usage val displayAmount = formatAmount( transaction.transactionAmount, sdk.styleConfiguration.currencySymbol ) ``` *** ## See Also * [Card List](../card-list/sdk-android.md) — Using `CardEntity` in lists * [Card Details](../card-details/sdk-android.md) — Displaying full card information * [Transaction History](../transaction-history/sdk-android.md) — Working with transactions * [Styling & Theming](styling-theming.md) — Customizing display # Sibling pages * [Component Reference](https://developer.paymentology.com/lume/docs/component-reference.md) * [Styling & Theming](https://developer.paymentology.com/lume/docs/styling-theming.md) * [Error Handling](https://developer.paymentology.com/lume/docs/error-handling.md)