---
updatedAt: 2026-11-11T10:49:16.000Z
agentTools:
  siteIndex: https://developer.paymentology.com/llms.txt
  projectIndex: https://developer.paymentology.com/lume/llms.txt
---

# Card Details - Headless / API

# Card Details: Headless / Data API

Fetch event history and secure card data (TOTP + MCD) directly, without the UI microfrontends. Use these APIs when building a fully custom card details screen.

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

## Event history

### Android (Kotlin)

```kotlin
// Returns CardEntity enriched with events and updated balance
val cardWithEvents = sdk.getEventHistory(card)
val events = cardWithEvents.events ?: emptyList()
```

### iOS (Swift)

```swift
let cardWithEvents = try await sdk.getEventHistory(card: card)
let events = cardWithEvents.events ?? []
```

Each `CardEvent` represents lifecycle or activity events such as card activation, locking/unlocking, and status changes.

## Time-based secret (TOTP) for secure card images

Required before rendering PAN / expiry / emboss / CVV via MeaWallet MCD. Requires a selected card.

### Android

```kotlin
sdk.selectCard(card)
val totp: com.paymentology.ei_card_provider_sdk.model.TOTPResponse = sdk.getTimeBasedSecret()
// totp.secret, totp.cardId, totp.last4
```

### iOS

```swift
sdk.selectCard(card: card)
let (secret, cardId) = try await sdk.getTimeBasedSecret()
```

> **Security**: TOTP secrets expire quickly. Generate a new secret for each secure image request. Never log or persist secrets.

## Secure card images (bitmaps / views)

### Android

```kotlin
// Requires: selected card + MCD artifact on classpath + valid TOTP secret
sdk.selectCard(card)
val images: Map<String, android.graphics.Bitmap> = sdk.getCardImages()
// Keys: "pan", "expiry", "embossName", "cvv"

// Or embed a native view (for non-Compose contexts)
val view: android.view.View = sdk.getCardView(context, card)
parent.addView(view)
```

### iOS

Secure card rendering on iOS is handled by the `CardDetailsView` MFE via MeaWallet MCD. See [iOS MFE](mfe-ios.md) for integration details.

## Error handling

* **Auth errors**: refresh token via `updateAuthToken(newToken)` and retry.
* **Card not selected**: call `selectCard()` before requesting TOTP or images.
* **MCD errors**: verify the MCD artifact is present, the card is selected, and the TOTP secret is valid.

# Sibling pages

* [iOS MFE](https://developer.paymentology.com/lume/docs/ios-card-list-mfe.md)
* [Android SDK](https://developer.paymentology.com/lume/docs/sdk-android.md)