Connect to a reader

Create a Location for each physical location where your readers operate. Set the display_name to represent the name of the business. Your customer sees the display_name on the device’s tap screen unless you explicitly provide the name of a business when you connect to a reader. You can edit existing locations as necessary to adjust this text.

If your business requires you to move your readers frequently, your locations can use an address that represents your primary place of business.

To create a location using the API, use the create location request.

Locations for the US require:

• line1
• city
• state
• postal_code
• country

curl https://api.stripe.com/v1/terminal/locations \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d display_name="Venice Burrito Shop" \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"=CA \
  -d "address[country]"=US \
  -d "address[postal_code]"=94110

To create a location in the Dashboard, click the +New button on the Locations page.

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 DiscoveryConfiguration.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 = DiscoveryConfiguration.LocalMobileDiscoveryConfiguration(
        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
    discoveryCancelable?.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 10ms to run on most devices.

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

connectLocalMobileReader 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.
• LOCAL_MOBILE_UNSUPPORTED_ANDROID_VERSION: The user can upgrade their operating system, if an update is available from the device manufacturer.

// After selecting a reader to connect to
val config = ConnectionConfiguration.LocalMobileConnectionConfiguration(
"{{LOCATION_ID}}")
Terminal.getInstance().connectLocalMobileReader(
  firstReader,
  config,
  object : ReaderCallback {
      override fun onSuccess(reader: Reader) {
          // Placeholder for handling successful operation
      }

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