Getting Started

Learn how to integrate our SDK into your Android project by starting with the correct environment setup.

Video Tutorial

Prefer watching over reading? Check out our SDK integration videos:

Requirements

Our SDK is currently compatible with the following minimum versions:

Component	Version(s)	Notes
minSdkVersion	23	If you need API 21 support, please contact us (see below how)
compileSdkVersion	37
Android Gradle Plugin	8.13.2	8.13.2 or newer
Gradle	8.13
Kotlin	2.3.0	Required only if already using Kotlin

Using Older Versions?

If you're using older versions and cannot upgrade, please contact your partnership manager or email us at partnersupport@teya.com and make sure to include the below information.

The current versions of your android tools (compile SDK, min SDK, AGP and Kotlin)
Any more useful information for the reason for not upgrading to the supported versions.

Your input helps us better understand real-world constraints so we can keep improving accordingly.

1. Get the SDK

Make sure your settings.gradle(.kts) includes the appropriate repository:

dependencyResolutionManagement {
    repositories {
        mavenCentral()
    }
}

Then, to include our SDK in your Android project, add the dependency for your chosen API style to your build.gradle(.kts) file:

Kotlin (callbacks)

dependencies {
    // ...
    implementation("com.teya.epos:unified-sdk:<version>")
}

Kotlin (coroutines)

dependencies {
    // ...
    implementation("com.teya.epos:unified-sdk-poslink-kt:<version>")
}

Replacing <version> with this one:

2. Get Your Client Credentials

You will need your Client ID and Client Secret, which can be obtained from your developer portal. See Setup & Authentication for what these credentials mean and where to get them.

3. Create the `TeyaPosLinkSDK` Instance

Initialize the SDK with your credentials and optional parameters:

Kotlin (callbacks)

val teyaPosLinkSDK = TeyaPosLinkSDK(
    isProductionEnv = false, // Set to true for production
    authConfig = PosLinkSDK.AuthConfig.Managed(
        clientId = "", // Replace with your Client ID
        clientSecret = "" // Replace with your Client Secret
    ),
    eposInstanceId = null, // Optional: identifier for your ePOS app instance
    logger = LoggerImpl()   // Optional: your custom logger implementation
)

Kotlin (coroutines)

val teyaPosLinkSDK = initTeyaPosLinkSDK(
    authConfig = PosLinkAuthConfig.Managed(
        clientId = "", // Replace with your Client ID
        clientSecret = "" // Replace with your Client Secret
    ),
    isProductionEnv = false, // Set to true for production
    eposInstanceId = null, // Optional: identifier for your ePOS app instance
    logger = LoggerImpl()   // Optional: your custom logger implementation
)

Java

// Create the authentication configuration
PosLinkSDK.AuthConfig authConfig = new PosLinkSDK.AuthConfig.Managed(
        "", // Replace with your Client ID
        "" // Replace with your Client Secret
);

// Initialize the TeyaPosLinkSDK
PosLinkSDK teyaPosLinkSDK = TeyaPosLinkSDK.init(
        authConfig, // Authentication config
        false, // isProductionEnv: set to true for production
        null, // Optional: ePOS instance ID
        new LoggerImpl() // Optional: your custom logger implementation
);

Make sure you are pointing to the Development environment when implementing the SDK. Only switch to Production once your integration is well tested

4. Add Custom Logging

To enable logging, you can pass a custom logger by implementing the Logger interface.

Kotlin

class LoggerImpl : Logger {
    override fun d(message: String) {
        Log.d("SDK", message)
    }

    override fun i(message: String) {
        Log.i("SDK", message)
    }

    override fun w(message: String) {
        Log.w("SDK", message)
    }

    override fun e(message: String) {
        Log.e("SDK", message)
    }
}

Java

class LoggerImpl implements Logger {
    @Override
    public void d(@NonNull String message) {
        Log.d("SDK", message);
    }

    @Override
    public void i(@NonNull String message) {
        Log.i("SDK", message);
    }

    @Override
    public void w(@NonNull String message) {
        Log.w("SDK", message);
    }

    @Override
    public void e(@NonNull String message) {
        Log.e("SDK", message);
    }
}

See Debug, Info, Warning, Error for what each log level means.

5. Set up the SDK

Use setup to run the SDK's built-in authentication, store selection, and card machine selection UI (see Setup & Authentication for what this covers). After successful setup, you can call functions on transactionsApi and printingApi.

Kotlin (callbacks)

teyaPosLinkSDK.setup(
    onFailure = {
        // Handle initialization failure
    },
    onSuccess = {
        // Initialization succeeded: you can now use the transactionsApi and printingApi APIs.

        teyaPosLinkSDK.transactionsApi. // Call functions on TeyaCommonTransactionsApi
        teyaPosLinkSDK.printingApi. // Call functions on TeyaCommonPrintingApi
    }
)

Kotlin (coroutines)

teyaPosLinkSDK.setup()
    .onOk {
        // Setup succeeded: you can now use the transactions and printing APIs.

        teyaPosLinkSDK.transactions. // Call functions on PosLinkTransactions
        teyaPosLinkSDK.printing. // Call functions on TeyaPrinting
    }
    .onErr { failure ->
        // Handle setup failure - see PosLinkSetupFailure
        println("Setup failed: $failure ${failure.debugMessage}")
    }

Java

teyaPosLinkSDK.setup(
        failure -> {
            // Handle initialization failure
            return Unit.INSTANCE;
        },
        () -> {
            // Initialization succeeded: you can now use the APIs.

            teyaPosLinkSDK.getTransactionsApi(). // Call functions on TeyaCommonTransactionsApi
            teyaPosLinkSDK.getPrintingApi(). // Call functions on TeyaCommonPrintingApi

            return Unit.INSTANCE;
        }
);

This setup call is required every time you want to access the TeyaCommonTransactionsApi and TeyaCommonPrintingApi.
If the user is already authenticated and linked, the SDK will skip any UI and automatically load credentials from disk.

Managing the device link

Set up without card machine linking

Use setupAuthAndStore to defer card machine selection (see Setup & Authentication) and link one later with linkTerminal.

Kotlin (callbacks)

teyaPosLinkSDK.setupAuthAndStore(
    onFailure = {
        // Handle setup failure
    },
    onSuccess = {
        // Authentication and store linking succeeded.
        // Call linkTerminal before making payments.
    }
)

Kotlin (coroutines)

teyaPosLinkSDK.setupAuthAndStore()
    .onOk {
        // Authentication and store linking succeeded.
        // Call linkTerminal before making payments.
    }
    .onErr { failure ->
        // Handle setup failure - see PosLinkSetupFailure
    }

Java

teyaPosLinkSDK.setupAuthAndStore(
        failure -> {
            // Handle setup failure
            return Unit.INSTANCE;
        },
        () -> {
            // Authentication and store linking succeeded.
            // Call linkTerminal before making payments.
            return Unit.INSTANCE;
        }
);

After setupAuthAndStore succeeds, linkedDeviceDetails will be null (no terminal linked yet) but linkedStore will reflect the linked store.
You must call linkTerminal before using transactionsApi or printingApi.

Linked device details

To retrieve the currently linked device details, you can access the LinkedDeviceDetails, which contains the relevant information.

Kotlin (callbacks)

teyaPosLinkSDK.linkedDeviceDetails // non-null only when both store and terminal are linked
teyaPosLinkSDK.linkedStore         // non-null when a store is linked
teyaPosLinkSDK.linkedTerminal      // non-null when a terminal is linked

Kotlin (coroutines)

teyaPosLinkSDK.linkedStore.value    // non-null when a store is linked
teyaPosLinkSDK.linkedTerminal.value // non-null when a terminal is linked

teyaPosLinkSDK.linkedStore.collect { store ->
    // null until a store is linked, non-null afterwards
}
teyaPosLinkSDK.linkedTerminal.collect { terminal ->
    // null until a terminal is linked, non-null afterwards
}

Java

teyaPosLinkSDK.getLinkedDeviceDetails(); // non-null only when both store and terminal are linked
teyaPosLinkSDK.getLinkedStore();         // non-null when a store is linked
teyaPosLinkSDK.getLinkedTerminal();      // non-null when a terminal is linked

The LinkedDeviceDetails contains information about your selected Terminal and Store. It is only non-null when both are linked.

The coroutines API has no linkedDeviceDetails. Because linkedStore and linkedTerminal are StateFlows you can observe them directly — the device is fully linked when both hold a non-null value.

Get card machines

Retrieve the card machines for the currently linked store with getTerminals. Pass forceRefresh = true to bypass the cache and fetch from the network, or forceRefresh = false to use cached results.

Kotlin (callbacks)

teyaPosLinkSDK.getTerminals(
    forceRefresh = false,
    onFailure = { failure ->
        // Handle failure - check failure.reason and failure.debugErrorMessage
    },
    onSuccess = { terminals ->
        // list of terminals
    }
)

Kotlin (coroutines)

teyaPosLinkSDK.getTerminals(forceRefresh = false)
    .onOk { terminals ->
        // list of terminals
    }
    .onErr {
        // Handle failure
    }

Java

teyaPosLinkSDK.getTerminals(
        failure -> {
            // Handle failure - check failure.getReason() and failure.getDebugErrorMessage()
            return Unit.INSTANCE;
        },
        terminals -> {
            // list of terminals
            return Unit.INSTANCE;
        },
        false // forceRefresh
);

Link card machine

Use linkTerminal to switch card machines (see Setup & Authentication). Pass a specific card machine ID (e.g. one returned by getTerminals), or null to show the SDK's built-in selection UI.

Kotlin (callbacks)

// Option 1: Show the terminal selection UI
teyaPosLinkSDK.linkTerminal(
    terminalId = null,
    onFailure = { failure ->
        // Handle failure - check failure.reason and failure.debugErrorMessage
    },
    onSuccess = { terminal ->
        // terminal - the newly linked terminal
    }
)

// Option 2: Link directly by terminal ID
teyaPosLinkSDK.linkTerminal(
    terminalId = "terminal-id-from-getTerminals",
    onFailure = { failure ->
        // Handle failure
    },
    onSuccess = { terminal ->
        // terminal - the newly linked terminal
    }
)

Kotlin (coroutines)

// Option 1: Show the terminal selection UI
teyaPosLinkSDK.linkTerminal(terminalId = null)
    .onOk { terminal ->
        // terminal - the newly linked terminal
    }
    .onErr { failure ->
        println("Could not link terminal: $failure ${failure.debugMessage}")
    }

// Option 2: Link directly by terminal ID
teyaPosLinkSDK.linkTerminal(terminalId = "terminal-id-from-getTerminals")
    .onOk { terminal ->
        // terminal - the newly linked terminal
    }
    .onErr { failure ->
        // Handle failure
    }

Java

// Option 1: Show the terminal selection UI
teyaPosLinkSDK.linkTerminal(
        null, // terminalId - null shows the selection UI
        terminal -> {
            // terminal - the newly linked terminal
            return Unit.INSTANCE;
        },
        failure -> {
            // Handle failure - check failure.getReason() and failure.getDebugErrorMessage()
            return Unit.INSTANCE;
        }
);

// Option 2: Link directly by terminal ID
teyaPosLinkSDK.linkTerminal(
        "terminal-id-from-getTerminals",
        terminal -> {
            // terminal - the newly linked terminal
            return Unit.INSTANCE;
        },
        failure -> {
            // Handle failure
            return Unit.INSTANCE;
        }
);

Clearing auth and device details

clearUserAuth clears authentication and the device link (see Setup & Authentication):

Kotlin (callbacks)

teyaPosLinkSDK.clearUserAuth()

Kotlin (coroutines)

teyaPosLinkSDK.clearUserAuth()

Java

teyaPosLinkSDK.clearUserAuth();

clearDeviceLink clears only the store and card machine link, preserving authentication:

Kotlin (callbacks)

teyaPosLinkSDK.clearDeviceLink()

Kotlin (coroutines)

teyaPosLinkSDK.clearDeviceLink()

Java

teyaPosLinkSDK.clearDeviceLink();

Note

After calling either clearUserAuth or clearDeviceLink, you must call setup again before performing any operations with the SDK.

Sample app

A complete Android sample application demonstrating POSLink integration with the Teya Unified ePOS SDK. This app shows how to connect an Android ePOS application to a separate Teya payment card machine over the cloud.

This sample app is a reference implementation for learning and development purposes. It is not intended for production use.

View on GitHub

Getting Started

Requirements

Using Older Versions?

1. Get the SDK

2. Get Your Client Credentials

3. Create the TeyaPosLinkSDK Instance

4. Add Custom Logging

5. Set up the SDK

Managing the device link

Set up without card machine linking

Linked device details

Get card machines

Link card machine

Clearing auth and device details

Sample app

3. Create the `TeyaPosLinkSDK` Instance