Adding the Terminal API to your project

The Terminal API is consumed as an Android library, distributed via Maven Central. Integration requires a Gradle dependency, a manifest declaration, and an application-scoped SDK instance.

1. Add the Gradle dependency

In your root settings.gradle.kts, make sure Google's Android repository and Maven Central are configured:

kotlin

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
    }
}

In your app module's build.gradle.kts:

kotlin

dependencies {
    implementation("com.wallee.terminal:terminal-api:<version>")
}

Replace <version> with the Terminal API SDK version provided by your wallee contact. No GitHub Packages or registry credentials are required.

2. Declare the permission and package visibility

The integrator app needs permission to access the Terminal service, plus Android 11+ package visibility for the SoftPOS app. Add both to your AndroidManifest.xml:

xml

<uses-permission android:name="com.wallee.atisdk.permission.ACCESS_ATI_SERVICE" />

<queries>
    <package android:name="com.wallee.softpos" />
    <intent>
        <action android:name="com.wallee.atisdk.action.BIND_TERMINAL_SERVICE" />
    </intent>
</queries>

Without the <queries> block, your app will not be able to discover or bind to the SoftPOS service on Android 11 or higher.

3. Create an application-scoped SDK instance

The SDK should live for the lifetime of the application process, not per Activity. Hold it on your Application subclass:

kotlin

class MyApplication : Application() {
    val atiSdk: AtiSdk by lazy {
        AtiSdkClient(this)
    }
}

Register the class in your manifest:

xml

<application
    android:name=".MyApplication"
    ...>
</application>

4. Verify the setup

Build and run the app on a device that has the SoftPOS sandbox installed (see step 2 of the happy path). The SDK instance is now ready to connect — covered in step 4.

Common pitfalls

• Missing <queries> block: binding silently fails on Android 11+ because the SoftPOS package is invisible to your app.
• SDK held in an Activity scope: connection state is lost on configuration changes; always scope to Application.
• Permission not declared: the bind attempt will be rejected by the SoftPOS service.
• SoftPOS app not installed: there is no service to bind to. Install the wallee SoftPOS APK first.
• Wrong artifact coordinates: the group is com.wallee.terminal, the artifact is terminal-api.

For the full class reference and constructor options, see the Terminal API reference.