Digital Card Engine: Getting Started

Welcome to the Digital Card Engine (DCE). This guide gives you the big-picture view of what you can do, how it’s structured, and where to go next. DCE ships SDKs for Android and iOS, plus ready-made UI “microfrontends” you can drop into your app—or you can go headless and build your own UI with the data APIs.

What the SDKs provide

• Unified card data: Fetch received cards, balances, events, transactions, and card art from Paymentology APIs.
• Secure card display: Render PAN/expiry/emboss/CVV via MeaWallet MCD using time-based secrets (TOTP) from the backend.
• Ready-made UI: Composable screens and components on Android, SwiftUI/UIKit components on iOS (matching patterns and theming knobs).
• Theming: Palette, typography, spacing, and view-level properties that mirror across platforms.
• Headless mode: Call the data APIs directly and build your own UI.

SDK structure

• Android
  • UI SDK: digital_card_engine_sdk_android (Compose microfrontends, theming, MCD integration helpers).
  • Core SDK: card_provider_sdk (Kotlin Multiplatform, networking, auth, TOTP, card art, transactions, events).
  • Reference app: androidTestApp/ shows end-to-end setup, navigation, and theming.
• iOS
  • UI SDK: Swift package with ready-made screens/components (SwiftUI wrappers).
  • Core SDK: KMP core consumed via XCFramework. Mirrors Android data APIs (cards, transactions, events, TOTP).
  • Reference app: iOSTestApp/ demonstrates initialization, theming, and navigation.

When to use the UI vs headless

• Use the UI microfrontends when you want fast integration with aligned UX, built-in loading/error states, and secure display via MCD.
• Go headless when you need bespoke UI, custom navigation, or your own state management. The data APIs expose cards, balances, transactions, events, TOTP, and card images.

Environments and security

• Envs: DEV, TEST, PROD (same names across Android/iOS).
• Tokens: short-lived, provided by your backend; never hardcode secrets. The SDKs validate tokens and surface auth errors.
• Secure fields: PAN/expiry/name/CVV require a selected card, a valid TOTP secret from the backend, and the MeaWallet MCD artifact. Do not log or persist secrets.

Platform highlights

• Android
  • Minimum SDK 29, Compose-based UI kit with theming via StyleConfiguration.
  • Core data APIs are suspend functions; integrate with coroutines/ViewModels.
  • MCD integration handled in the UI SDK; headless access via getCardImages() or getCardView().
• iOS
  • Swift API surface mirrors Android concepts (initialize with token + environment, fetch cards/transactions/events, request TOTP, render secure card).
  • UI components are themeable; you can use SwiftUI or UIKit wrappers.

Typical integration paths

• Drop-in UI: Initialize → render card list → open card details (transactions, events, secure card view) → optional theming.
• Headless: Initialize → fetch cards → select card → fetch transactions/events/TOTP → render your own UI → optionally use bitmap/card views for secure fields.

Where to go next

• Setup: Platform-specific setup pages (repos, dependencies, permissions).
• Initialize: Platform-specific initialization guides for token/env + MCD bootstrap.
• Card List / Card Details / Transaction History: UI microfrontends and customization.
• Data APIs (Headless): How to fetch cards, history, TOTP, and secure images without the UI kit.