# 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<Transaction>?,
    val transactionCurrency: String?,
    val transactionHasNext: Boolean?,
    val transactionNextPageStartingAfter: String?,
    val events: List<CardEvent>?,
    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<Transaction>?` | 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<CardEvent>?`   | 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<CardEntity> = 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<String, String>
)
```

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