Tapaya
Integration GuideMobile SDK Integration

Mobile SDK Integration

Comprehensive guide to integrating the Tapaya Accept SDK into your mobile application.

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

Initialization

The AcceptSDK singleton is the entry point for all SDK functionality. It must be initialized before accessing any payment terminals or identity services. We recommend initializing the SDK in your Application class or the onCreate method of your main Activity.

Configuration Options

You can initialize the SDK using a static token (for simple integrations) or a TokenProvider (recommended for production to handle token rotation).

// Option 1: TokenProvider (Recommended for Production)
// Automatically handles token refresh when expired
val tokenProvider = object : TokenProvider {
override suspend fun fetchToken(): String {
return myBackendApi.getMerchantToken()
}
}

AcceptSDK.initialize(
context = this,
tokenProvider = tokenProvider,
demo = BuildConfig.DEBUG // Use demo environment for debug builds
)

// Option 2: Static Token (Testing only)
AcceptSDK.initialize(
context = this,
token = "YOUR_STATIC_TEST_TOKEN",
demo = true
)

Core Concepts

Payment Interface

The SDK exposes specialized "Terminal" objects for different payment methods. These are lazily initialized and handle the specific logic for each payment type.

MethodDescriptionUse Case
cardTerminalNFC Card ReaderContactless EMV payments.
sepaTerminalSEPA InstantBank-to-bank transfers via QR code.
certisTerminalCertis PaymentsSpecialized instant payment network.
cryptoTerminalCryptocurrencyBitcoin, Lightning, and stablecoin payments.

Onboarding

Before processing payments, you may need to verify the merchant's status or collect additional information (KYC/KYB). The AcceptSDK.identity module manages these flows.

// Check if the merchant is approved for Card payments
val status = AcceptSDK.identity.loadStatus(PaymentMethod.CARD)

if (status == IdentityStatus.APPROVED) {
// Ready to process payments
} else {
// Trigger onboarding flow
AcceptSDK.identity.express.startOnboarding(activity)
}

Permissions

Processing payments, especially contactless card payments, requires specific Android permissions and hardware capabilities (NFC). The AcceptSDK.helper simplifies managing these requirements.

Lifecycle Management

To ensure the helper can correctly handle permission results, link it to your Activity's lifecycle.

class PaymentActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Register lifecycle observer
AcceptSDK.helper.onCreate(this)
}

override fun onDestroy() {
AcceptSDK.helper.onDestroy()
super.onDestroy()
}
}

Requesting Permissions

Request the necessary permissions before starting a transaction. The SDK handles the complexity of different Android versions.

fun startPayment() {
AcceptSDK.helper.requestLocationPermission(this,
    onLocationPermissionGranted = {
        // Permission granted, proceed to payment
        launchPaymentFlow()
    },
    onLocationPermissionDenied = {
        // Show rationale to user
        showPermissionRationale()
    }
)
}

UI Customization

You can tailor the SDK's UI to match your brand identity. This includes colors, logos, and text strings used during the payment flow.

val uiConfig = UiConfigurationData(
logoResId = R.drawable.my_merchant_logo,
primaryColor = ContextCompat.getColor(context, R.color.brand_primary),
merchantName = "My Coffee Shop"
)

AcceptSDK.setUiConfiguration(uiConfig)

Error Handling

The SDK uses a unified exception hierarchy rooted at AcceptSDKException. All exceptions are wrapped in AcceptSDKExceptionWrapper to preserve the original cause while providing a consistent interface.

Exception Hierarchy

Exception ClassDescription
Initialization
AcceptSDKUninitializedExceptionTerminal is not initialized, call AcceptSDK.initialize() first.
AcceptSDKServiceStartingExceptionService failed to start. Ensure app is in foreground.
AcceptSDKServiceInitializationExceptionUnable to initialize payment service. Payments may not be working
properly.
AcceptSDKTokenInitializationErrorExceptionError in your TokenProvider implementation.
AcceptSDKInitializationExceptionAccept SDK initialization failed.
AcceptSDKLoginExpiredExceptionSession expired or not found. Call AcceptSDK.initialize() first.
AcceptSDKInitializeWithoutDataExceptionDevice restarted payment service. Waiting for proper start.
Permissions & Environment
AcceptSDKLocationPermissionExceptionMissing required location permissions (ACCESS_COARSE_LOCATION /
ACCESS_FINE_LOCATION).
AcceptSDKLocationDisabledExceptionAndroid Location services are disabled.
AcceptNFCDisabledExceptionNFC is disabled on the device.
AcceptSDKNotDebuggableExceptionProduction app detected, but SDK registered in DEMO mode. Use
AcceptSDK.initialize(..., demo = false).
AcceptSDKDebuggableNotDemoExceptionDebug app detected, but SDK registered in PROD mode. Use
AcceptSDK.initialize(..., demo = true).
Reader & Connection
AcceptSDKReaderNotFoundExceptionNo Tap-to-Pay terminal reader found on this device.
AcceptSDKReaderNotReadyYetExceptionMerchant KYB data missing or processing for the specific terminal
reader.
AcceptSDKReaderBadConnectionExceptionConnection issues detected while communicating with the reader.
AcceptSDKOfflineExceptionInternet connection not available.
Transactions & Operations
AcceptSDKInitializeTransactionExceptionUnable to initialize transaction.
AcceptSDKFinalizeTransactionExceptionTransaction finalization failed. Verify status manually via backend.
AcceptSDKOperationTimeoutExceptionThe operation timed out.
AcceptSDKPaymentNotFoundExceptionThe requested payment record was not found.
AcceptSDKServerErrorExceptionServer error occurred.
AcceptSDKClientErrorExceptionClient error occurred.
AcceptSDKCancellationExceptionUser cancelled the operation manually.
Onboarding & Location Metadata
AcceptSDKOnboardingExceptionError occurred during terminal onboarding.
AcceptSDKDuplicatedOnboardingExceptionDuplicated onboarding provided.
AcceptSDKMissingKYBDetailsExceptionOnboarding not completed for the specified payment method.
AcceptSDKLocationNotFoundExceptionUnable to resolve location coordinates.
AcceptSDKLocationIdNotFoundExceptionStripe/Internal location identifier not found.
System
AcceptSDKUnknownExceptionUnknown SDK error.
AcceptSDKUnknownMessageExceptionUnknown SDK error with message.

Handling Exceptions

When using Coroutines, wrap SDK calls in a try-catch block to handle these specific scenarios.

try {
    AcceptSDK.cardTerminal.pay(...)
} catch (e: AcceptSDKCancellationException) {
    // User cancelled, do nothing
} catch (e: AcceptSDKLocationPermissionException) {
    // Prompt user for permissions
} catch (e: AcceptSDKException) {
    // Handle other SDK-specific errors
    Log.e("Payment", "Error: ${e.message}")
}

Logging

Enable verbose logging during development to troubleshoot issues.

// Enable debug logs
AcceptSDK.setLogLevel(LogLevel.DEBUG)

Coming Soon

iOS documentation is currently being updated. Please refer to the Android guide for general concepts or contact support for the iOS beta SDK.

iOS Implementation

iOS part of implementation is under development, so the SDK calls made from iOS part will be ignored.

The Tapaya Accept SDK for React Native is a robust, secure, and easy-to-use toolkit that lets you embed payment processing directly into your React Native application. Built to integrate seamlessly with the React Native ecosystem, it offers a clean API, reliable performance, and a developer-friendly experience across platforms.

Create .npmrc file

In project root create file called .npmrc where you will place NPM registry secret to access @tapayadot registry. Content of the file should be following.

//npm.pkg.github.com/:_authToken=REPLACE_ME
@tapayadot:registry=https://npm.pkg.github.com/

To pull the plugin inside your project, you have to generate NPM registry secret and replace it with the REPLACE_ME above. You can find in the settings of the Tapaya Platform.

Install NPM plugin

Add dependency to the project.

npm i @tapayadot/accept-sdk-react-native

Initialization

The AcceptSDK object is the entry point for all SDK functionality. It must be initialized before accessing any payment terminals or identity services.

import AcceptSDK from '@tapayadot/accept-sdk-react-native';

// Initialize with your token
// set demo = true for testing environment
await AcceptSDK.initialize("YOUR_TOKEN", true);

Core Concepts

Payment Interface

The SDK exposes payment methods through the AcceptSDK.payments object.

MethodDescriptionUse Case
startCardPaymentNFC Card ReaderContactless EMV payments.
startSepaPaymentSEPA InstantBank-to-bank transfers via QR code.
startCertisPaymentCertis PaymentsSpecialized instant payment network.
startCryptoPaymentCryptocurrencyBitcoin, Lightning, and stablecoin payments.

Example of starting a card payment:

import AcceptSDK, {Currency, CardPaymentIntent} from '@tapayadot/accept-sdk-react-native';

const paymentIntent: CardPaymentIntent = {
amount: 100.0,
currency: Currency.CZK,
description: "Coffee"
};

try {
const result = await AcceptSDK.payments.startCardPayment(
paymentIntent,
(status) => {
console.log("Payment Status Update:", status);
},
(message, exception) => {
console.error("Payment Error:", message, exception);
}
);
console.log("Payment Successful:", result);
} catch (error) {
console.error("Payment Failed:", error);
}

Onboarding

Before processing payments, you may need to verify the merchant's status or collect additional information (KYC/KYB). The AcceptSDK.identity module manages these flows.

import AcceptSDK, {PaymentMethod, IdentityStatus} from '@tapayadot/accept-sdk-react-native';

// Check if the merchant is approved for Card payments
const status = await AcceptSDK.identity.loadStatus(PaymentMethod.CARD);

if (status === IdentityStatus.APPROVED) {
// Ready to process payments
} else {
// Trigger onboarding flow
await AcceptSDK.identity.showExpressOnboarding();
}

Permissions

Processing payments, especially contactless card payments, requires specific permissions (like Location).

const granted = await AcceptSDK.requestLocationPermission();
if (granted) {
// Proceed with payment
} else {
// Show rationale
}

UI Customization

You can tailor the SDK's UI to match your brand identity.

import {UiConfigurationData} from '@tapayadot/accept-sdk-react-native';

const uiConfig: UiConfigurationData = {
// ... configuration properties
};

await AcceptSDK.setUiConfiguration(uiConfig);

Other Operations

Get Status

Check the current status of the SDK.

const status = await AcceptSDK.getStatus();

Get Transaction Info

Retrieve information about a specific payment intent.

const info = await AcceptSDK.info("payment_intent_id");

Cancel Operation

Cancel the current operation.

await AcceptSDK.cancel();

Log Out

Clear the current session.

await AcceptSDK.logOut();