Connect to a reader
Note
If you haven’t chosen a reader yet, compare the available Terminal readers and choose one that best suits your needs.
Use the Stripe Terminal Android SDK 2.22.0 (or later) to support USB connections for the Stripe Reader M2, BBPOS WisePad 3, and BBPOS Chipper 2X BT readers. USB-connected readers avoid Bluetooth interference and disconnection issues by using a wired connection to the reader.
You must use a USB cable that supports both data and charging, like the USB 2.0 cable that’s included with the Stripe Reader M2 and BBPOS WisePad 3. If the cable included with your Terminal reader is charge-only—like the one included with the BBPOS Chipper 2X BT—use a third-party USB 2.0 cable that can transfer data.
Follow these steps to connect your app to a Terminal reader with a USB cable:
Caution
Don’t use mobile device settings to pair with your reader. Pairing the reader through device settings makes the reader unavailable to connect to your app.
Discover readersClient-side
Use the discoverReaders method to enable your point-of-sale app to search for nearby readers. You must set DiscoveryConfiguration.discoveryMethod
to USB to discover USB-connected devices.
Make sure the reader is on and connected with a USB 2.0 cable to the device running your app. When prompted, grant permission to access the USB-connected reader.
If you’re plugging in the reader for the first time, an Android system prompt displays to connect to the reader. You can select the “Always open” checkbox to open your app without prompting when it’s connected to a reader.
Connect to a readerClient-side
To connect to a discovered reader, call the connectUsbReader
method from your app. As soon as the SDK connects to the reader, the reader’s status light shines solid blue.
You must register your reader to a location upon connection. To do so, create and use a UsbConnectionConfiguration
with the locationId
set to the relevant location ID when connecting.
Don’t program your app to call disconnectReader
to conserve power. The reader efficiently handles power management using its standby mode.
Prioritize the connection type
The Terminal SDK doesn’t automatically prioritize one connection type over another. If you want the ability to toggle between discovering devices with USB or Bluetooth, you can implement this functionality in your point-of-sale app. Call discoverReaders
and set the discoveryMethod
in the DiscoveryConfiguration
.
To switch between USB and Bluetooth, call disconnectReader
for your current connection type before initiating the other type. For example, call disconnectReader
for a Bluetooth-connected reader before calling connectUsbReader
.
Handle reader disconnects
Reader disconnects can sometimes occur between your app and the reader. For example, the reader can disconnect from your app if the USB cable connecting it to your device is disconnected. You can simulate an unexpected disconnect while testing by powering off the reader.
The ReaderListener
includes a onDisconnect
callback that provides your application with the DisconnectReason
to help identify why the reader disconnected.
You can handle disconnects in two ways:
1. Handle the disconnect immediately
For this option, your app must implement the UnexpectedReaderDisconnect
callback to manually handle when a reader disconnects. This is the default behavior of the SDK.
In your implementation of this callback, display a UI to notify the user that the reader disconnected.
The reader can disconnect from your app if the USB cable connecting it to your device is disconnected. To simulate an unexpected disconnect while testing, power off the reader.
2. Automatically attempt reconnection
For this option, your app must set autoReconnectOnUnexpectedDisconnect
to true on the UsbConnectionConfiguration
and implement the callbacks found in the ReconnectionListener
. You must also pass a autoReconnectionListener
to your UsbConnectionConfiguration
.
If you automatically attempt reconnection, the following occurs:
- When a disconnect occurs, the SDK automatically attempts to reconnect and notifies you through
onReaderReconnectStarted
. Make sure your app announces that the connection was lost and a reconnection is in progress.
- You can use the
Cancelable
object to stop the reconnection attempt at any time.
- If the SDK successfully reconnects to the reader, you’re notified through
onReaderReconnectSucceeded
. Make sure your app announces that the connection was restored and to continue normal operations. - If the SDK can’t reconnect to the reader, you’re notified through
onReaderReconnectFailed
. Make sure your app announces that an unexpected disconnect occurred.
Reboot the connected reader
Stripe Reader M2 and BBPOS WisePad 3 automatically reboot after operating for 24 hours. However, you can force the reader to reboot and reset its 24-hour timer by using the rebootReader
API. After this action, the reader disconnects from the SDK and then reboots. If you’re using automatic reconnect, the SDK attempts to restore the connection with the reader.
Automatic reconnection on application start
Stripe Terminal doesn’t automatically reconnect to a reader when your application starts. Instead, you can build a reconnection flow by storing reader IDs and attempting to connect to a known reader on startup.
- When you successfully connect to a reader, save its serial number in a persistent data storage location, such as the Shared Preferences API.
- When your app launches, check that persistent store for a saved serial number. If one is found, call the
discoverReaders
method so your application can try to find that reader again. - If the saved serial number matches any of the discovered readers, try connecting to that reader with the matching reader object returned from the call to
discoverReaders
. If the previously connected reader isn’t found, stop the discovery process.
You can display some UI during the discovery and connection process to indicate that an automatic reconnection is taking place.
Update reader softwareClient-side
You must support updating the reader from your application. The reader can’t update itself. These updates include regional configurations that keep you up to date with card network and issuer requirements, as well as potential security updates. Required updates start installing on connection to the reader and must complete before you can use the reader.
Note
Installing updates requires that the reader’s battery is charged to more than 50%.
Required updates
If there are immediately required updates for the reader, the Terminal connectionStatus
changes to ConnectionStatus.CONNECTING
while changes are sent. The connection process won’t complete until the required update is installed on the reader.
For updates expected to take greater than 30 seconds, your application’s ReaderListener
receives onStartInstallingUpdate
with a ReaderSoftwareUpdate
object containing the update details. This includes an estimate of total update duration, timeEstimate
.
In your app, notify users that an update is being installed and display the progress so it’s clear why the connection process is taking longer than usual.
You can cancel required updates using the Cancelable
object. However, this results in a failed connection to the reader. For incremental-only updates, no Cancelable
is provided as these updates can’t be canceled.
Optional updates
Optional updates are announced to your ReaderListener
any time the reader is connected but not performing a transaction. Your app’s ReaderListener
receives the onReportAvailableUpdate
callback with the ReaderSoftwareUpdate
object containing the update details. This update is also stored on the reader object as reader.availableUpdate
, and is installed when calling Terminal.installAvailableUpdate
. The update object includes an estimate of update duration (timeEstimate
) and the future date on which you must install the update (requiredAt
).
In your app, notify users of the available update and display a prompt to optionally continue with the update. To continue, call installAvailableUpdate
to install the update in onReportAvailableUpdate
.
While the update installs, block the user from leaving the page in your app, and instruct them to keep the reader plugged in and powered on until the update completes. We recommend providing your user with a visual indicator of the update’s progress. You can use the onReportReaderSoftwareUpdateProgress
method in your ReaderListener
.
When the requiredAt
date has passed, the optional update won’t install until you disconnect and reconnect the reader.
You can also defer optional updates, but they become required if you don’t install them by a certain date.
Next steps
You’ve connected your application to the reader. Next, collect your first Stripe Terminal payment.
The BBPOS and Chipper™ name and logo are trademarks or registered trademarks of BBPOS Limited in the United States and/or other countries. The Verifone® name and logo are either trademarks or registered trademarks of Verifone in the United States and/or other countries. Use of the trademarks does not imply any endorsement by BBPOS or Verifone.