Mobile SDK Integration

The Tapaya Accept SDK for Android provides a robust, secure, and easy-to-use toolkit for embedding payment processing directly into your Android application. Designed with modern Android development practices in mind, it supports Kotlin Coroutines, lifecycle-aware components, and a clean API surface.

Installation

Add the Tapaya Accept SDK dependency to your module-level build.gradle file.

dependencies {
    implementation("com.tapaya:accept:1.10.0")
}

Initialization

The Accept singleton is the entry point for all SDK functionality. Initialize it once (typically in your Application class), then authenticate separately with a merchant token.

Step 1: Initialize

// Sandbox is the default (isProduction = false)
Accept.initialize(context = this)

// Target production explicitly
Accept.initialize(context = this, isProduction = true)

// Or drive it from your build type
Accept.initialize(context = this, isProduction = !BuildConfig.DEBUG)

Step 2: Authenticate

Call Accept.auth.authenticate() after initialization to log in a merchant with a token obtained from your backend. It is a suspend function and throws an AcceptException on failure. On success, Accept.state transitions to SdkState.Authenticated.

// suspend; call from a coroutine
try {
    val merchantToken = myBackendApi.getMerchantToken()
    Accept.auth.authenticate(merchantToken)
    // Accept.state now emits SdkState.Authenticated
} catch (e: AcceptException) {
    // handle authentication failure
}

You can observe Accept.state (a StateFlow<SdkState>) to react to lifecycle changes — Idle → Initialized → Authenticated.

Core Concepts

The Accept object exposes the SDK through a small set of surfaces:

Taking a Payment

Call Accept.payments.pay() with the amount (in the currency's minor unit) and an ISO 4217 currency code. It returns a Flow<PaymentEvent>; collect it to observe progress and the terminal outcome. pay() never throws — failures arrive as PaymentEvent.CreationFailed.

Parameters:

Accept.payments.pay(amount = 15000, currency = "CZK") // 150.00 Kč
    .collect { event ->
        when (event) {
            PaymentEvent.Creating -> Log.d("pay", "creating")
            is PaymentEvent.Created -> Log.d("pay", "created ${event.paymentToken}")
            PaymentEvent.Launched -> Log.d("pay", "launched")
            is PaymentEvent.Result -> Log.d("pay", event.payResult.toString())
            is PaymentEvent.CreationFailed -> Log.e("pay", event.cause.toString())
        }
    }

The terminal PaymentEvent.Result carries a PayResult — Success(paymentToken, metadata, authCode, receiptDetails), Declined(metadata, receiptDetails), Canceled(metadata), or Failed(reason, metadata). See Payment outcome for the full breakdown. Query a payment later with Accept.payments.status(paymentToken), stop it with Accept.payments.cancel(paymentToken), or refund it with Accept.payments.refund(paymentToken, reason).

Plugin App

Every card payment hands off to Tapaya Terminal, the Tapaya plugin app; it is always required, there is no card payment path that skips it. Check whether it is installed, then activate the terminal, or open the store listing so the merchant can install it.

if (Accept.plugin.isInstalled()) {
    // suspend; returns ActivateTerminalResult (Success / Canceled / Failed)
    Accept.plugin.activateTerminal()
} else {
    Accept.plugin.install() // opens the store listing
}

Read the plugin's current state with Accept.plugin.status(), or sign the merchant out of the plugin with Accept.plugin.logout().

Permissions

Card payments require the host app to hold location permission (ACCESS_FINE_LOCATION). The SDK does not request it for you — grant it with the standard Android permission APIs before calling pay().

class PaymentActivity : AppCompatActivity() {
    private val requestLocation = registerForActivityResult(
        ActivityResultContracts.RequestPermission()
    ) { granted ->
        if (granted) launchPaymentFlow() else showPermissionRationale()
    }

    fun startPayment() {
        requestLocation.launch(Manifest.permission.ACCESS_FINE_LOCATION)
    }
}

If location is missing or cannot be resolved when pay() runs, the flow emits PaymentEvent.CreationFailed with LocationPermissionRequired, LocationUnavailable, or LocationTimeout as the cause.

Error Handling

Every checked failure is a subclass of the sealed AcceptException. Suspend calls (authenticate, merchant.*, payments.status/cancel/refund, plugin.activateTerminal/status/logout/updateInfo, clear) throw one on failure. payments.pay() is the exception: it never throws and instead reports failures as PaymentEvent.CreationFailed(cause).

Exception Types

Handling Exceptions

Wrap suspend calls in a try-catch; branch on specific cases or catch AcceptException broadly.

try {
    val status = Accept.payments.status(paymentToken)
} catch (e: SessionExpired) {
    // Re-authenticate
} catch (e: NoInternetConnection) {
    // Ask the user to check connectivity
} catch (e: AcceptException) {
    // Handle any other SDK error
    Log.e("Payment", "Error: ${e.message}")
}

Logging

Enable debug logging during development to troubleshoot issues.

Accept.setDebugLoggingEnabled(true)

Logging Out

Clear all locally persisted SDK state (auth token, device id, cached config) and reset Accept.state to SdkState.Idle. Call this on user logout.

Accept.clear() // suspend