# Tapaya Terminal App (/in-store/integration/card_terminal)



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 [#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](#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:**

* The **Tapaya Terminal plugin** installed on the device and **activated** for your merchant (see
  [Install and activate the terminal](#install-and-activate-the-terminal)).
* A device with NFC, running Android 11 (API 30) or later.
* The Accept SDK [installed and initialized](../integration/sdk_integration#initialization), with the merchant
  [authenticated](../integration/sdk_integration#step-2-authenticate).
* Location permission (`ACCESS_FINE_LOCATION`) granted at runtime by your app.

## Take a payment [#take-a-payment]

<div className="fd-steps [&_h3]:fd-step">
  ### Install and activate the terminal [#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.

  <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="kotlin">
        Android (Kotlin)
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="typescript">
        React Native (TypeScript)
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="kotlin">
      ```kotlin
      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
      }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="typescript">
      ```typescript
      if (!Accept.plugin.isInstalled()) {
          // Opens the app store, or installs Tapaya Terminal directly where there is no store
          await Accept.plugin.install();
          return;
      }

      // launches the plugin's activation flow and waits for the outcome
      const result = await Accept.plugin.activateTerminal();
      switch (result.type) {
          case 'success': /* device linked, ready to take payments */ break;
          case 'canceled': /* user backed out */ break;
          case 'failed': handle(result.reason); break; // ActivateTerminalFailureReason
      }
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  * `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.

  <Accordions type="multiple">
    <Accordion title="Check for plugin updates" id="checking-for-plugin-updates">
      `Accept.plugin.updateInfo()` reports whether a newer build of the Tapaya Terminal plugin is available, so you can
      prompt the merchant to update before a payment hits a version gap.

      <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="kotlin">
            Android (Kotlin)
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="typescript">
            React Native (TypeScript)
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="kotlin">
          ```kotlin
          when (val info = Accept.plugin.updateInfo()) {
              PluginUpdateInfo.UpToDate -> { /* nothing to do */ }
              is PluginUpdateInfo.UpdateAvailable -> promptUpdate(info.priority) // Int, higher is more urgent
              PluginUpdateInfo.Unknown -> { /* the SDK cannot tell for this install */ }
          }
          ```
        </CodeBlockTab>

        <CodeBlockTab value="typescript">
          ```typescript
          const info = await Accept.plugin.updateInfo();
          switch (info.type) {
              case 'upToDate': /* nothing to do */ break;
              case 'updateAvailable': promptUpdate(info.priority); break; // higher is more urgent
              case 'unknown': /* the SDK cannot tell for this install */ break;
          }
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      * The check follows where the plugin came from. A Google Play install is checked against Play. A plugin from the
        Sunmi store, or installed directly, is checked against Tapaya's release information, with no sign-in needed.
      * The PCI PTS version of Tapaya Terminal on certified Sunmi P3 terminals reports `Unknown`.
    </Accordion>

    <Accordion title="Install on devices without an app store" id="install-without-an-app-store">
      `Accept.plugin.install()` takes whichever route the device has:

      1. A certified Sunmi P3 terminal with the Sunmi store opens the PCI PTS version of Tapaya Terminal there, even when
         Google Play is present.
      2. Any other device with Google Play opens Tapaya Terminal on Play.
      3. Any other Sunmi device opens Tapaya Terminal in the Sunmi store.
      4. A device with no store downloads Tapaya Terminal and installs it through the Android system installer.

      The SDK works with either version of Tapaya Terminal, and prefers the PCI PTS version on certified terminals. The
      direct install is opt-in, because it needs the `REQUEST_INSTALL_PACKAGES` permission, which Google Play asks you
      to justify on your app's listing. Leave it off if your app ships through Play.

      <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
        <CodeBlockTabsList>
          <CodeBlockTabsTrigger value="kotlin">
            Android (Kotlin)
          </CodeBlockTabsTrigger>

          <CodeBlockTabsTrigger value="typescript">
            React Native (TypeScript)
          </CodeBlockTabsTrigger>
        </CodeBlockTabsList>

        <CodeBlockTab value="kotlin">
          ```kotlin title="build.gradle.kts"
          dependencies {
              implementation("com.tapaya:accept:$acceptVersion")
              implementation("com.tapaya:accept-installer:$acceptVersion")
          }
          ```
        </CodeBlockTab>

        <CodeBlockTab value="typescript">
          ```json title="app.json"
          {
            "expo": {
              "plugins": [["@tapayadot/accept-react-native", { "selfInstall": true }]]
            }
          }
          ```
        </CodeBlockTab>
      </CodeBlockTabs>

      The download checks the app's signature and contents before installing it. It also needs:

      | Error                             | Missing                                                    | What to do                                                                                              |
      | :-------------------------------- | :--------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |
      | `PluginSelfInstallUnavailable`    | The installer artifact.                                    | Add `com.tapaya:accept-installer`, or set `selfInstall: true` and run `npx expo prebuild` again.        |
      | `PluginInstallAuthRequired`       | A signed-in merchant.                                      | Call `Accept.auth.authenticate()` first.                                                                |
      | `PluginInstallPermissionRequired` | The user's "Install unknown apps" permission for your app. | Open Android's `MANAGE_UNKNOWN_APP_SOURCES` settings screen, then call `install()` again.               |
      | `PluginDownloadNotPermitted`      | Permission for this merchant to install outside a store.   | Not fixable in code. Ask your account manager or [developers@tapaya.com](mailto:developers@tapaya.com). |

      `PluginStoreUnavailable` means no store listing could be opened on the device.
    </Accordion>

    <Accordion title="Allow the terminal app in lock-task mode" id="lock-task-mode">
      On a managed device in lock-task (kiosk) mode, Android only opens apps on the lock-task allowlist, so Tapaya
      Terminal cannot open for a payment unless your device-policy controller adds it. `AcceptPluginPackages` gives you
      the package names.

      ```kotlin
      val packages = setOf(packageName, AcceptPluginPackages.PRODUCTION) // your app plus Tapaya Terminal
      devicePolicyManager.setLockTaskPackages(adminComponent, packages.toTypedArray())
      ```

      | Constant                            | Use it on                                                    |
      | :---------------------------------- | :----------------------------------------------------------- |
      | `PRODUCTION`, `SANDBOX`             | Every device except certified Sunmi P3 terminals.            |
      | `SUNMI_PRODUCTION`, `SUNMI_SANDBOX` | Certified Sunmi P3 terminals, which run the PCI PTS version. |
      | `ALL`                               | Fleets that mix environments or hardware on purpose.         |

      * Pick the constant that matches your environment and hardware, and keep your other lock-task packages.
      * Listing the packages in your manifest only makes them visible to your app; it does not add them to the allowlist.
      * React Native exports the same `AcceptPluginPackages`, for your native device-policy controller.
    </Accordion>
  </Accordions>

  ### Create a payment [#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.

  <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="kotlin">
        Android (Kotlin)
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="typescript">
        React Native (TypeScript)
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="kotlin">
      ```kotlin
      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
              }
          }
      ```
    </CodeBlockTab>

    <CodeBlockTab value="typescript">
      ```typescript
      Accept.payments.pay({ amount: 1500, currency: 'CZK' }, (event) => { // 15.00 Kč
          switch (event.type) {
              case 'creating': /* registering the payment */ break;
              case 'created': /* backend payment created: event.paymentToken */ break;
              case 'launched': /* Tapaya Terminal is in the foreground */ break;
              case 'result':
                  switch (event.payResult.type) {
                      case 'success': showReceipt(event.payResult.paymentToken, event.payResult.authCode); break;
                      case 'declined': showDeclined(event.payResult.metadata); break;
                      case 'canceled': showCancelled(event.payResult.metadata); break;
                      case 'failed': showUnexpected(event.payResult.reason); break; // PayFailureReason
                  }
                  break;
              case 'creationFailed': handleError(event.error); break; // AcceptError payload
          }
      });
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  * `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)`.

  <Callout title="metadata is best-effort" type="info">
    `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.
  </Callout>

  <Accordions type="multiple">
    <Accordion title="Parameters" id="pay-parameters">
      | Parameter            | Type                        | Required | Description                                                                                                                                                                                                                                             |
      | :------------------- | :-------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
      | `amount`             | `Long`                      | ✓        | Amount to charge, in the minor unit of `currency` (e.g. cents for USD, hellers for CZK).                                                                                                                                                                |
      | `currency`           | `String`                    | ✓        | ISO 4217 currency code.                                                                                                                                                                                                                                 |
      | `paymentToken`       | `String?`                   |          | Resumes an existing payment session instead of starting a new one. Defaults to `null`.                                                                                                                                                                  |
      | `receiptConfig`      | `PaymentReceiptConfig?`     |          | Overrides the receipt screen shown after an **approved** payment, for this call only. Defaults to `null`, which falls back to the default set with `Accept.payments.setOptions()`. See [Configure the receipt screen](#configuring-the-receipt-screen). |
      | `nfcPosition`        | `NfcPositionConfig?`        |          | Overrides where the tap-to-pay animation points, for this call only. Defaults to `null`, which falls back to the default set with `Accept.payments.setOptions()`. See [Position the NFC tap animation](#positioning-the-nfc-tap-animation).             |
      | `metadata`           | `Map<String, String>`       |          | Key-value data attached to the payment. Sent to the Tapaya Terminal plugin on the `PAY` intent and echoed back on the resulting `PayResult`, if the plugin returns it. Defaults to `emptyMap()`.                                                        |
      | `tip`                | `Long?`                     |          | Fixed tip, in the minor unit of `currency`. When set, the plugin skips its own interactive tip screen and charges `amount + tip`. Defaults to `null` (plugin prompts the payer for a tip).                                                              |
      | `transactionTimeout` | `Duration?`                 |          | Overrides how long the terminal waits for a card tap, for this call only. Defaults to `null`, which falls back to the default set with `Accept.payments.setOptions()`. See [Set a transaction timeout](#setting-a-transaction-timeout).                 |
      | `display`            | `PaymentDisplay?`           |          | Overrides which screen runs the plugin's payment UI, for this call only. Defaults to `null`, which falls back to the default set with `Accept.payments.setOptions()`. See [Target a display](#targeting-a-display).                                     |
      | `customerFacingFlip` | `CustomerFacingFlipConfig?` |          | Overrides whether the payment UI turns 180° toward the customer, for this call only. Defaults to `null`, which falls back to the default set with `Accept.payments.setOptions()`. See [Turn off the customer-facing flip](#customer-facing-flip).       |
    </Accordion>

    <Accordion title="Choose the currency" id="choosing-the-currency">
      `pay()` charges in the `currency` you pass, as an uppercase ISO 4217 code, with `amount` in that currency's minor
      unit. [Supported Currencies](/merchants/supported_currencies) lists every currency Tapaya supports, but a merchant is
      usually enabled for only some of them.

      * Call `Accept.merchant.availableCurrencies()` for the ISO 4217 codes the merchant is enabled for. Paying in any
        other currency fails with `CurrencyNotAvailableForMerchant`.
      * Each currency also has a minimum payable amount, enforced platform-wide. Fetch the current minimums with
        `Accept.sdk.minimumAmounts()`, which returns a `List<MinimumAmount>` (`currency: String, amount: Long`, in the
        currency's minor unit).
      * Calling `pay()` below that minimum fails with `PaymentEvent.CreationFailed(AmountBelowMinimum(minimum, currency))`.
        See [Error handling](./sdk_integration#error-handling) for the full exception list.
    </Accordion>
  </Accordions>

  ### Read the payment outcome [#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()`.

  <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="kotlin">
        Android (Kotlin)
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="typescript">
        React Native (TypeScript)
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="kotlin">
      ```kotlin
      val status: PaymentStatus = Accept.payments.status(paymentToken)
      status.state       // PENDING, SUCCESS, CANCELLED, REFUNDED, FAILED, ACTION_NEEDED
      status.receiptUrl  // for your receipt UI
      ```
    </CodeBlockTab>

    <CodeBlockTab value="typescript">
      ```typescript
      const status = await Accept.payments.status(paymentToken);
      status.state;      // PENDING, SUCCESS, CANCELLED, REFUNDED, FAILED, ACTION_NEEDED
      status.receiptUrl; // for your receipt UI
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  * 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`.

  <Accordions type="multiple">
    <Accordion title="Result variants" id="result-variants">
      | `PayResult`                                                 | Meaning                                                                                                                                                                                           |
      | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
      | `Success(paymentToken, metadata, authCode, receiptDetails)` | Authorized and captured. Funds will settle to the merchant. `authCode` is the processor authorization code reported by the terminal; informational, and may be absent depending on the processor. |
      | `Declined(metadata, receiptDetails)`                        | Rejected by the card processor or issuing bank.                                                                                                                                                   |
      | `Canceled(metadata)`                                        | Cancelled by the customer or merchant before completion.                                                                                                                                          |
      | `Failed(reason, metadata)`                                  | Did not complete; `reason` is a `PayFailureReason`.                                                                                                                                               |

      `PayFailureReason` is one of `INVALID_INTENT`, `NOT_ACTIVATED`, `TERMINAL_INIT_FAILED`, `PAYMENT_SETUP_FAILED`,
      `PLUGIN_UNAVAILABLE`, or `UNKNOWN`.
    </Accordion>

    <Accordion title="Read receipt details" id="reading-receipt-details">
      `Success` and `Declined` carry an optional `receiptDetails: ReceiptDetails?` with structured card-receipt data
      reported by the terminal, for callers that print their own official card receipt instead of relying solely on
      `PaymentStatus.receiptUrl`'s hosted page.

      | Field                  | Type      | Description                            |
      | :--------------------- | :-------- | :------------------------------------- |
      | `merchantId`           | `String?` | Merchant ID reported by the processor. |
      | `terminalId`           | `String?` | Terminal ID reported by the processor. |
      | `cardBrand`            | `String?` | Card brand, e.g. Visa or Mastercard.   |
      | `appLabel`             | `String?` | EMV application label.                 |
      | `aid`                  | `String?` | EMV application identifier.            |
      | `maskedPan`            | `String?` | Masked card number.                    |
      | `responseCode`         | `String?` | Processor response code.               |
      | `transactionTimestamp` | `String?` | ISO-8601 transaction timestamp.        |

      Every field is optional and best-effort; a caller must be prepared for any of them, or `receiptDetails` itself,
      to be absent.
    </Accordion>
  </Accordions>

  ### Refund a payment [#refund-a-payment]

  Refund a settled payment with `Accept.payments.refund(paymentToken, reason)`, which also returns the resulting
  `PaymentState`.

  <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="kotlin">
        Android (Kotlin)
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="typescript">
        React Native (TypeScript)
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="kotlin">
      ```kotlin
      val state: PaymentState = Accept.payments.refund(paymentToken, RefundReason.CUSTOMER_REQUEST)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="typescript">
      ```typescript
      const state = await Accept.payments.refund(paymentToken, 'CUSTOMER_REQUEST');
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  * `RefundReason` is one of `CUSTOMER_REQUEST`, `DUPLICATE`, `FRAUDULENT`, or `EXPIRED_CHARGE`.
</div>

## Customize the payment [#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()`.

<Accordions type="multiple">
  <Accordion title="Configure the receipt screen" id="configuring-the-receipt-screen">
    `receiptConfig` controls what the Tapaya Terminal plugin shows the payer after an **approved** payment, and how
    long it stays on screen and whether it prints. It has no effect on declined, reversed, or pending-reversal
    outcomes; those always show their own outcome screen regardless of this setting.

    <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="kotlin">
          Android (Kotlin)
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="typescript">
          React Native (TypeScript)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="kotlin">
        ```kotlin
        // Set a default, e.g. once at app startup
        Accept.payments.setOptions(
            receiptConfig = PaymentReceiptConfig.Show(
                showQrCodeReceipt = true,
                dismissBehavior = DismissBehavior.Delayed(30.seconds),
                printBehavior = ReceiptPrintBehavior.Automatic,
            ),
        )

        // Override it for a single payment
        Accept.payments.pay(
            amount = 1500,
            currency = "CZK",
            receiptConfig = PaymentReceiptConfig.DismissImmediately,
        )
        ```
      </CodeBlockTab>

      <CodeBlockTab value="typescript">
        ```typescript
        // Set a default, e.g. once at app startup
        Accept.payments.setOptions({
            receiptConfig: {
                type: 'show',
                showQrCodeReceipt: true,
                dismissBehavior: { type: 'delayed', delayMs: 30_000 },
                printBehavior: 'automatic',
            },
        });

        // Override it for a single payment
        await Accept.payments.payAsync({
            amount: 1500,
            currency: 'CZK',
            receiptConfig: { type: 'dismissImmediately' },
        });
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    `PaymentReceiptConfig` is one of:

    * `DismissImmediately`: nothing is shown to the payer.
    * `Show(showQrCodeReceipt, dismissBehavior, printBehavior)`: shows the receipt screen.
      * `showQrCodeReceipt: Boolean = true` toggles a QR code linking to the receipt.
      * `dismissBehavior: DismissBehavior = DismissBehavior.Manual` controls how it closes: `Manual` (stays until the
        payer dismisses it) or `Delayed(delay: Duration)` (auto-dismisses after `delay` if the payer hasn't dismissed
        it first).
      * `printBehavior: ReceiptPrintBehavior = ReceiptPrintBehavior.OnDemand` controls the physical receipt:
        `Automatic` (prints as soon as the screen appears), `OnDemand` (only when the cashier triggers it), or
        `Disabled` (never prints).

    Until `setOptions()` is called, the default is `Show` with a QR receipt, manual dismiss, and on-demand printing,
    matching the plugin's own fallback.
  </Accordion>

  <Accordion title="Position the NFC tap animation" id="positioning-the-nfc-tap-animation">
    `nfcPosition` is a hint telling the Tapaya Terminal plugin where this device's NFC antenna is, so it can place the
    "tap here" animation correctly. The plugin resolves antenna position on its own first (live platform detection,
    then a bundled device database, then anything the merchant configured directly in the plugin); only provide this
    to override that resolution, for example on a device the plugin can't detect or has wrong in its database.

    | `NfcPositionConfig`                       | Description                                                                                                                                                                                                                                                       |
    | :---------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `Unspecified`                             | No override (default). The plugin resolves the position itself and keeps any position the merchant already configured there.                                                                                                                                      |
    | `OnDevice(surface, xFraction, yFraction)` | The antenna is on the device itself; the animation points at `(xFraction, yFraction)` on `surface`, either `OnDeviceSurface.BACK` or `OnDeviceSurface.FRONT_SCREEN`.                                                                                              |
    | `ExternalAbove`                           | A separate reader module sits above the phone (smart-POS scaffold); there's no on-device point to place.                                                                                                                                                          |
    | `ExternalReader(message, indicator)`      | A separate reader that is not above the phone, such as a counter reader, a pinpad, a dock, or a kiosk reader below the screen. `message` replaces the "tap the card on the reader" prompt; you translate it. `indicator` shows animated arrows toward the reader. |

    Set a device-wide default with `Accept.payments.setOptions(nfcPosition = ...)`, or override it per call via
    `pay(..., nfcPosition = ...)`.

    For a kiosk or dock reader outside the screen, point the arrows at it with a `ReaderIndicator`:

    <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="kotlin">
          Android (Kotlin)
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="typescript">
          React Native (TypeScript)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="kotlin">
        ```kotlin
        Accept.payments.setOptions(
            nfcPosition = NfcPositionConfig.ExternalReader(
                indicator = ReaderIndicator(edge = ReaderEdge.BOTTOM, offsetFraction = 0.5f),
            ),
        )
        ```
      </CodeBlockTab>

      <CodeBlockTab value="typescript">
        ```typescript
        Accept.payments.setOptions({
            nfcPosition: {
                type: 'externalReader',
                indicator: { edge: 'bottom', offsetFraction: 0.5 },
            },
        });
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    * `edge` is the screen edge the reader sits beyond, `TOP`, `RIGHT`, `BOTTOM`, or `LEFT`, in the device's natural
      orientation. The arrows follow screen rotation.
    * `offsetFraction` is where along that edge, from `0` to `1`: left to right on the top and bottom edges, top to
      bottom on the left and right. It defaults to `0.5`.
    * Without an `indicator`, no arrows show. An older Tapaya Terminal build ignores it.
  </Accordion>

  <Accordion title="Set a transaction timeout" id="setting-a-transaction-timeout">
    `transactionTimeout` controls how long the Tapaya Terminal plugin waits for the customer to tap their card before
    giving up. It accepts any `Duration` from zero up to 120 seconds.

    <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="kotlin">
          Android (Kotlin)
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="typescript">
          React Native (TypeScript)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="kotlin">
        ```kotlin
        Accept.payments.pay(
            amount = 1500,
            currency = "CZK",
            transactionTimeout = 90.seconds,
        )
        ```
      </CodeBlockTab>

      <CodeBlockTab value="typescript">
        ```typescript
        await Accept.payments.payAsync({
            amount: 1500,
            currency: 'CZK',
            transactionTimeoutMs: 90_000, // milliseconds, 0…120000
        });
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    * A value outside that range surfaces as `TransactionTimeoutOutOfRange(transactionTimeout)` via
      `PaymentEvent.CreationFailed`, since `pay()` never throws synchronously.
    * Leave it at the default `null` to use the companion's own fallback of around 60 seconds, or set a device-wide
      default with `Accept.payments.setOptions(transactionTimeout = ...)`.
  </Accordion>

  <Accordion title="Target a display" id="targeting-a-display">
    On a dual-sided ("double-sided") device, one panel faces the merchant and a second, customer-facing panel faces
    the payer. `Accept.displays` reports what the device has right now, and the `display` option tells the plugin
    which panel to run its payment UI on.

    <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="kotlin">
          Android (Kotlin)
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="typescript">
          React Native (TypeScript)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="kotlin">
        ```kotlin
        if (Accept.displays.isDualScreen) {
            val customerPanel = Accept.displays.customerFacing() // AcceptDisplay?, null on single-screen devices
        }

        Accept.payments.pay(
            amount = 1500,
            currency = "CZK",
            display = PaymentDisplay.CustomerFacing,
        )
        ```
      </CodeBlockTab>

      <CodeBlockTab value="typescript">
        ```typescript
        if (Accept.displays.isDualScreen) {
            const customerPanel = Accept.displays.customerFacing(); // null on single-screen devices
        }

        await Accept.payments.payAsync({
            amount: 1500,
            currency: 'CZK',
            display: { type: 'customerFacing' },
        });
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    | `PaymentDisplay`      | Description                                                                            |
    | :-------------------- | :------------------------------------------------------------------------------------- |
    | `Default`             | The host app's current display (default behavior, unchanged on single-screen devices). |
    | `CustomerFacing`      | The secondary panel of a dual-sided device.                                            |
    | `Specific(displayId)` | An explicit display, by the `id` reported in `Accept.displays.all()`.                  |

    * A target that can't be honored, for example `CustomerFacing` on a single-screen device, silently falls back to
      `Default`. Set a device-wide default with `Accept.payments.setOptions(display = ...)`, or override it per call
      via `pay(..., display = ...)`.
    * Set the target before authenticating. The terminal warm-up fired by `Accept.auth.authenticate()` follows the
      same target, so call `setOptions(display = ...)` before `authenticate()` if you want the warm-up itself to stay
      off the merchant's screen.
    * The `:dualscreen` sample app demonstrates a full two-panel checkout: the merchant works the primary panel while
      `PaymentDisplay.CustomerFacing` puts the plugin's payment UI on the customer's screen.
  </Accordion>

  <Accordion title="Turn off the customer-facing flip" id="customer-facing-flip">
    When the merchant turns a handheld device toward the customer, Tapaya Terminal turns its payment UI 180° so the
    customer can read it. On hardware that already faces the customer, such as a fixed POS, a two-sided terminal, or
    a device in a stand, that turn never happens, and the motion sensors only cause accidental flips. Turn it off
    there.

    <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="kotlin">
          Android (Kotlin)
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="typescript">
          React Native (TypeScript)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="kotlin">
        ```kotlin
        Accept.payments.setOptions(customerFacingFlip = CustomerFacingFlipConfig.Disabled)
        ```
      </CodeBlockTab>

      <CodeBlockTab value="typescript">
        ```typescript
        Accept.payments.setOptions({ customerFacingFlip: 'disabled' });
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    * `Automatic` is the default, and flips the UI when the device turns toward the customer.
    * Override it for one payment with `pay(..., customerFacingFlip = ...)`.
    * An older Tapaya Terminal build ignores it.
  </Accordion>

  <Accordion title="Brand the terminal app" id="branding-the-terminal-app">
    `Accept.setTheme()` applies your colors and logos to Tapaya Terminal's activation, status, and payment screens, so
    they match your app.

    <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="kotlin">
          Android (Kotlin)
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="typescript">
          React Native (TypeScript)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="kotlin">
        ```kotlin
        Accept.setTheme(
            AcceptTheme(
                light = AcceptThemeVariant(
                    colors = AcceptThemeColors(primary = "#0B5FFF", onPrimary = "#FFFFFF"),
                    images = AcceptThemeImages(logoSymbol = "https://example.com/logo.png"),
                ),
                dark = AcceptThemeVariant(
                    colors = AcceptThemeColors(primary = "#6E9BFF", onPrimary = "#001B3D"),
                ),
            ),
        )
        ```
      </CodeBlockTab>

      <CodeBlockTab value="typescript">
        ```typescript
        Accept.setTheme({
            light: {
                colors: { primary: '#0B5FFF', onPrimary: '#FFFFFF' },
                images: { logoSymbol: 'https://example.com/logo.png' },
            },
            dark: {
                colors: { primary: '#6E9BFF', onPrimary: '#001B3D' },
            },
        });
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    * Colors are hex strings, `#RRGGBB` or `#AARRGGBB`. Images are `logoText`, `logoTextSolid`, `logoSymbol`, and
      `logoSymbolWithBackground`, each a URL.
    * Anything you leave out keeps the theme set for your organization in the Tapaya Platform. The theme lasts until
      you change it, pass `null`, or call `Accept.clear()`.
    * For a logo stored in your app, `Accept.createLocalThemeImageUri()` turns its bytes into a `content://` URL
      Tapaya Terminal can read. It takes a byte array on Android and a base64 string on React Native.
  </Accordion>
</Accordions>

## Integrate without the SDK [#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](https://api.tapaya.com/openapi/index.html) and keep
   its `paymentId`.
2. Open Tapaya Terminal with that `paymentId` using the [pay deeplink](#pay-deeplink).
3. Poll the payment status via the [Payments API](https://api.tapaya.com/openapi/index.html) until it leaves
   `PENDING`. Deeplinks have no return channel, so polling is the only source of truth.

<Callout title="No activation step" type="info">
  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](#login-deeplink) if needed.
</Callout>

<Accordions type="multiple">
  <Accordion title="Deeplink schemes" id="deeplink-schemes">
    The scheme selects which build of Tapaya Terminal handles the link:

    * Production: `tapaya-accept`
    * Sandbox: `tapaya-accept-sandbox`

    If a link doesn't resolve, that build of Tapaya Terminal is not installed.
  </Accordion>

  <Accordion title="Pay deeplink" id="pay-deeplink">
    ```text
    tapaya-accept://pay?paymentId=<paymentId>&amount=<amount>&currency=<ISO4217>
    ```

    | Query parameter | Required | Notes                                                                                                                       |
    | :-------------- | :------- | :-------------------------------------------------------------------------------------------------------------------------- |
    | `paymentId`     | **Yes**  | The payment created in step 1.                                                                                              |
    | `amount`        | **Yes**  | Amount in **major units** as a whole number: `amount=15` charges 15.00. This differs from the SDK, which takes minor units. |
    | `currency`      | **Yes**  | ISO 4217 currency code, e.g. `CZK`.                                                                                         |

    <CodeBlockTabs defaultValue="kotlin" groupId="accept-language">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="kotlin">
          Android (Kotlin)
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="typescript">
          React Native (TypeScript)
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="kotlin">
        ```kotlin
        val uri = Uri.parse("tapaya-accept://pay?paymentId=$paymentId&amount=15&currency=CZK")
        try {
            startActivity(Intent(Intent.ACTION_VIEW, uri).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
        } catch (e: ActivityNotFoundException) {
            // Tapaya Terminal is not installed, send the user to Google Play
        }
        ```
      </CodeBlockTab>

      <CodeBlockTab value="typescript">
        ```typescript
        import { Linking } from 'react-native';

        const url = `tapaya-accept://pay?paymentId=${paymentId}&amount=15&currency=CZK`;
        try {
            await Linking.openURL(url);
        } catch {
            // Tapaya Terminal is not installed, send the user to Google Play
        }
        ```
      </CodeBlockTab>
    </CodeBlockTabs>
  </Accordion>

  <Accordion title="Login deeplink" id="login-deeplink">
    Sign a merchant in to Tapaya Terminal with their `merchantToken`, the merchant identifier you set with
    `POST /merchant/auth/register`:

    ```text
    tapaya-accept://login?token=<merchantToken>
    ```

    | Query parameter  | Required | Notes                                                                                                                            |
    | :--------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------- |
    | `token`          | **Yes**  | The merchant's `merchantToken`. This is your stable merchant ID, not the short-lived SDK token from `POST /merchant/auth/login`. |
    | `activationCode` | No       | Pre-fills the terminal activation code.                                                                                          |
  </Accordion>
</Accordions>

## Test the integration [#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 [#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](#payment-outcome).

<Accordions type="multiple">
  <Accordion title="Payment creation errors" id="payment-creation-errors">
    Failures that stop the payment from being created arrive as `PaymentEvent.CreationFailed(cause)`, where `cause` is
    a typed `AcceptException`. The ones specific to this integration:

    | Exception                                          | When it happens                                                                                                    | What to do                                                             |
    | :------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------- |
    | `PluginUnavailable`                                | The Tapaya Terminal plugin is not installed or its service could not be bound.                                     | Prompt installation with `Accept.plugin.install()`.                    |
    | `CurrencyNotAvailableForMerchant(code)`            | The merchant is not configured for the requested currency.                                                         | Charge in an enabled currency, or update the merchant's configuration. |
    | `AmountBelowMinimum(minimum, currency)`            | The amount is below the configured minimum.                                                                        | Charge at or above `minimum`.                                          |
    | `TransactionTimeoutOutOfRange(transactionTimeout)` | `transactionTimeout` was outside the 0 to 120 second range.                                                        | Pass a value within range, or omit it to use the default.              |
    | `LocationPermissionRequired`                       | Your app has not been granted location permission.                                                                 | Request `ACCESS_FINE_LOCATION`, then retry.                            |
    | `LocationUnavailable` / `LocationTimeout`          | The device has never had a location fix, and none arrived in time. The SDK otherwise uses the last known location. | Ask the user to enable location and retry.                             |
    | `SessionExpired`                                   | The authenticated session expired.                                                                                 | Re-authenticate with `Accept.auth.authenticate()`.                     |
    | `NoInternetConnection`                             | No network connectivity.                                                                                           | Ask the user to reconnect and retry.                                   |
    | `PaymentInProgress`                                | A previous `pay()` call is still awaiting a result.                                                                | Wait for the current payment to finish.                                |
  </Accordion>

  <Accordion title="Status, cancel, and refund errors" id="status-cancel-and-refund-errors">
    * `Accept.payments.status()`, `cancel()`, and `refund()` are `suspend` functions and **throw** these exceptions
      (rather than emitting events); wrap them in `try-catch`.
    * They also throw `PaymentNotFound` for an unknown token.
    * See the full list in [Error Handling](../integration/sdk_integration#error-handling).
  </Accordion>

  <Accordion title="Install errors" id="install-errors">
    `Accept.plugin.install()` throws when it cannot install Tapaya Terminal: `PluginStoreUnavailable`,
    `PluginSelfInstallUnavailable`, `PluginInstallAuthRequired`, `PluginInstallPermissionRequired`, or
    `PluginDownloadNotPermitted`. See [Install on devices without an app store](#install-without-an-app-store) for
    what each one needs.
  </Accordion>

  <Accordion title="Timeouts" id="timeouts">
    A card payment must be completed on the terminal shortly after it starts. If the customer never taps, or the
    Tapaya Terminal plugin is closed mid-payment, the payment ends as `PayResult.Canceled` or `PayResult.Failed`, and
    the underlying payment is cancelled server-side and never settles. Always confirm the final state with
    `Accept.payments.status()` before treating a payment as complete.
  </Accordion>
</Accordions>
