Connect to a reader

To start, make sure your reader is powered on and within close proximity.

Then from your app, search for nearby Bluetooth-connected readers with the discoverReaders method, setting discoveryMethod to bluetoothScan.

function DiscoverReadersScreen() {
  const { discoverReaders, discoveredReaders } =
    useStripeTerminal({
      onUpdateDiscoveredReaders: (readers) => {
        // After the SDK discovers a reader, your app can connect to it.
      },
    });

  useEffect(() => {
    handleDiscoverReaders();
  }, []);

  const handleDiscoverReaders = async () => {
    // The list of discovered readers is reported in the `onUpdateDiscoveredReaders` method
    // within the `useStripeTerminal` hook.
    const { error } = await discoverReaders({
      discoveryMethod: 'bluetoothScan',
    });

    if (error) {
      Alert.alert(
        'Discover readers error: ',
        `${error.code}, ${error.message}`
      );
    }
  };

  return <View />;
}

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 onUpdateDiscoveredReaders within the useStripeTerminal hook 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, which you can use 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.

To connect to a discovered reader, call the connectReader method from your app.

You must register your reader to a location upon connection. To do so, make sure locationId is set to the relevant location ID when connecting.

const handleConnectBluetoothReader = async (id) => {
  const { reader, error } = await connectReader(
    {
      reader: selectedReader,
      locationId: 
'{{LOCATION_ID}}',
    },
    'bluetoothScan'
  );

  if (error) {
    console.log('connectReader error', error);
    return;
  }

  console.log('Reader connected successfully', reader);
};

Handle reader disconnects

Reader disconnects can sometimes occur between your app and the reader. For example, the reader can disconnect from your app if it’s out of range or runs out of battery. You can simulate an unexpected disconnect while testing by powering off the reader.

UserCallbacks includes onDidDisconnect that provides your application with the DisconnectReason to help identify why the reader disconnected.

When a reader disconnects, we automatically attempt reconnection by default and recommend that you display notifications in your app relaying the reader status throughout the process.

To display notifications in your app during automatic reconnection, do the following:

1. Set autoReconnectOnUnexpectedDisconnect to true on the ConnectBluetoothReaderParams.
2. Implement the auto reconnect callbacks found in the UserCallbacks.
3. When the SDK sends onDidStartReaderReconnect to your app, display a message announcing that the reader lost connection and reconnection is in progress.
   • You can use cancelReaderReconnection to stop the reconnection attempt at any time.
4. When the SDK indicates successful reconnection by sending onDidSucceedReaderReconnect, display a message announcing the connection was restored and to continue normal operations.
5. If the SDK can’t reconnect to the reader and sends onDidFailReaderReconnect, display a message stating that an unexpected disconnect occurred.

To handle reader disconnects yourself, you can do the following:

1. Set autoReconnectOnUnexpectedDisconnect to false during connection.
2. Handle the disconnect callback to display a message in the app alerting the user that the reader unexpectedly disconnected and initiate reader discovery and connection.

const terminal = useStripeTerminal({
  onDidReportUnexpectedReaderDisconnect: (error) => {
    // Consider displaying a UI to notify the user and start rediscovering readers
  },
});

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.

const { error } = await rebootReader();

if (error) {
  console.log('rebootReader error:', error);
  return;
}

console.log('rebootReader succeeded');

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.

1. When you successfully connect to a reader, save its serial number in a persistent data storage location, such as Async Storage (React Native).

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

Your application must update mobile readers to apply the following:

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

Required updates

When immediately required updates are available for the reader, the integration receives onDidStartInstallingUpdate from the useStripeTerminal hook with a Reader.SoftwareUpdate.

The Reader.SoftwareUpdate provides the necessary details of the update, including an estimate of the total update duration, indicated by estimatedUpdateTime.

During the installation process, the Terminal’s connectionStatus transitions to "connecting" 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 useStripeTerminal hook with onDidFinishInstallingUpdate. 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 React Native SDK version is greater than or equal to 0.0.1-beta.18.

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.

const terminal = useStripeTerminal({
  onDidReportReaderSoftwareUpdateProgress: (progress) => {
    setCurrentProgress((Number(progress) * 100).toFixed(0).toString());
  },
  onDidFinishInstallingUpdate: ({ error }) => {
  },
  onDidStartInstallingUpdate: (update) => {
  },
});

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 onDidReportAvailableUpdate callback from the useStripeTerminal hook any time the reader is connected but not performing a transaction. If an optional update is available, your application’s useStripeTerminal hook receives the onDidReportAvailableUpdate callback with the SoftwareUpdate object containing the update details, including:

• Estimated time for update to complete (estimatedUpdateTime)
• 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 onDidReportAvailableUpdate, call installAvailableUpdate from the useStripeTerminal hook.

The available update is also stored on the reader object as reader.availableUpdate.

As the update proceeds, block the user from leaving the page in your app, and instruct the user to keep the reader in range and powered on until the update completes. We recommend also providing your user with a visual indicator of the update’s progress. The useStripeTerminal hook reports the update’s progress in the onDidReportReaderSoftwareUpdateProgress method.

When an optional update’s requiredAt date has passed, the update installs the next time the reader is connected.

const terminal = useStripeTerminal({
  onDidReportAvailableUpdate: (update) => {
    // An update is available for the connected reader. Show this update in your application.
    // Install this update using the `installAvailableUpdate` method from the `useStripeTerminal` hook.
  },
});

See Testing reader updates to learn more about making sure your application handles the different update types that a reader can have.