Android Quickstart

Run a first standard merchant checkout in UAT using Android SDK 1.0.7 from Maven Central. Enrollment is an explicit step after login and location selection.

1. Prepare the Merchant

Follow Merchant Setup in the Dashboard or Merchant Setup via API. You need a merchant, a terminal with assigned UAT processor credentials, a linked location, merchant code/PIN, and the SDK client key assigned for your app.

Check: the selected processor configuration and credentials belong to the same environment as the merchant and SDK key.

2. Prepare a Supported Device

Use a supported physical NFC device with Android 13 or later. Install Visa Tap to Pay Ready 25.06.10 or later using Google Play or the optional in-app install action.

The host app must declare the KiC package visibility query for com.visa.kic.app.kernel. Follow Permissions and Package Visibility when integrating into your own app.

Check: the device meets the supported-device requirements and the kernel app is installed. An emulator cannot perform the contactless test.

3. Configure and Install the Public Demo

Follow the 1.0.7 Demo Setup:

git clone --branch release/1.0.7 https://github.com/koardlabs/koard-android.git
cd koard-android

Open the root project in Android Studio. Resolve com.koard:koard-android-sdk:1.0.7 from Maven Central using the demo guide's repository setup. Configure the UAT API_KEY and ENVIRONMENT build fields, then select uatDebug. Merchant code/PIN are entered at runtime, not embedded in Gradle.

Enable developer options/USB debugging only for installation or updating. Build and install the UAT demo on the physical device. No SDK source module or local Maven mirror is required.

4. Disable Developer Mode

Disable Android developer options before enrollment or payments, then reopen the demo and allow its readiness checks to refresh. A location change on an already-enrolled device also requires developer mode to be off.

Check: the app's readiness state no longer reports developer mode enabled. Every USB-installed update needs this check again.

5. Log In, Choose a Location, and Enroll

1. Enter the merchant code/PIN and confirm login succeeds.
2. Select the merchant's active location. Your app must also provide this selector in settings and display the selection during checkout.
3. If the device is not enrolled, press Enroll Device. Login and location selection do not enroll it automatically.
4. Wait for enrollment to reach Enrolled and readiness to report isReadyForTransactions.

Use the Location and Enrollment Implementation in your own app. Keep suspend SDK calls on a worker thread, register the hosting activity for NFC, and update UI on Main.

For an already-enrolled device, inspect its readiness rather than enrolling again. Changing to a different merchant requires the documented unenrollment flow; see SDK Lifecycle.

6. Take the Assigned Test Payment

Enter the amount and choose sale or preauth. Use the contactless test card or wallet token assigned by your processor/network for this environment; a keyed PAN/CVV is not reader data.

Use the canonical Sale Session and Response Handling when integrating your app. Save the operation ID before a method that accepts eventId, collect the reader flow, and inspect the returned transaction and amounts. A terminal reader event does not always mean the payment succeeded.

Handle partial approval, surcharge confirmation, declines, cancellation, missing results, and pending outcomes. Preserve coroutine cancellation. Do not automatically submit another charge after a timeout.

7. Verify the Outcome

Check the transaction in Koard UAT. Compare its merchant, location, status, amount, and identifiers with the app result. Follow Outcome Recovery for an uncertain result, and verify webhooks and settlement.

Next Steps

• Install the SDK in your app and implement the full payment flow.
• Use Response Codes and Troubleshooting for readiness or enrollment failures.
• Complete Android Production Deployment and the Launch Checklist.