Credit Cards

Kotlin Credit Cards Mobile SDK Integration Guide

Overview

The Credit Cards vertical is delivered through Engine's Web Wrapper SDK for Android. This guide covers installation, prerequisites, the core configuration props (channel, zone, productTypes), a basic usage example, prefilling lead data, client tags, and event handlers.

You'll need the correct channel and zone values for your integration. Ask your Partner Manager to provide these values for Credit Cards.

Before you start, request an API token from your Partner Manager. It authenticates with the Engine API and is required to use the Prefill API. You may want multiple tokens depending on how many entry points your app has into the SDK.

Requirements

• Android project built with Gradle

• minSdk 24 or higher

Install

The SDK is published to GitHub Packages, so a GitHub Personal Access Token (PAT) is required to download it.

1. Create a GitHub PAT

In GitHub, go to Settings → Developer settings → Personal access tokens and create a token with at least the read:packages scope. When authenticating, use your GitHub username and the PAT as the password (not your GitHub login password).

2. Store credentials outside the repo

Either store them user-level in ~/.gradle/gradle.properties:

gpr.user=YOUR_GITHUB_USERNAME
gpr.token=YOUR_GITHUB_PAT

or as environment variables:

export GPR_USER=YOUR_GITHUB_USERNAME
export GPR_TOKEN=YOUR_GITHUB_PAT

3. Add the GitHub Packages repository

Add the maven block inside dependencyResolutionManagement.repositories in settings.gradle.kts:

dependencyResolutionManagement {
    // Forces all repos here (not in app/build.gradle.kts)
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()

        // Private GitHub Packages — where kotlin-wrapper-sdk is hosted
        maven {
            // Local label for logs/errors only; not sent to GitHub
            name = "GhPkgA"
            url = uri("https://maven.pkg.github.com/MoneyLion/engine-mobile-native-sdk")
            credentials {
                username = providers.gradleProperty("gpr.user")
                    .orElse(providers.environmentVariable("GPR_USER"))
                    .get()
                password = providers.gradleProperty("gpr.token")
                    .orElse(providers.environmentVariable("GPR_TOKEN"))
                    .get()
            }
        }
    }
}

4. Add the dependency

Add this line inside dependencies { ... } in app/build.gradle.kts (use the latest published release):

dependencies {
    implementation("com.engine.mobile.sdk:kotlin-wrapper-sdk:0.0.2")
}

5. Sync / verify

./gradlew :app:dependencies --configuration releaseRuntimeClasspath

Confirm com.engine.mobile.sdk:kotlin-wrapper-sdk:0.0.2 appears in the tree.

Initialize

Import the SDK where you render the Engine flow:

import com.engine.mobile.sdk.EngineSDK
import com.engine.mobile.sdk.ProductType

Basic Example

EngineSDK extends FrameLayout, so construct it in code and add it to any container. Use listOf(ProductType.CreditCard) for productTypes to render the Credit Cards flow. Your channel and zone values are provided by your Partner Manager.

val sdk = EngineSDK(
    context = this,
    channel = "your-channel",
    zone = "your-zone",
    productTypes = listOf(ProductType.CreditCard),
    onExit = {
        // handle exit / navigation
    },
    // ...optional event handlers, see Event Handlers
)

container.addView(sdk)

Properties

Prop	Type	Required	Description
channel	String	Yes	Identifies your integration in Engine. Provided by your Partner Manager (e.g. "direct").
zone	String	Yes	Identifies the placement or distribution surface for the SDK. Provided by your Partner Manager (e.g. "marketplace").
productTypes	List<ProductType>	Yes	Product flow(s) to render. Use listOf(ProductType.CreditCard) for Credit Cards.
bearerToken	String?	For prefill	API token from your Partner Manager. Required to use the Prefill API. Without it, the standard non-prefilled flow renders.
isDev	Boolean	No	When true, the SDK targets Engine's dev/staging hosts. Defaults to false (production).
personalInformation, financialInformation, creditInformation, creditCardInformation	Lead*Information?	No	Prefill data. See Prefilling Lead Data.
clientTags	Map<String, List<String>>?	No	Reporting/attribution tags. See Client Tags.
onExit	(ExitEvent) -> Unit	Yes	Fired when the user exits the flow.
onInitialize, onCreate, onUpdate, onNavigate, onSubmit, onRateTableRender, onOfferClick, onErrorPageView, onErrorPageRetry, onEmbedError, onEmbedErrorRetry	Callbacks	No	Optional tracking hooks. See Event Handlers.

Prefilling Lead Data

Prefill any user data you already have to reduce what the user has to type in-flow. Prefilled data is grouped into typed information objects, each passed as its own argument on EngineSDK (e.g. personalInformation, financialInformation, creditInformation, creditCardInformation).

Prefilling requires a bearerToken. Pass only the fields you have — omitted fields are collected from the user in-flow.

Example

val sdk = EngineSDK(
    context = this,
    channel = "your-channel",
    zone = "your-zone",
    bearerToken = "{your_token}",
    productTypes = listOf(ProductType.CreditCard),
    personalInformation = LeadPersonalInformation(
        firstName = "Bob",
        lastName = "Dylan",
        email = "[email protected]",
        dateOfBirth = LocalDate(1990, 1, 1),
        primaryPhone = "2325624852",
        address1 = "1600 Pennsylvania Avenue",
        address2 = "Apt 2",
        city = "Washington",
        state = State.DC,
        zipcode = "20500",
    ),
    financialInformation = LeadFinancialInformation(
        annualIncome = 20000,
        creditCardDebt = 5000,
    ),
    creditInformation = LeadCreditInformation(
        providedCreditRating = ProvidedCreditRating.Good,
    ),
    creditCardInformation = LeadCreditCardInformation(
        allowAnnualFee = true,
        cardPurposes = listOf(CardPurpose.BalanceTransfer, CardPurpose.CashBack),
    ),
    onExit = {},
)

Type Definitions

Every prop and field is optional — pass only what you have.

class LeadPersonalInformation(
    val firstName: String? = null,
    val lastName: String? = null,
    val email: String? = null,
    val dateOfBirth: LocalDate? = null,
    val primaryPhone: String? = null, // 10 digits, no "+" or "-" chars
    val address1: String? = null,
    val address2: String? = null,     // optional apartment / suite
    val city: String? = null,
    val state: State? = null,         // 2-letter state enum (e.g. State.DC)
    val zipcode: String? = null,
)

class LeadFinancialInformation(
    val annualIncome: Int? = null,   // raw integer value (e.g. 20000)
    val creditCardDebt: Int? = null, // total credit card debt, raw integer value
)

class LeadCreditInformation(
    val providedCreditRating: ProvidedCreditRating? = null,
)

class LeadCreditCardInformation(
    val allowAnnualFee: Boolean? = null,
    val cardPurposes: List<CardPurpose>? = null,
)

Enums / Accepted Values

Fields backed by an enum must use a valid value.

enum class CardPurpose {
    BalanceTransfer,
    CashBack,
    EarningRewards,
    ImproveCredit,
    LowInterest,
    NewToCredit,
    Student,
    TravelIncentives,
}

enum class ProvidedCreditRating {
    Excellent,
    Good,
    Fair,
    Poor,
    Limited,
}

// State is a 2-letter US state enum, e.g. State.CA, State.DC, State.NY

Do not prefill any fields that are empty or unavailable — omit them so the user is prompted in-flow. Prefilled data must match the type definitions above, and any field backed by an enum must use a valid value. If a value is invalid, that attribute is stripped and the user will have to enter it again manually.

Client Tags

The Engine Web Wrapper SDK supports adding your unique Client Tags to track performance of specific campaigns or users. All Client Tag data is attributed to the lead level.

Client Tags are added via the clientTags argument on EngineSDK, a map of string keys to lists of string values. We strongly recommend including only one element per list for ease of reporting and attribution — if you want two separate tags, include the second tag under a different key. There is no limit to the number of keys.

val sdk = EngineSDK(
    context = this,
    channel = "your-channel",
    zone = "your-zone",
    bearerToken = "{your_token}",
    productTypes = listOf(ProductType.CreditCard),
    personalInformation = LeadPersonalInformation(/* ...any data you don't want to ask for again */),
    clientTags = mapOf(
        "clientId" to listOf("client1"),
        "trafficsource" to listOf("email"),
        "campaignId" to listOf("campaign1"),
    ),
    onExit = {},
)

Note: Client Tags are only sent as part of a prefill request. You must provide both a bearerToken and prefill data (via the information props such as personalInformation). If no prefill data is supplied, the SDK makes no prefill call and any clientTags you pass are ignored.

Supported Client Tag Keys for Reporting

If you plan for the Engine team to set up reporting (i.e., you do not plan to hit the Analytics API), these are the only keys that are currently fully supported. If a different key is needed, please reach out to your partner manager.

• agentId

• campaignId

• clientId

• deviceid

• medium

• sourceId

• subid

• subid1

• subid2

• subid3

• target

• trafficsource

• userid

Event Handlers

EngineSDK exposes optional callback arguments that notify your app when key moments occur during the user's journey. Each callback receives an event object containing a timestamp (ISO 8601 UTC) and event-specific fields.

All callbacks are optional. Pass any combination when constructing EngineSDK. If a callback is not provided, the SDK will still log the event to the debug console in development mode.

val sdk = EngineSDK(
    context = this,
    channel = "your-channel",
    zone = "your-zone",
    productTypes = listOf(ProductType.CreditCard),
    onInitialize = { event -> Log.d("Engine", "onInitialize ${event.timestamp}") },
    onCreate = { event -> Log.d("Engine", "onCreate ${event.leadUuid}") },
    onSubmit = { event -> Log.d("Engine", "onSubmit ${event.leadUuid}") },
    onOfferClick = { event -> Log.d("Engine", "onOfferClick ${event.offerUuid}") },
    onExit = {
        // Navigate the user back or perform cleanup
    },
    // ...other callbacks
)

Available Events

Callback	Trigger
onInitialize	SDK finished loading the embed
onCreate	New lead created
onUpdate	Lead data updated
onNavigate	Page navigation within the flow
onSubmit	Lead form submitted
onRateTableRender	Rate table displayed with offers
onOfferClick	User clicked an offer
onErrorPageView	Error page displayed in the flow
onErrorPageRetry	User retried from the error page
onExit	User exited the SDK
onEmbedError	Web embed failed to load
onEmbedErrorRetry	User retried after embed failure

For Credit Cards, onRateTableRender populates creditCardOffers, and onOfferClick includes card-specific fields such as financialInstitutionBrandName, cardName, isITA, and cardNetwork. Every event includes a timestamp (ISO 8601 UTC).