Connecting to the terminal service

Connecting to the Terminal service

Once the SDK is initialized, your app must explicitly bind to the SoftPOS service before any payment, config, batch, or identification operation can be invoked. Connection is asynchronous and returns information about the negotiated API version.

1. Connect (Kotlin coroutines)

kotlin

val sdk = (application as MyApplication).atiSdk

lifecycleScope.launch {
    try {
        val info = sdk.connect()
        val apiVersion = info.apiVersion
        // SDK is ready
    } catch (error: AtiSdkException) {
        // Handle connection failure (service not installed, permission missing, bind rejected)
    }
}

2. Connect (Java callback)

java

sdk.connect(new TerminalCallback<AtiConnectionInfo>() {
    @Override
    public void onSuccess(AtiConnectionInfo info) {
        int apiVersion = info.getApiVersion();
        // SDK is ready
    }

    @Override
    public void onFailure(TerminalException error) {
        // Handle connection failure
    }
});

3. Disconnect when finished

Release the bind when your integration no longer needs the Terminal service — typically when the user logs out or the payment surface is dismissed:

kotlin

sdk.disconnect()

The SDK does not auto-disconnect. Long-lived idle connections waste a service binding; reconnect on demand if your app has long quiet periods.

When to connect

Connect on first use of the payment surface, not at app launch. Cold-starting a bind before the user needs it slows startup and may fail if the SoftPOS app is updating.
Connect once per session. The result is cached internally; subsequent calls return quickly.
Always check the negotiated apiVersion and gate features your app uses against it. The Terminal API is in active development and capability surfaces may differ between versions.

Connection failure modes

SoftPOS app not installed or not yet activated: bind fails. Prompt the user to complete steps 2 and 3 of the happy path.
Permission missing or <queries> block absent: bind is rejected silently on Android 11+. Verify the manifest setup.
SoftPOS service updating or restarting: transient failure. Retry with backoff.
API version mismatch: the connected service may not support your SDK version. Check apiVersion and surface a clear update message.

Error handling

AtiSdkException covers connection state and lower-level setup failures (no service, bind refused, SDK not initialized).
TerminalException is reported from Terminal calls themselves once connected — handle it on each operation, not on connect() in the Kotlin coroutine style.

Recommended pattern

Wrap connect/disconnect around the lifecycle of the payment-capable screen, not the whole app:

kotlin

class CheckoutActivity : AppCompatActivity() {
    private val sdk by lazy { (application as MyApplication).atiSdk }

    override fun onStart() {
        super.onStart()
        lifecycleScope.launch {
            runCatching { sdk.connect() }
                .onFailure { /* show error */ }
        }
    }

    override fun onStop() {
        sdk.disconnect()
        super.onStop()
    }
}

For the full AtiConnectionInfo schema and version compatibility matrix, see the Terminal API reference.

Connecting to the Terminal service​

Connecting to the Terminal service