Connecting to the BBPOS Chipper 2X BT

The BBPOS Chipper 2X BT is a Bluetooth LE device. It collects payment details, but relies on a paired mobile device for communication with Stripe. Connecting your app to a Bluetooth reader requires two steps:

• Discovering readers
• Connecting to a reader

Use this guide to connect your application to the reader using the discoverReaders and connectReader methods.

Discovering readers

import UIKit
import StripeTerminal

class ReaderDiscoveryViewController: UIViewController, DiscoveryDelegate {

    var discoverCancelable: Cancelable?

    // ...

    // Action for a "Discover Readers" button
    func discoverReadersAction() {
        let config = DiscoveryConfiguration(
          discoveryMethod: .bluetoothProximity,
          simulated: false
        )

        self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
            if let error = error {
                print("discoverReaders failed: \(error)")
            } else {
                print("discoverReaders succeeded")
            }
        }
    }

    // ...

    // MARK: DiscoveryDelegate

    func terminal(_ terminal: Terminal, didUpdateDiscoveredReaders readers: [Reader]) {
        // In your app, display the discovered reader(s) to the user.
        // Call `connectReader` after the user selects a reader to connect to.
    }
}

Depending on your SDK, you can use either the bluetoothProximity or bluetoothScan discovery method to search for readers.

Bluetooth proximity

Bluetooth proximity filters search results to return the closest reader. When discovered, the reader flashes multicolored lights, making it easy for your user to identify the discovered reader among many other readers. After the SDK discovers a reader, it won’t switch to a closer reader unless you turn off the discovered reader.

Note that when using Bluetooth proximity, the SDK returns the reader to your app’s callback twice. The first time, your app receives a Reader object populated with only the reader’s serial number. After a short delay, your app receives the same Reader object populated with new information, such as the reader’s battery level.

We recommend displaying the discovered reader in your app’s UI, letting the user either confirm connection to the reader or cancel if they don’t want to connect to this reader.

Bluetooth scan

Bluetooth scan searches for all nearby readers and returns a list of discovered readers to your app. As the discovery process continues, the SDK continues to invoke the DiscoveryDelegate.didUpdateDiscoveredReaders method with the latest list of nearby readers.

With the Bluetooth scan discovery method, you can set a timeout to scan for a set period of time. This is useful for managing battery life or triggering an error message if no devices are found.

In your mobile application, we recommend displaying an auto-updating list of discovered readers, with serial numbers or labels to help users identify their reader.

Connecting to a reader

To connect to a discovered reader, call the connectReader method from your app. As soon as the SDK connects to the reader, the reader’s status light shines steady blue.

let config = ConnectionConfiguration(failIfInUse: true)
Terminal.shared.connectReader(selectedReader, connectionConfig: config) { reader, error in
  if let reader = reader {
      print("Successfully connected to reader: \(reader)")
  } else if let error = error {
      print("connectReader failed: \(error)")
  }
}

On iOS, for your app to run in the background and remain connected to the reader, configure your app to include the required background mode.

Don’t program your app to call disconnectReader to conserve power. The reader efficiently handles power management using its standby mode.

Handling disconnects

Your app must implement the UnexpectedReaderDisconnect callback to handle when a reader disconnects.

In your implementation of this callback, display a UI to notify the user that the reader disconnected. You may also want to call discoverReaders to begin scanning for readers and reconnect. Your app can attempt to automatically reconnect to the reader that disconnected, or display a UI for your user to reconnect to another reader.

The BBPOS Chipper 2X BT can disconnect from your app if it goes out of range or runs out of battery. To simulate an unexpected disconnect while testing, power off the reader.

import StripeTerminal

class ReaderViewController: UIViewController, TerminalDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        Terminal.shared.delegate = self
    }

    // ...

    // MARK: TerminalDelegate

    func terminal(_ terminal: Terminal, didReportUnexpectedReaderDisconnect reader: Reader) {
        // You might want to display UI to notify the user and start re-discovering readers
    }
}

You’ve connected your app to the reader. Next, collect your first Stripe Terminal payment.