Demo

Setup

To run the demo app, you need to get the project and configure your API credentials:

android {
    flavorDimensions += "environment"

    productFlavors {
        create("uat") {
            dimension = "environment"
            isDefault = true
            buildConfigField("String", "ENVIRONMENT", "\"UAT\"")
            buildConfigField("String", "API_KEY", "\"YOUR_API_KEY\"")
            applicationIdSuffix = ".uat"
        }
        create("prod") {
            dimension = "environment"
            buildConfigField("String", "ENVIRONMENT", "\"PROD\"")
            buildConfigField("String", "API_KEY", "\"YOUR_API_KEY\"")
        }
    }
}

# Build UAT flavor
./gradlew assembleUatDebug

# Build production flavor
./gradlew assembleProdRelease

# Install UAT build
./gradlew installUatDebug

# Install production build
./gradlew installProdRelease

Running the Demo

Demo App Features

The demo app showcases the following SDK capabilities:

Merchant Authentication

• Login with merchant code and PIN
• Session management
• Automatic token refresh

Device Enrollment

• NFC configuration with Koard's tap-to-pay services
• Certificate management
• Device provisioning status

Location Management

• Retrieve all merchant locations
• Select active location
• Location-based transaction processing

Transaction Processing

• Sale transactions (immediate capture)
• Preauthorization (auth hold)
• Capture (settle preauth)
• Refund processing
• Transaction reversal
• Tip adjustment

Transaction History

• List all transactions
• View transaction details
• Filter and search
• Transaction status tracking

Digital Receipts

• Send receipts via email
• Send receipts via SMS
• Receipt customization

Project Structure

The demo app structure:

koard-android/
├── src/
│   └── main/
│       ├── java/com/koard/android/
│       │   ├── DemoApplication.kt          # SDK initialization
│       │   ├── MainActivity.kt             # NFC register/unregister in onResume/onPause
│       │   ├── navigation/                 # Tab navigation (History, Home, Settings)
│       │   └── ui/
│       │       ├── LoginScreen.kt / LoginViewModel.kt
│       │       ├── MainScreen.kt / MainScreenViewModel.kt
│       │       ├── SettingsScreen.kt
│       │       ├── TransactionDetailsScreen.kt
│       │       └── TransactionHistoryScreen.kt
│       ├── res/
│       │   └── xml/nfc_tech_filter.xml     # IsoDep tech filter for TECH_DISCOVERED
│       └── AndroidManifest.xml
├── build.gradle.kts                # Build configuration + SDK coordinate
├── settings.gradle.kts             # google() + mavenCentral() only
└── README.md

SDK Integration

The demo resolves the SDK straight from Maven Central — there is no bundled AAR and no local repository to configure:

// build.gradle.kts
implementation("com.koard:koard-android-sdk:1.0.6")

The published artifact is a shaded fat AAR: it bundles the tap-to-pay engine (KiC) and relocates OkHttp, Okio, Retrofit, kotlinx.serialization, and Ktor under com.koardlabs.*, so those never clash with your app's own versions. It also means they are not transitive dependencies — see Installing the SDK for what you must declare yourself.

The environment (UAT vs. PROD) is chosen at runtime from the flavor's ENVIRONMENT buildConfigField, not by swapping artifacts:

• UAT builds → KoardEnvironment.UAT
• Prod builds → KoardEnvironment.PROD

How the Demo Initializes the SDK

DemoApplication.onCreate() maps BuildConfig.ENVIRONMENT to a KoardEnvironment and initializes the SDK on a worker thread, passing the API key from BuildConfig:

val environment = when (BuildConfig.ENVIRONMENT) {
    "PROD" -> KoardEnvironment.PROD
    "UAT" -> KoardEnvironment.UAT
    else -> KoardEnvironment.UAT
}

KoardMerchantSdk.initialize(
    application = this@DemoApplication,
    apiKey = BuildConfig.API_KEY,
    environment = environment,
    timeoutSeconds = 30L
)

Merchant credentials are supplied later, on the login screen, via sdk.login(merchantCode, merchantPin).

Build Commands Reference

# Clean build
./gradlew clean

# Build all flavors
./gradlew build

# Build specific flavor
./gradlew assembleUatDebug
./gradlew assembleProdRelease

# Install on device
./gradlew installUatDebug
./gradlew installProdRelease

# Uninstall from device
./gradlew uninstallUatDebug
./gradlew uninstallProd

# Run tests
./gradlew test

# Generate APK
./gradlew assembleDebug
./gradlew assembleRelease

Troubleshooting

Common Issues

App crashes on startup

Solution:

• Verify credentials are configured correctly in build.gradle.kts
• Check that you're not using placeholder values (YOUR_API_KEY_HERE)
• Review Logcat for specific error messages

"Device not provisioned" error

Solution:

• Ensure the tap-to-pay kernel app is installed (see the Running Payments guide for setup steps)
• Confirm you selected a location and then pressed Enroll Device — enrollment never runs on its own
• Check NFC hardware is functioning
• Verify the kernel app is up to date

NFC not working

Solution:

• Confirm device has NFC hardware
• Enable NFC in device settings
• Verify device enrollment was successful
• Test with a physical payment card
• IMPORTANT: Ensure developer mode is DISABLED on the device

"Transaction failed" or "NFC error" during tap to pay

Solution:

• Disable developer mode - This is the most common cause of transaction failures
• Go to Settings > System > Developer Options and toggle OFF
• Restart your device after disabling developer mode
• Ensure the tap-to-pay kernel app is running and up to date
• Check that NFC is enabled in device settings

Build errors

Solution:

• Verify JDK 21 is configured
• Check minimum SDK is set to 31
• Clean and rebuild: ./gradlew clean build
• Invalidate caches: File > Invalidate Caches / Restart

Network errors

Solution:

• Check device has internet connection
• Verify API key and credentials are correct
• Ensure you're using the correct build flavor for your environment (uat/prod)

Debugging Tips

Enable verbose logging:

SDK log verbosity is set once, at initialization — there is no runtime setter. Pass a KoardLogLevel in DemoApplication.onCreate():

import com.koardlabs.merchant.sdk.domain.KoardLogLevel

KoardMerchantSdk.initialize(
    application = this@DemoApplication,
    apiKey = BuildConfig.API_KEY,
    environment = environment,
    timeoutSeconds = 30L,
    logLevel = KoardLogLevel.VERBOSE
)

Levels are VERBOSE, DEBUG, INFO, WARN, ERROR, and NONE. The default is DEBUG in debug builds and NONE in release, and the level applies in release builds too if you opt in. Secrets — API key and token headers, device certificates, and enrollment key material — are never logged at any level.

Check Logcat:

The SDK logs under the fixed tag KoardSDK:

adb logcat -s KoardSDK

Verify SDK version:

Check which SDK version the demo is using:

./gradlew dependencies | grep koard

Security Notes

• Never commit actual credentials to version control
• Use environment variables or secure credential management for production
• The build.gradle.kts credentials are for demo purposes only
• Consider using Android Keystore for sensitive data in production apps
• Keep the demo app on devices used exclusively for testing

Updating the SDK

Updating the SDK is a one-line change — bump the Maven coordinate in build.gradle.kts and rebuild:

implementation("com.koard:koard-android-sdk:<version>")

There is no AAR to download or copy: the artifact resolves from mavenCentral(), which settings.gradle.kts already declares.

Next Steps

After running the demo app successfully:

• Install SDK in Your App - Integrate SDK into your own application, including login, location selection, and enrollment
• Running Payments - Drive tap-to-pay sessions and post-reader operations
• SDK Response Codes - Understand transaction outcomes, error codes, and error handling
• Payment Lifecycle - Understand payment flows
• Supported Devices & NFC Tap Location - Device compatibility and where to tap
• Troubleshooting - Fix enrollment failures and taps that cancel instantly

Support

For technical support or questions:

• Email: support@koard.com
• Documentation: https://docs.koard.com
• GitHub Issues: https://github.com/koardlabs/koard-android/issues