Mobile SDK Integration
AndroidIntegrate the Tapaya Accept SDK into your mobile application.

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
dependencies {
implementation("com.tapaya:accept:$acceptVersion")
}- Android: add the dependency to your module-level
build.gradle.kts, setacceptVersionto 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 withnpx expo prebuild --clean, and run it withnpx expo run:android. - Optional features: add
com.tapaya:accept-installerto install Tapaya Terminal on devices without an app store, andcom.tapaya:accept-nfcto read NFC tags. On React Native, turn them on with the config plugin optionsselfInstallandnfc, then runnpx expo prebuildagain.
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
Applicationclass. - There is no
contexton 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()
}- Your backend creates the token; see Backend Integration.
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 withAccept.plugin.install(), and link the device withAccept.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 aCreationFailedevent. Kotlin returns aFlow<PaymentEvent>you collect from a coroutine; React Native takes a listener and returns a subscription.- The
Resultevent carries aPayResult: success (paymentToken,metadata,authCode,receiptDetails), declined (metadata,receiptDetails), canceled (metadata), or failed (reason,metadata). Kotlin models these asPayResult.Success,Declined,Canceled, andFailed; React Native as a union you branch on withpayResult.type. See Payment outcome. amountandcurrencyare required. For the optional parameters (paymentToken,receiptConfig,nfcPosition,metadata,tip,transactionTimeout,display,customerFacingFlip), see Create a payment. Later, query, stop, or refund the payment withAccept.payments.status(),cancel(), orrefund().
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}")
}