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.
| Method | Description | Use Case |
|---|---|---|
cardTerminal | NFC Card Reader | Contactless EMV payments. |
sepaTerminal | SEPA Instant | Bank-to-bank transfers via QR code. |
certisTerminal | Certis Payments | Specialized instant payment network. |
cryptoTerminal | Cryptocurrency | Bitcoin, 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 Class | Description |
|---|---|
| Initialization | |
AcceptSDKUninitializedException | Terminal is not initialized, call AcceptSDK.initialize() first. |
AcceptSDKServiceStartingException | Service failed to start. Ensure app is in foreground. |
AcceptSDKServiceInitializationException | Unable to initialize payment service. Payments may not be working |
| properly. | |
AcceptSDKTokenInitializationErrorException | Error in your TokenProvider implementation. |
AcceptSDKInitializationException | Accept SDK initialization failed. |
AcceptSDKLoginExpiredException | Session expired or not found. Call AcceptSDK.initialize() first. |
AcceptSDKInitializeWithoutDataException | Device restarted payment service. Waiting for proper start. |
| Permissions & Environment | |
AcceptSDKLocationPermissionException | Missing required location permissions (ACCESS_COARSE_LOCATION / |
ACCESS_FINE_LOCATION). | |
AcceptSDKLocationDisabledException | Android Location services are disabled. |
AcceptNFCDisabledException | NFC is disabled on the device. |
AcceptSDKNotDebuggableException | Production app detected, but SDK registered in DEMO mode. Use |
AcceptSDK.initialize(..., demo = false). | |
AcceptSDKDebuggableNotDemoException | Debug app detected, but SDK registered in PROD mode. Use |
AcceptSDK.initialize(..., demo = true). | |
| Reader & Connection | |
AcceptSDKReaderNotFoundException | No Tap-to-Pay terminal reader found on this device. |
AcceptSDKReaderNotReadyYetException | Merchant KYB data missing or processing for the specific terminal |
| reader. | |
AcceptSDKReaderBadConnectionException | Connection issues detected while communicating with the reader. |
AcceptSDKOfflineException | Internet connection not available. |
| Transactions & Operations | |
AcceptSDKInitializeTransactionException | Unable to initialize transaction. |
AcceptSDKFinalizeTransactionException | Transaction finalization failed. Verify status manually via backend. |
AcceptSDKOperationTimeoutException | The operation timed out. |
AcceptSDKPaymentNotFoundException | The requested payment record was not found. |
AcceptSDKServerErrorException | Server error occurred. |
AcceptSDKClientErrorException | Client error occurred. |
AcceptSDKCancellationException | User cancelled the operation manually. |
| Onboarding & Location Metadata | |
AcceptSDKOnboardingException | Error occurred during terminal onboarding. |
AcceptSDKDuplicatedOnboardingException | Duplicated onboarding provided. |
AcceptSDKMissingKYBDetailsException | Onboarding not completed for the specified payment method. |
AcceptSDKLocationNotFoundException | Unable to resolve location coordinates. |
AcceptSDKLocationIdNotFoundException | Stripe/Internal location identifier not found. |
| System | |
AcceptSDKUnknownException | Unknown SDK error. |
AcceptSDKUnknownMessageException | Unknown 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-nativeInitialization
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.
| Method | Description | Use Case |
|---|---|---|
startCardPayment | NFC Card Reader | Contactless EMV payments. |
startSepaPayment | SEPA Instant | Bank-to-bank transfers via QR code. |
startCertisPayment | Certis Payments | Specialized instant payment network. |
startCryptoPayment | Cryptocurrency | Bitcoin, 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();