Tapaya Terminal App
Accept contactless card payments by handing the card interaction off to the Tapaya Terminal plugin app.
Take contactless card payments from your Android app by handing the card interaction off to the Tapaya Terminal
plugin app. Your app stays in control of the sale; the plugin handles the NFC tap, PIN entry, and card
processing, then the result flows back through the Accept.payments.pay() event stream.
Before you start
Use this integration when you want Tap to Pay without embedding a payment processor in your own app.
| Option | Best for | Result delivery |
|---|---|---|
| Accept SDK (recommended) | Native Android apps | Accept.payments.pay() emits a Flow<PaymentEvent>: creation, launch, and the terminal result, handled for you |
| Deeplink | WebViews, cross-platform frameworks, QR codes | You create the payment via the Tapaya API and poll its status; the plugin opens via a deeplink |
This page covers the SDK path first; see Integrate without the SDK for the deeplink contract.
How it works:
- Your app starts a payment with
Accept.payments.pay(amount, currency). - The SDK registers the payment with the Tapaya backend and launches the Tapaya Terminal plugin on the same device.
- The customer taps their card or phone on the Tapaya Terminal screen.
- Tapaya Terminal settles the payment with the Tapaya backend.
- The SDK observes the payment until it reaches a final state and emits
PaymentEvent.Resultcarrying aPayResult. If the payment can't be created at all, it emitsPaymentEvent.CreationFailedinstead, usually within a second.
You need:
- The Tapaya Terminal plugin installed on the device and activated for your merchant (see Install and activate the terminal).
- A device with NFC, running Android 11 (API 30) or later.
- The Accept SDK installed and initialized, with the merchant authenticated.
- Location permission (
ACCESS_FINE_LOCATION) granted at runtime by your app.
Take a payment
Install and activate the terminal
Activate once per device. Activation links the Tapaya Terminal plugin to the same merchant account your app is authenticated with.
if (!Accept.plugin.isInstalled()) {
// Opens the app store, or installs Tapaya Terminal directly where there is no store
Accept.plugin.install()
return
}
// suspend; launches the plugin's activation flow and waits for the outcome
when (val result = Accept.plugin.activateTerminal()) {
ActivateTerminalResult.Success -> { /* device linked, ready to take payments */ }
ActivateTerminalResult.Canceled -> { /* user backed out */ }
is ActivateTerminalResult.Failed -> result.reason // ActivateTerminalFailureReason
}ActivateTerminalFailureReasonis one ofINVALID_INTENT,HANDOVER_FAILED,CONFIRM_FAILED,MERCHANT_NOT_ONBOARDED, orUNKNOWN.Accept.plugin.isInstalled()returnsfalsewhen the plugin is missing. Read the plugin's current state at any time withAccept.plugin.status(), and guard your payment UI accordingly.activateTerminal()also throws, separately from theFailedoutcomes above:PluginUnavailablewhen Tapaya Terminal is missing,MerchantOnboardingIncompletebefore anything opens when the merchant has not finished onboarding, andNoTidsAvailableForMerchantwhen the merchant has no unassigned terminal (TID) left.
Create a payment
Call pay() and collect the Flow<PaymentEvent> it returns to observe progress and the terminal outcome. Amounts
are always in the smallest unit of the currency: hellers for CZK, cents for EUR. 1500 with currency "CZK"
charges 15.00 Kč. Currencies are ISO 4217 codes.
Accept.payments.pay(amount = 1500, currency = "CZK") // 15.00 Kč
.collect { event ->
when (event) {
PaymentEvent.Creating -> { /* registering the payment */ }
is PaymentEvent.Created -> { /* backend payment created: event.paymentToken */ }
PaymentEvent.Launched -> { /* Tapaya Terminal is in the foreground */ }
is PaymentEvent.Result -> when (val r = event.payResult) {
is PayResult.Success -> showReceipt(r.paymentToken, r.authCode)
is PayResult.Declined -> showDeclined(r.metadata)
is PayResult.Canceled -> showCancelled(r.metadata)
is PayResult.Failed -> showUnexpected(r.reason) // PayFailureReason
}
is PaymentEvent.CreationFailed -> handleError(event.cause) // AcceptException
}
}pay()never throws; failures surface asPaymentEvent.CreationFailed.- While the payment is in progress the Tapaya Terminal plugin is in the foreground. Your app resumes automatically when the payment finishes.
- To resume an interrupted payment, pass its
paymentTokenback intopay(amount, currency, paymentToken).
metadata is best-effort
metadata is echoed back on PayResult only if the plugin returns it, so treat it as best-effort context
(e.g. an order ID for your own logging), not as data your app depends on receiving back.
Read the payment outcome
The terminal PaymentEvent.Result carries a PayResult. PayResult.Success gives you the paymentToken; fetch
the full record, including receiptUrl, requested and settlement amounts, and timestamps, with
Accept.payments.status().
val status: PaymentStatus = Accept.payments.status(paymentToken)
status.state // PENDING, SUCCESS, CANCELLED, REFUNDED, FAILED, ACTION_NEEDED
status.receiptUrl // for your receipt UI- Every
PayResultvariant carriesmetadata, echoing back what you passed topay()if the plugin returns it (may benull). - Always confirm the final state with
Accept.payments.status()before treating a payment as complete. - Stop an in-flight payment with
Accept.payments.cancel(paymentToken), which returns the resultingPaymentState.
Refund a payment
Refund a settled payment with Accept.payments.refund(paymentToken, reason), which also returns the resulting
PaymentState.
val state: PaymentState = Accept.payments.refund(paymentToken, RefundReason.CUSTOMER_REQUEST)RefundReasonis one ofCUSTOMER_REQUEST,DUPLICATE,FRAUDULENT, orEXPIRED_CHARGE.
Customize the payment
Set a device-wide default once with Accept.payments.setOptions(), and override it for a single payment by
passing the same option to pay(). setOptions() only touches the options you pass, so setting one never
disturbs a default set earlier for another. Brand the Tapaya Terminal screens with Accept.setTheme().
Integrate without the SDK
If you can't embed the Accept SDK (a cross-platform framework, a thin POS shell, a web-based till), you can drive Tapaya Terminal directly with a deeplink. The division of work changes: you create the payment through the Tapaya API and you poll its status for the result; Tapaya Terminal only handles the card interaction.
- Create a payment from your backend via the Payments API and keep
its
paymentId. - Open Tapaya Terminal with that
paymentIdusing the pay deeplink. - Poll the payment status via the Payments API until it leaves
PENDING. Deeplinks have no return channel, so polling is the only source of truth.
No activation step
Tapaya Terminal must be installed, signed in to the merchant account, and configured for the payment's currency. There is no activation step in this mode; the signed-in account is the merchant of record. Sign a merchant in with the login deeplink if needed.
Test the integration
- Initialize with
isProduction = false(the default); sandbox payments never move real money. - Install the Tapaya Terminal plugin on your test device, sign in with a sandbox merchant, and activate.
- Run a payment for a small amount and verify the
Successflow end to end, including your receipt UI. - Exercise the failure paths: decline a payment on the terminal, cancel one, and start one with an unsupported
currency; your
PayResult/CreationFailedhandling should cover each.
When you're ready to go live, set isProduction = true in initialize and authenticate with production
credentials. The payment code does not change.
Handle errors
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). See
Read the payment outcome.