Connect to a reader
Connect your application to a Stripe Terminal 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.
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.
When a reader disconnects, we recommend you automatically attempt reconnection and display notifications in your app relaying the reader status throughout the process.
To implement automatic reconnection:
- Set
autoReconnectOnUnexpectedDisconnect
to true on theConnectionConfiguration
. - Implement the callbacks found in the
ReaderReconnectionListener
. - Pass a
usbReaderReconnectionListener
to yourConnectionConfiguration
. - When the SDK sends onReaderReconnectStarted to your app, display a message announcing that the reader lost connection and reconnection is in progress.
- You can use the
Cancelable
object to stop the reconnection attempt at any time.
- You can use the
- When the SDK indicates successful reconnection by sending onReaderReconnectSucceeded, display a message announcing the connection was restored and to continue normal operations.
- If the SDK can’t reconnect to the reader and sends onReaderReconnectFailed, display a message stating that an unexpected disconnect occurred.
If you don’t configure automatic reconnection, you can handle the disconnect callback to just display a message in the app alerting the user that the reader unexpectedly disconnected and initiate reader discovery and connection.
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 (Android).
- When your app launches, check the persistent data storage location 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.
Display some UI during the discovery and connection process to indicate that an automatic reconnection is happening.
Update reader softwareClient-side
Your application must update Bluetooth and USB readers to apply:
- Regional configurations that keep you up to date with card network and issuer requirements
- Security updates
Required updates start installing on connection to the reader. You can’t use the reader until updating completes.
Note
In order to install updates, the reader’s battery level must be higher than 50%.
Required updates
When immediately required updates are available for the reader, the integration’s ReaderListener
receives onStartInstallingUpdate
with a ReaderSoftwareUpdate
.
The ReaderSoftwareUpdate
provides the necessary details of the update, including an estimate of the total update duration, indicated by timeEstimate
.
During the installation process, the Terminal’s connectionStatus
transitions to ConnectionStatus.
while the update installs on the reader.
Your application must notify users that an update is installing and display the progress in your UI. Make it clear why connecting might take longer than usual.
If the required update process fails, Stripe communicates the error to the ReaderListener
with onFinishInstallingUpdate
. You can’t reconnect to the reader after a required update fails, unless the following conditions are met:
- The reader runs the latest software version for the location within the last 30 days.
- The Android SDK version is greater than or equal to
3.
.5. 0
If the conditions are met, the connection process succeeds despite an incomplete update. Stripe retries the required update the next time you connect to that reader until it’s successfully installed.
You can cancel required updates using the Cancelable
object, which also results in a failed connection to the reader. You can’t cancel incremental-only updates.
Optional updates
You can defer optional updates until the specified date, after which they become required. The SDK notifies you of optional updates through the ReaderListener
any time the reader is connected but not performing a transaction. If an optional update is available, your application’s ReaderListener
receives the onReportAvailableUpdate
callback with the ReaderSoftwareUpdate
object containing the update details, including:
- Estimated time for update to complete (
timeEstimate
) - Date after which the update becomes required (
requiredAt
)
In your application, notify users that an update is available, and display a prompt to optionally continue with the update.
To proceed with the update previously reported with onReportAvailableUpdate
, call Terminal.
.
The available update is also stored on the reader object as reader.
.
As the update proceeds, block the user from leaving the page in your app, and instruct the user to keep the reader connected until the update completes. We recommend also providing your user with a visual indicator of the update’s progress. The ReaderListener
reports the update’s progress in the onReportReaderSoftwareUpdateProgress
method.
When an optional update’s requiredAt
date has passed, the update installs the next time the reader is connected.
See Testing reader updates to learn more about making sure your application handles the different update types that a reader can have.
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.