Connect to a reader

Tap to Pay lets users accept in-person contactless payments with compatible NFC-equipped Android devices or compatible iPhones. Tap to Pay supports Visa, Mastercard, American Express contactless cards, and NFC-based mobile wallets (Apple Pay, Google Pay, and Samsung Pay). Tap to Pay on iPhone and Android support is included in the native Terminal SDKs and enables payments directly in your mobile app.

Follow these steps to connect your app to the Tap to Pay reader on a supported device:

• Discover readers using the SDK to confirm device compatibility.
• Connect to a reader using the SDK to accept payments.
• Handle unexpected disconnects to make sure your user can continue to accept payments if the reader disconnects unexpectedly.

export default function DiscoverReadersScreen() {
  const { discoverReaders, discoveredReaders } =
    useStripeTerminal({
      onUpdateDiscoveredReaders: (readers) => {
        // The `readers` variable will contain an array of all the discovered readers.
      },
    });

  useEffect(() => {
    const { error } = await discoverReaders({
      discoveryMethod: 'tapToPay',
    });
  }, [discoverReaders]);

  return <View />;
}

Connect to a reader

To accept Tap to Pay payments, provide the discovered reader from the previous step to the connectReader method.

You must register your reader to a location upon connection. To do so, you must pass the relevant location ID to connectReader.

When using destination charges with on_behalf_of on iPhones, you must also provide the connected account ID.

ConnectReaderScreen.tsx

const { reader, error } = await connectReader({
    reader: selectedReader,
    locationId: 
'{{LOCATION_ID}}'
  },
  'tapToPay'
);

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

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

Account linking and Apple terms and conditions

Users are presented with Apple’s Tap to Pay on iPhone Terms and Conditions the first time they connect to the reader on iPhones. To register with Apple, you must specify a valid Apple ID representing your business before accepting the terms presented by Apple. You only need to perform this once per Stripe account. This flow isn’t presented on subsequent connections using the same Stripe account, including on other mobile devices.

Each connected account must accept the Terms and Conditions when:

• A Connect user creates direct charges
• A Connect user creates a destination charge and specifies an on_behalf_of account

Link your Apple ID account to accept Tap to Pay payments

Learn more about account linking in the Tap to Pay on iPhone Business Information section of the Apple Tap to Pay on iPhone FAQ.

Handle unexpected disconnects

Unexpected disconnects might occur between your app and the reader. For example, the Tap to Pay reader might unexpectedly disconnect because the device loses internet connectivity and when Android OS terminates the Tap to Pay reader service due to memory constraints.

During testing, you can simulate an unexpected disconnect by disabling internet access to your device.

Automatically attempt reconnection

When an unexpected disconnect occurs, Stripe automatically attempts reconnection by default and recommend that you display notifications in your app relaying the reader status throughout the process.

const { reader, error } = await connectReader({
    reader,
    autoReconnectOnUnexpectedDisconnect: true, // default setting
  },
  'tapToPay'
);

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

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

When the SDK automatically attempts reconnection, the following occurs:

1. The SDK notifies you through onDidStartReaderReconnect. Make sure your app announces that the connection was lost and a reconnection is in progress.
   • You can use the cancelReaderReconnection method to stop the reconnection attempt at any time.
2. If the SDK successfully reconnects to the reader, Stripe notifies you through onDidSucceedReaderReconnect. Make sure your app announces that the connection was restored and to continue normal operations.
3. If the SDK can’t reconnect to the reader, Stripe notifies you through both onDidFailReaderReconnect and onDidDisconnect. Make sure your app announces that an unexpected disconnect occurred.

const { discoverReaders, connectedReader, discoveredReaders } =
    useStripeTerminal({
      onDidStartReaderReconnect: (disconnectReason) => {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
      },
      onDidSucceedReaderReconnect: () => {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
      },
      onDidFailReaderReconnect: (): => {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
      }
    });

Handle the disconnect manually

To handle the disconnect yourself, set autoReconnectOnUxpectedDisconnect to false and implement the onDidReportUnexpectedReaderDisconnect callback. This allows your app to reconnect to the Tap to Pay reader and, when appropriate, notify the user of what went wrong and how they can enable access to Tap to Pay. End users can resolve certain errors, such as internet connectivity issues.

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