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:

Confirm the following hardware, software, and credentials are in place before you integrate the SDK.

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.

The following environments are available:

Credentials are scoped to one environment:

• A clientId and clientSecret issued for the sandbox environment are rejected in the production environment.
• A clientId and clientSecret issued for the production environment are rejected in the sandbox environment.

Either case returns a 401 result during initialization.

This section covers starting the SDK, supplying credentials at runtime, checking their status, and releasing the SDK when it's no longer needed.

Initializes the SDK for the selected environment and credentials.

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

This lists each parameter accepted by FluteTerminalConfig.

When credentials aren't included in at build time, or they need to change without a rebuild, the app can supply them at runtime instead.

This supplies or rotates credentials at runtime without a rebuild.

FluteTerminal.provisionCredentials(clientId, clientSecret, callback)

The SDK stores them encrypted for each environment, invalidates the existing token, and the re-warms them.

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

Before starting a payment, the app can check whether valid credentials are already stored for the current environment.

FluteTerminal.hasCredentials()

val ready = FluteTerminal.hasCredentials()

This returns true if this device holds valid credentials for the selected environment.

When your app no longer needs the SDK, such as on sign-out or when switching merchant accounts, it should be shut down to free its resources.

This releases the SDK and stops the token-refresh loop.

FluteTerminal.shutdown()

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.

The following steps trace what happens between calling startPayment() and receiving a result:

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. parseResult(activityResult) is also used for process-death recovery. See Recovery After Process Death.

Before a payment can be started, the app must register a callback to receive its result.

This registers the result callback and returns the launcher used to start payments.

FluteTerminal.registerForPaymentResult(owner, callback)

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

With credentials provisioned and a result callback registered, the app is ready to initiate a card-present payment.

This starts a card-present payment for the given amount and hands off to the Flute Terminal app to collect the card.

launcher.startPayment(PaymentRequest)

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

PaymentRequest parameters

This lists each parameter accepted by PaymentRequest.

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.

When a merchant needs to return funds to a customer without an original transaction to reference, the app can initiate a refund directly.

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

launcher.startRefund(RefundRequest)

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.

If a payment needs to be stopped before the cardholder completes it, the app can request its cancellation.

This cancels the payment currently in flight, before the cardholder completes it.

FluteTerminal.cancelPayment(posTransactionId, callback)

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.

Once the payment completes, the callback delivers a PaymentResult describing how it was resolved.

PaymentResult is a sealed class with three cases: Approved Case, Declined Case, and Error Case.

An approved payment returns the following properties describing the completed transaction.

PaymentResult.Approved

When the issuer or processor rejects the payment, the callback delivers a PaymentResult.Declined instead of an error.

A decline is a completed transaction with a negative outcome, not an error.

PaymentResult.Declined

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

AVS and CVV rejections arrive here, with the reason in message.

An error indicates the payment did not reach a definitive outcome and carries the following properties to help you diagnose and recover.

PaymentResult.Error

ErrorReason values

This lists each ErrorReason value and how to handle it.

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

This describes each property returned by PendingPaymentCheck.

Recovery methods

This lists the methods available for recovering from a process death.

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

These methods return read-only information about the merchant's terminals, payment configuration, and this device.

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

Keep the following threading and lifecycle behaviors in mind when integrating the SDK.

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

The following table lists common integration issues, their causes, and how to resolve them.