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:

• The device contains a functioning NFC antenna and chipset.
• The device has a hardware-backed keystore.
• The device runs a current version of Android (Android 11 or above).
• 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.

Using the non-simulated, production version of the Tap to Pay reader with debuggable applications isn’t supported for security and compliance reasons. 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 following requirements:

• The device has a stable connection to the internet.
• The device isn’t rooted and the device bootloader is locked and unchanged.
• The device uses Google Mobile Services.
• The device runs a current version of Android (Android 11 or above).
• The application uses a supported version of the Tap to Pay SDK (currently 2.20.0 or above).

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
      }
  }
)