Demo

Setup

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

android {
    defaultConfig {
        buildConfigField("String", "API_KEY", "\"YOUR_API_KEY_HERE\"")
        buildConfigField("String", "MERCHANT_CODE", "\"YOUR_MERCHANT_CODE_HERE\"")
        buildConfigField("String", "MERCHANT_PIN", "\"YOUR_MERCHANT_PIN_HERE\"")
        buildConfigField("String", "STORE_ID", "\"YOUR_STORE_ID_HERE\"")
    }
}

# Build development flavor
./gradlew assembleDevDebug

# Build UAT flavor
./gradlew assembleUatDebug

# Build production flavor
./gradlew assembleProdRelease

# Install development build
./gradlew installDevDebug

# Install UAT build
./gradlew installUatDebug

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-demo/
├── src/
│   └── main/
│       ├── java/com/koard/android/
│       │   ├── DemoApplication.kt
│       │   ├── MainActivity.kt
│       │   └── ui/
│       ├── res/
│       └── AndroidManifest.xml
├── libs/                           # Embedded SDK AARs (dev/uat/prod)
├── libs-maven/                     # Local Maven repo for the SDK fat AAR
├── build.gradle.kts                # Build configuration
├── settings.gradle.kts
└── README.md

SDK Integration

The demo app uses the Koard Android SDK embedded as "fat AAR" files. These artifacts already bundle the SDK along with the tap-to-pay thin client and shared libraries, so you only need to reference the single AAR per environment.

The SDK is automatically selected based on your build flavor:

• Dev builds → Use koard-android-dev-release.aar
• UAT builds → Use koard-android-uat-release.aar
• Prod builds → Use koard-android-prod-release.aar

Build Commands Reference

# Clean build
./gradlew clean

# Build all flavors
./gradlew build

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

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

# Uninstall from device
./gradlew uninstallDevDebug
./gradlew uninstallUat

# 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)
• The SDK automatically handles device enrollment after successful merchant login
• 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 (dev/uat/prod)

Debugging Tips

Enable verbose logging:

Add this to see detailed SDK logs:

import android.util.Log

// In your Application or Activity
KoardMerchantSdk.getInstance().apply {
    // Enable debug logging if available
}

Check Logcat:

Filter by package name to see app-specific logs:

adb logcat | grep "com.koardlabs"

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

To update to a newer version of the SDK in the demo app:

1. Download the latest Koard Android SDK fat AAR.
2. Copy the resulting AAR into libs/ (or publish them into libs-maven/) inside the koard-android-demo project.
3. Rebuild the demo app.

Next Steps

After running the demo app successfully:

• Install SDK in Your App - Integrate SDK into your own application
• Merchant Authentication - Implement login flows
• Transaction Processing - Process payments
• Payment Lifecycle - Understand payment flows
• Error Handling - Handle SDK errors gracefully

Support

For technical support or questions:

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