Flute Terminal SDK for Android

The Flute Terminal SDK for Android is a native integration layer for ISV point-of-sale applications running on Flute-provisioned Android terminals. It handles authentication, token management, payment configuration, and the full transaction lifecycle, letting your application focus on business logic rather than payment infrastructure.

The SDK's primary feature is Deeplink Integration, which lets your app initiate a card-present transaction and hand off to the Flute Terminal app on the same device for card collection. Additional features may be added to the SDK over time and documented here as new sections.

The Flute Terminal SDK is the on-device counterpart to the POS Terminal Integration REST flow:

The Flute Terminal SDK is available on Flute's official GitHub. Download the SDK package from the releases page, unzip it next to your project, and register it in settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("../flute-terminal-sdk") }
    }
}

Then add the dependency to your app module:

dependencies {
    implementation("com.flute.terminal:sdk:1.0.0")
}

Third-party dependencies (Retrofit, OkHttp, Coroutines) resolve from Maven Central automatically.

The SDK includes its own consumer ProGuard rules. No additional keep rules are required in your app, and R8 minification can remain enabled on release builds.

Credentials are scoped to one environment. A clientId and clientSecret issued for SANDBOX are rejected on PRODUCTION and vice versa, surfacing as a 401 during initialization.

FluteTerminal.initialize(context, config, onReady)

Call once, typically from Application.onCreate().

FluteTerminal.initialize(
    applicationContext,
    FluteTerminalConfig(
        environment = FluteTerminalConfig.Environment.SANDBOX,
        clientId = BuildConfig.FLUTE_CLIENT_ID,
        clientSecret = BuildConfig.FLUTE_CLIENT_SECRET,
    ),
) { result ->
    when (result) {
        is FluteResult.Success -> Log.i("Flute", "SDK ready")
        is FluteResult.Failure -> Log.e("Flute", "Initialization failed: ${result.error.message}")
    }
}

Initialization runs in the background: it fetches and caches an OAuth token, loads the merchant's payment configuration, identifies the terminal for this device, and keeps the session current automatically. The callback is optional; on-demand calls still work if warm-up is skipped or fails.

FluteTerminalConfig parameters

FluteTerminal.provisionCredentials(clientId, clientSecret, callback)

Supplies or rotates credentials at runtime without a rebuild. The SDK stores them encrypted per environment, invalidates the existing token, and re-warms.

FluteTerminal.provisionCredentials(clientId, clientSecret) { result ->
    // FluteResult.Failure with httpStatus 401 means wrong keys or keys for a different environment
}

FluteTerminal.hasCredentials()

Returns true if this device holds credentials for the selected environment.

val ready = FluteTerminal.hasCredentials()

FluteTerminal.shutdown()

Releases the SDK and stops the token-refresh loop. After calling shutdown(), re-register the payment result launcher before taking new payments.

FluteTerminal.shutdown()

Deeplink Integration is the SDK's mechanism for initiating a card-present transaction directly from your POS application. The SDK launches the Flute Terminal app on the same device to handle card collection, then returns a typed result to your callback once the payment is resolved.

1. Your app calls startPayment() with an amount.
2. The SDK resolves the terminal and currency, then requests the amounts to display (surcharge, cash discount, dual pricing, and tip).
3. The SDK creates the POS transaction through the Flute API.
4. The SDK launches the Flute Terminal app, which collects the card and processes the payment.
5. The Flute Terminal app returns control to your app.
6. The SDK fetches the authoritative transaction outcome from the API and delivers it to your callback.

The result returned to your callback reflects the transaction record as the gateway sees it, not just what the terminal app reported.

parseResult(activityResult) is available as an alternative for apps that handle the ActivityResult directly, bypassing the callback. The callback path is the recommended approach. It is also used for process-death recovery (see Recovery After Process Death).

FluteTerminal.registerForPaymentResult(owner, callback)

Registers the result callback and returns the launcher used to start payments. Must be called before the Activity reaches STARTED, making onCreate() the only safe place.

class CheckoutActivity : ComponentActivity() {
    private lateinit var launcher: FluteTerminalLauncher

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        launcher = FluteTerminal.registerForPaymentResult(this) { result ->
            handleResult(result)
        }
    }
}

The callback fires exactly once per payment, on the main thread, for every outcome: approval, decline, cancellation, timeout, or a failure before the terminal was launched.

launcher.startPayment(PaymentRequest)

launcher.startPayment(
    PaymentRequest.Builder(BigDecimal("25.00"))
        .posDeviceId("TILL-1")
        .referenceId(orderId)
        .build(),
)

PaymentRequest parameters

Only one payment may be in flight at a time. A second call while a payment is running is rejected immediately with ErrorReason.ALREADY_IN_PROGRESS.

When using captureMethod: MANUAL, the transaction is authorized but not captured. Call capture() (see Post-Payment Operations) to settle the funds.

launcher.startRefund(RefundRequest)

Initiates an unreferenced refund: funds are returned to whatever card the customer presents, with no originating transaction required.

launcher.startRefund(
    RefundRequest(
        refundAmount = BigDecimal("25.00"),
        posDeviceId = "TILL-1",
    ),
)

The outcome arrives on the same payment callback as PaymentResult.Approved, with transactionType identifying it as a refund and a negative processedAmount.

FluteTerminal.cancelPayment(posTransactionId, callback)

Cancels the payment currently in flight, before the cardholder completes it.

FluteTerminal.pendingPosTransactionId()?.let { id ->
    FluteTerminal.cancelPayment(id) { /* accepted or rejected */ }
}

The return value indicates only whether the cancellation request was accepted by the SDK. The backend rejects it once the transaction has already reached the processor. The final outcome still arrives on the payment callback.

PaymentResult is a sealed class with three cases.

PaymentResult.Approved

PaymentResult.Declined

Carries posTransactionId, transactionId, responseCode, message, plus processedAmount, amounts, card, avs, gatewayReferenceId, and transactionDateTime where available.

A decline is a completed transaction with a negative outcome, not an error. AVS and CVV rejections arrive here, with the reason in message.

PaymentResult.Error

ErrorReason values

Example result handler:

private fun handleResult(result: PaymentResult) = when (result) {
    is PaymentResult.Approved -> completeOrder(result.transactionId, result.processedAmount)
    is PaymentResult.Declined -> showDeclined(result.message)
    is PaymentResult.Error -> when (result.reason) {
        ErrorReason.USER_CANCELLED -> returnToOrder()
        ErrorReason.TIMEOUT -> reconcileLater(result.posTransactionId)
        else -> showError(result.message, result.correlationId)
    }
}

If your app is killed while the terminal is collecting the card, the in-flight transaction ID is persisted. Call checkPendingPayment() at startup and resolve the outstanding result before initiating new payments:

FluteTerminal.checkPendingPayment { check ->
    check.onSuccess { pending ->
        when {
            !pending.hasPending -> Unit                        // nothing was interrupted
            pending.stillInProgress -> waitForTerminal()       // terminal has not finished yet
            else -> pending.result?.let { handleResult(it) }  // resolved outcome
        }
    }
}

PendingPaymentCheck properties

Recovery methods

All methods are available as @JvmStatic on FluteTerminal and deliver results via FluteCallback on the main thread.

Check PaymentConfig.requiresPricingType to determine whether pricingType must be set on every payment. It is true for Dual Pricing merchants.

• Every callback is delivered on the main thread, so you can update the UI directly.
• The payment flow runs on a process-wide scope and survives Activity recreation while the terminal app is in the foreground.
• After shutdown() or an initialize() with changed configuration, re-register to obtain a new launcher.