Terminal API SDK for Android

Android SDK for integrating an app with Wallee Terminal API payment flows.

The SDK provides the public AtiSdk entry point and Terminal API domain facades for payments, configuration, batch operations, and identification. Service communication is handled internally by the SDK.

Installation

Binary artifacts are distributed through GitHub Packages. Configure the Wallee Terminal API Maven repository in your Gradle settings:

dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
    repositories {
        google()
        mavenCentral()
        maven {
            name = "GitHubPackages"
            url = uri("https://maven.pkg.github.com/wallee-payment/Terminal-API")
            credentials {
                username = providers.gradleProperty("gpr.user").orNull
                password = providers.gradleProperty("gpr.key").orNull
            }
        }
    }
}

GitHub Packages may require authentication. Use your GitHub username for gpr.user and a GitHub token with package read access for gpr.key.

Add the SDK dependency to your app module:

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

Replace <version> with the version provided by Wallee.

Versioning

Wallee publishes prerelease SDK versions from the dev branch for validation and stable SDK versions from the master branch for production clients.

Use the version provided by Wallee for your integration.

Getting Started

Your app must be able to discover its installed Terminal service host. The SDK defaults to the Wallee SoftPOS package com.wallee.softpos:

<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>

When targeting another supported Terminal service host, add that explicit host package to package visibility. For Paydroid, use com.wallee.android.pinpad. Include every host package your app may configure at runtime. The Terminal service bind action and permission stay the same.

Create the SDK once in an application-scoped holder. This keeps the default SoftPOS host:

val sdk = AtiSdkClient(applicationContext)

To target Paydroid, provide its host package while keeping the same SDK API:

val sdk = AtiSdkClient(
    applicationContext,
    AtiSdkConfig(hostPackageName = AtiSdkConstants.PAYDROID_HOST_PACKAGE),
)

Connect before calling Terminal operations:

lifecycleScope.launch {
    try {
        sdk.connect()
    } catch (error: AtiSdkException) {
        // Show a connection error or ask the user to retry.
    }
}

Purchase Example

Build a purchase request, create a transaction context, then execute the returned transactionId:

val request = TransactionRequest.purchase(
    BaseTransactionRequest.builder()
        .currency("CHF")
        .merchantReference("order-123")
        .addLineItem(
            PaymentLineItem.builder("item-1", BigDecimal("10.00"))
                .name("Demo item")
                .build()
        )
        .build()
)

val context = sdk.terminal.payments.createTransaction(request)
val result = sdk.terminal.payments.executeTransaction(context.transactionId)

when (result.outcome) {
    TransactionOutcome.APPROVED -> {
        val reference = (result as? PurchaseResult)
            ?.transaction
            ?.transactionReferenceNumber
    }
    TransactionOutcome.CANCELLED_BY_USER -> {
        // The user or terminal cancelled the payment flow.
    }
    TransactionOutcome.DECLINED -> {
        // The payment was declined.
    }
    else -> Unit
}

Common Operations

Use cancelTransactionExecution to ask the Terminal service to stop an execution that is still in progress:

val cancellation = sdk.terminal.payments.cancelTransactionExecution(context.transactionId)

TerminalCall.cancel() cancels the local caller handle. It is not the same as a terminal or user cancellation result.

Use getLastResult to recover the most recent final payment result:

val lastResult = sdk.terminal.payments.getLastResult()
if (lastResult.state == LastPaymentResultState.FOUND) {
    val recovered = lastResult.result
}

Configuration and status:

val capabilities = sdk.terminal.config.getCapabilities()
val status = sdk.terminal.config.getTerminalStatus()
val info = sdk.terminal.config.getTerminalInfo()

Batch:

val batchResult = sdk.terminal.batch.processBatch(batchRequest)
val finalBalance = sdk.terminal.batch.executeFinalBalance(finalBalanceRequest)

Identification:

val panHash = sdk.terminal.identification.getPanHash(panHashRequest)

Payment-domain context creation:

val refund = sdk.terminal.payments.createRefund(refundRequest)
val capture = sdk.terminal.payments.createReservationCapture(captureRequest)
val adjustment = sdk.terminal.payments.createReservationAdjustment(adjustmentRequest)
val cancellation = sdk.terminal.payments.createReservationCancellation(cancellationRequest)
val voidContext = sdk.terminal.payments.createVoid(voidRequest)

Each of these operations creates a TransactionContext. Execute the returned transactionId with sdk.terminal.payments.executeTransaction(...).

Terminology

• Payment: API domain grouping for financial terminal operations.
• TransactionContext: executable runtime context created by a payment-domain operation.
• transactionId: runtime context identifier used for execute, cancel, and recovery.
• transactionReferenceNumber: acquirer or payment reference returned after execution. It is not the same as transactionId.
• Reservation: authorization-like hold.
• Capture: completion of a reservation.
• Reservation cancellation: cancellation of a reserved transaction. It is distinct from cancelTransactionExecution.
• Void: payment-domain operation for voiding a previous transaction.

Support

For integration support, SDK access, and recommended production versions, contact Wallee.

Changelog

Public release notes are published in CHANGELOG.md.

License And Legal

This SDK is provided for Wallee Terminal API integrations. License and usage terms are provided by Wallee.