Tapaya

Mobile SDK Integration

Android

Integrate the Tapaya Accept SDK into your mobile application.

Payment Flow

Before you start

The Tapaya Accept SDK embeds card payment processing in your app. It ships for Android (Kotlin) and for React Native / Expo, and both target Android devices. The React Native package is a thin wrapper over the Android SDK, so the surfaces, types, and failure cases are the same on either. Every code sample on this page is tabbed by language; pick one and the whole page follows.

For every API with an example, see the Android SDK reference.

Install the SDK

build.gradle.kts
dependencies {
    implementation("com.tapaya:accept:$acceptVersion")
}
  • Android: add the dependency to your module-level build.gradle.kts, set acceptVersion to the latest release on Maven Central, then sync the project.
  • React Native: install with npx expo install @tapayadot/accept-react-native, add the config plugin as shown, regenerate the native project with npx expo prebuild --clean, and run it with npx expo run:android.
  • Optional features: add com.tapaya:accept-installer to install Tapaya Terminal on devices without an app store, and com.tapaya:accept-nfc to read NFC tags. On React Native, turn them on with the config plugin options selfInstall and nfc, then run npx expo prebuild again.

Grant location permission

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

Payments use the device's last known location, refreshed in the background, so they do not wait for a new fix. Only a device that has never had a fix waits, for up to 30 seconds. If location is missing when pay() runs, the flow emits PaymentEvent.CreationFailed with LocationPermissionRequired, LocationUnavailable, or LocationTimeout as the cause.

Take your first payment

Initialize the SDK

Accept is the entry point for all SDK functionality, so initialize it once at app startup.

// 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)
  • On Android, call it in your Application class.
  • There is no context on React Native; the native module holds it for you.

Authenticate the merchant

Call Accept.auth.authenticate() with a token from your backend to sign the merchant in. It is asynchronous, fails with an SDK error, and on success moves the SDK state to authenticated.

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

Observe the lifecycle to react to its transitions: idle → initialized → authenticated.

// Accept.state is a StateFlow<SdkState>
Accept.state.collect { state ->
    if (state == SdkState.Authenticated) loadMerchant()
}

Install and activate the terminal

Every card payment hands off to Tapaya Terminal, the Tapaya plugin app, so it must be installed and activated for the merchant before the first payment. There is no card payment path that skips it.

  • Check for it with Accept.plugin.isInstalled(), install it with Accept.plugin.install(), and link the device with Accept.plugin.activateTerminal(). install() opens the app store, or installs directly on devices without one. See Install and activate the terminal for the code and every activation outcome.
  • Read the plugin's current state with Accept.plugin.status().

Take a payment

Call Accept.payments.pay() with the amount and an ISO 4217 currency code, then observe the PaymentEvents it reports: progress first, then the outcome. Amounts are in the currency's minor unit: 15000 with CZK is 150.00 Kč.

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())
        }
    }
  • pay() never throws; a failure to create the payment arrives as a CreationFailed event. Kotlin returns a Flow<PaymentEvent> you collect from a coroutine; React Native takes a listener and returns a subscription.
  • The Result event carries a PayResult: success (paymentToken, metadata, authCode, receiptDetails), declined (metadata, receiptDetails), canceled (metadata), or failed (reason, metadata). Kotlin models these as PayResult.Success, Declined, Canceled, and Failed; React Native as a union you branch on with payResult.type. See Payment outcome.
  • amount and currency are required. For the optional parameters (paymentToken, receiptConfig, nfcPosition, metadata, tip, transactionTimeout, display, customerFacingFlip), see Create a payment. Later, query, stop, or refund the payment with Accept.payments.status(), cancel(), or refund().

On React Native

The same parameters arrive as a single PaymentRequest object, pay({ amount, currency, tip, … }), with number in place of Long and Record<string, string> in place of Map<String, String>. The timeout is transactionTimeoutMs and takes plain milliseconds (0 to 120000) rather than a Duration.

Sign out

When the merchant logs out of your app, clear all locally stored SDK state (auth token, device id, cached config, theme). This resets the SDK state to idle.

Accept.plugin.logout() // suspend; signs out of the Tapaya Terminal app
Accept.clear()         // suspend; clears local SDK state
  • Call Accept.plugin.logout() first if the merchant should also be signed out of the Tapaya Terminal app.

Merchant and SDK details

Accept.merchant exposes the authenticated merchant's profile and payment configuration; Accept.sdk exposes facts about the SDK build and this device. Everything except Accept.sdk.version requires Accept.initialize() first, and everything on Accept.merchant also requires Accept.auth.authenticate(), otherwise the call throws NotInitialized or NotAuthenticated.

val info = Accept.merchant.info()                      // MerchantInformation?
val config = Accept.merchant.config()                  // MerchantConfig
val currencies = Accept.merchant.availableCurrencies() // List<String>
val status = Accept.merchant.onboardingStatus()        // OnboardingStatus

Accept.sdk.version            // String, the SDK version
Accept.sdk.isProduction       // Boolean
Accept.sdk.deviceId()         // String?  (suspend)
Accept.sdk.minimumAmounts()   // List<MinimumAmount>  (suspend)

For what each member returns, see Merchant and Device and SDK in the Android SDK reference. On dual-screen terminals, Accept.displays finds the customer-facing screen; see Use a customer screen.

Handle errors

Every checked failure carries one of the names below. On Kotlin each is a subclass of the sealed AcceptException; on React Native they are all one AcceptError class whose code holds the name, with the payload fields (minimum, currency, state, …) on the same object.

The async calls (authenticate, merchant.*, payments.status/cancel/refund, plugin.install/activateTerminal/status/logout/updateInfo, clear) fail with one. payments.pay() never throws, and reports the same failures as a CreationFailed event carrying the cause.

Result vs. exception

A payment that reaches the terminal but does not succeed is not an exception; it arrives as PaymentEvent.Result carrying PayResult.Declined, Canceled, or Failed(reason). Likewise, terminal activation reports ActivateTerminalResult.Failed(reason).

Wrap the call in a try/catch and branch on the cases you handle, falling back to a broad catch. Kotlin branches on the exception subclass; React Native guards with AcceptError.is() and switches on code.

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}")
}

Missing something on this page?Request a feature. We attach this page so the team sees the context.