Connect to a reader

Before you can connect your application to a smart reader, you must register the reader to your account.

Register in the Dashboard

You can add your reader directly in the Dashboard.

1. If you already created a Location, click it. Otherwise, create one by clicking + New.
2. Under the Readers section, click + New.
3. If you have a Verifone P400, enter the key sequence 0-7-1-3-9 to display a unique registration code. If you have a BBPOS WisePOS E or Stripe Reader S700, go to the reader settings and tap Generate pairing code.
4. Enter the code when prompted.

Register using the API

For larger deployments, enable users in the field to receive and set up new readers on their own. In your app, build a flow to register a reader with the Stripe API.

1. If you have a Verifone P400, enter the key sequence 0-7-1-3-9 to display a unique registration code. If you have a BBPOS WisePOS E or Stripe Reader S700, go to the reader settings and tap Generate pairing code.
2. The user enters the code in your application.
3. Your application sends the code to Stripe:

curl https://api.stripe.com/v1/terminal/readers \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d registration_code={{READER_REGISTRATION_CODE}} \
  --data-urlencode label="Alice's reader" \
  -d location=
{{LOCATION_ID}}

To confirm that you’ve registered a reader correctly, list all the readers you’ve registered at that location:

curl https://api.stripe.com/v1/terminal/readers \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:

After registering the reader to your account, search for previously registered readers to connect to your point of sale application using the discoverReaders method. You can scope your discovery using the location you registered the reader to in the previous step.

var discoveryCancelable: Cancelable? = null

fun onDiscoverReaders() {
    val config = InternetDiscoveryConfiguration(
        isSimulated = false,
        location = 
"{{LOCATION_ID}}"
    )

    // Save this cancelable to an instance variable
    discoveryCancelable = Terminal.getInstance().discoverReaders(
        config,
        object : DiscoveryListener {
            override fun onUpdateDiscoveredReaders(readers: List<Reader>) {
                // Display the discovered readers to the user
            }
        },
        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 connect your point of sale application to a reader, call connectReader with the selected reader.

val internetReaderListener = yourInternetReaderListener
val config = ConnectionConfiguration.InternetConnectionConfiguration(internetReaderListener)
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
        }
    }
)

Multiple connections

Only one instance of the Stripe Terminal SDK can connect to a reader at a given time. By default, when you call connectReader from another application, the incoming connection replaces the existing SDK-to-reader connection, and the previously connected SDK disconnects from the reader. The connectReader method takes a configuration object with a failIfInUse property, whose default value is false. When your application sets failIfInUse to true, the connectReader call has an alternate behavior where the incoming connection fails when the reader is in the middle of a collectPaymentMethod or confirmPaymentIntent call initiated by another SDK. If the reader is connected to another SDK but is idle (displaying the splash screen before collectPaymentMethod is called), setting failIfInUse has no change to the connection behavior, and the incoming connection request can always break the existing SDK-to-reader connection.

val failIfInUse = true
val internetReaderListener = yourInternetReaderListener
val config = InternetConnectionConfiguration.InternetConnectionConfiguration(failIfInUse, internetReaderListener)
Terminal.getInstance().connectReader(
    reader,
    config,
    object : ReaderCallback {
        override fun onSuccess(reader: Reader) {
            // Placeholder for handling successful operation
        }

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

For the least-disruptive connection experience in multi-reader environments, we recommend setting failIfInUse to true on your application’s initial connection attempt. Then, allow your users to retry the connection with failIfInUse set to false if the connection fails the first time.

With this setup, one of your users can’t accidentally interrupt a transaction by inadvertently connecting to an in-use reader, but can still connect if needed.

Handle disconnects

Your app must implement the onDisconnect callback to handle when a reader disconnects. When you implement this callback, display a UI that notifies your user of the disconnected reader. You can call discoverReaders to scan for readers and initiate reconnection.

Your app can attempt to automatically reconnect to the disconnected reader or display a UI that prompts your user to reconnect to a different reader.

The reader can disconnect from your app if it loses connection to the network. To simulate an unexpected disconnect, power off the reader.

class ReaderActivity : AppCompatActivity(), InternetReaderListener {
    // ...

    override fun onDisconnect(reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }

    // ...
}

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 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.

Display some UI during the discovery and connection process to indicate that an automatic reconnection is taking place.