Connecting to a reader

With the SDK initialized in your app, the next step is connecting your app to a reader.

Connecting is important. Readers have some basic functionality of their own, but the connection to the Stripe SDK in your app is what enables readers to accept payments for your business.

The way you handle the connection workflow in your app is also important. Users of your point of sale (e.g., your onsite employees or connected accounts) must be able to connect to a reader from your app easily. For example, if you ship two readers directly to a store location, your app’s UI should include options to discover readers nearby, select the one they want to use, and connect to it.

How connecting works

Connecting your app to the reader takes two steps: discovery and connection.

Discovery

First, your app calls the discoverReaders function and, depending on your reader type, searches for:

• readers over Bluetooth (BBPOS)
• readers registered to your Stripe account (Verifone P400)

It’s up to you to handle the returned list of readers in your application’s UI. Your in-store employees should be able to use your application to clearly discover and select the correct reader (e.g., by its serial number or label).

Connection

After receiving user input, your app calls the connectBluetoothReader or connectInternetReader function with the selected reader. This establishes the reader-to-app communication necessary for taking in-person payments. If necessary, connectReader also fetches a connection token to connect to Stripe and enable payment collection.

When connecting to a Bluetooth reader, the Terminal SDK checks for required updates that need to be installed before the reader can be used. These updates include regional configurations that keep you up to date with card network and issuer requirements, and security updates. If there is a required update, connectReader will install this update before completing the connection. Keep this in mind if you’re implementing an automatic reconnection flow. To learn more about reader updates see Updating reader software.

Automatic reconnection

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.

1. When you successfully connect to a reader, save its serial number in a persistent data storage location, such as the localStorage API (web), the UserDefaults API (iOS), or the Shared Preferences API (Android).
2. 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.
3. 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 should display some UI during the discovery and connection process indicating that an automatic reconnection is taking place.

To see a working example of the steps above, you can refer to the Rocket Rides Pilot App sample code on GitHub. The Rocket Rides Pilot App is a full sample iOS app that demonstrates a checkout flow with Stripe Terminal, and implements automatic reader reconnection using this method.

Next steps