Connect to a reader

TTPA operates in a dedicated process to make transactions more secure. In this process, a second instance of your Application is created. To avoid any unexpected errors caused by running your code in this process, you can skip initialization in your Application in this process by checking TapToPay.isInTapToPayProcess().

// Substitute with your application name, and remember to keep it the same as your AndroidManifest.xml
class StripeTerminalApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Skip initialization if running in the TTPA process.
        if (TapToPay.isInTapToPayProcess()) return

        // For example, this will be skipped.
        TerminalApplicationDelegate.onCreate(this)
    }
}

Use the discoverReaders method to determine hardware support for Tap to Pay on the Android device. discoverReaders verifies the following requirements about the Android device:

• Has a functioning, integrated NFC sensor and ARM-based processor
• Runs Android 13 or later
• Has a keystore with hardware support for ECDH (FEATURE_HARDWARE_KEYSTORE version must be 100 or later)
• For the non-simulated version of the Tap to Pay reader, the application isn’t debuggable.

Your application must be in the foreground for the Tap to Pay reader service to successfully start.

If your application runs on a device that doesn’t meet the requirements above, the onFailure callback returns with a TerminalException that contains a TerminalErrorCode and additional context. The failures at this stage aren’t actionable by the end user.

You can’t use the non-simulated, production version of the Tap to Pay reader with debuggable applications or with the device’s developer options enabled. To test your integration with the Tap to Pay on Android reader, set TapToPayDiscoveryConfiguration.isSimulated to true during reader discovery. You must set this value to false in the release version of your application.

var discoverCancelable: Cancelable? = null

fun onDiscoverReaders() {
    val isApplicationDebuggable = 0 != applicationInfo.flags and ApplicationInfo.FLAG_DEBUGGABLE
    val config = TapToPayDiscoveryConfiguration(isSimulated = isApplicationDebuggable)

    // Save this cancelable to an instance variable
    discoverCancelable = Terminal.getInstance().discoverReaders(
        config,
        object : DiscoveryListener {
            override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
                // Automatically connect to supported mobile readers
            }
        },
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}

override fun onStop() {
    super.onStop()

    // If you're leaving the activity or fragment without selecting a reader,
    // make sure you cancel the discovery process or the SDK will be stuck in
    // a discover readers phase
    discoverCancelable?.cancel(
        object : Callback {
            override fun onSuccess() {
                // Placeholder for handling successful operation
            }

            override fun onFailure(e: TerminalException) {
                // Placeholder for handling exception
            }
        }
    )
}

To check if a device meets the Tap to Pay hardware and OS requirements at runtime, use the Terminal.supportsReadersOfType function. As part of initializing the Terminal SDK, this function requires your end-user to accept permission requests to access the location and bluetooth. This function takes approximately 10 milliseconds to run on most devices.

To accept Tap to Pay payments, provide the discovered reader from the previous step to the connectReader method.

connectReader verifies the Android device meets the following requirements:

• It isn’t rooted and device bootloader is locked and unchanged
• It uses Google Mobile Services and has the Google Play Store app installed
• It has a stable connection to the internet
• It runs the unmodified manufacturer provided OS
• The application uses Tap to Pay SDK version 2.20.0 or later
• Developer options are disabled for the non-simulated version of the Tap to Pay reader

If your application runs on a device that doesn’t meet the requirements above, the onFailure callback returns with a TerminalException that contains a TerminalErrorCode and additional context. The end user can take action on some of the failure reasons. For example:

• STRIPE_API_CONNECTION_ERROR: The user can connect to a stable internet source.
• TAP_TO_PAY_UNSUPPORTED_ANDROID_VERSION: The user can upgrade their operating system, if an update is available from the device manufacturer.

You must register your reader to a location upon connection. To do so, create and use a TapToPayConnectionConfiguration with the locationId set to the relevant location ID when connecting.

val tapToPayReaderListener = yourTapToPayReaderListener
val autoReconnectOnUnexpectedDisconnect = true

val config = TapToPayConnectionConfiguration(
  
"{{LOCATION_ID}}",
  autoReconnectOnUnexpectedDisconnect,
  tapToPayReaderListener
),
Terminal.getInstance().connectReader(
  firstReader,
  config,
  object : ReaderCallback {
      override fun onSuccess(reader: Reader) {
          // Placeholder for handling successful operation
      }

      override fun onFailure(e: TerminalException) {
          // Placeholder for handling exception
      }
  }
)