Tapaya

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.

OptionBest forResult delivery
Accept SDK (recommended)Native Android appsAccept.payments.pay() emits a Flow<PaymentEvent>: creation, launch, and the terminal result, handled for you
DeeplinkWebViews, cross-platform frameworks, QR codesYou 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:

  1. Your app starts a payment with Accept.payments.pay(amount, currency).
  2. The SDK registers the payment with the Tapaya backend and launches the Tapaya Terminal plugin on the same device.
  3. The customer taps their card or phone on the Tapaya Terminal screen.
  4. Tapaya Terminal settles the payment with the Tapaya backend.
  5. The SDK observes the payment until it reaches a final state and emits PaymentEvent.Result carrying a PayResult. If the payment can't be created at all, it emits PaymentEvent.CreationFailed instead, usually within a second.

You need:

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
}
  • ActivateTerminalFailureReason is one of INVALID_INTENT, HANDOVER_FAILED, CONFIRM_FAILED, MERCHANT_NOT_ONBOARDED, or UNKNOWN.
  • Accept.plugin.isInstalled() returns false when the plugin is missing. Read the plugin's current state at any time with Accept.plugin.status(), and guard your payment UI accordingly.
  • activateTerminal() also throws, separately from the Failed outcomes above: PluginUnavailable when Tapaya Terminal is missing, MerchantOnboardingIncomplete before anything opens when the merchant has not finished onboarding, and NoTidsAvailableForMerchant when 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 as PaymentEvent.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 paymentToken back into pay(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 PayResult variant carries metadata, echoing back what you passed to pay() if the plugin returns it (may be null).
  • 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 resulting PaymentState.

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)
  • RefundReason is one of CUSTOMER_REQUEST, DUPLICATE, FRAUDULENT, or EXPIRED_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.

  1. Create a payment from your backend via the Payments API and keep its paymentId.
  2. Open Tapaya Terminal with that paymentId using the pay deeplink.
  3. 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

  1. Initialize with isProduction = false (the default); sandbox payments never move real money.
  2. Install the Tapaya Terminal plugin on your test device, sign in with a sandbox merchant, and activate.
  3. Run a payment for a small amount and verify the Success flow end to end, including your receipt UI.
  4. Exercise the failure paths: decline a payment on the terminal, cancel one, and start one with an unsupported currency; your PayResult/CreationFailed handling 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.

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