Stripe Terminal React Native SDK - Turn Your App Into a Payment Terminal That Doesn't Suck

Stripe Terminal React Native SDK (v0.0.1-beta.27) bridges the gap between your React Native app and physical payment hardware. Still in beta, which means plan for shit breaking randomly and Stack Overflow being your best friend.

Why You'd Actually Want This

Instead of building separate payment terminals or dealing with clunky third-party hardware solutions, this SDK lets your React Native app accept physical card payments directly. Your iPhone becomes a payment terminal with Tap to Pay, or you can connect dedicated card readers like the Stripe Reader M2 or BBPOS WisePad 3.

The real win is unified payment processing - online and offline transactions flow through the same Stripe infrastructure, same reporting dashboard, same everything. No more managing separate payment providers for different channels.

The Reality Check

This isn't your typical React Native library integration. You're dealing with:

• Hardware dependencies - Card readers need firmware updates, batteries die, Bluetooth connections drop
• Compliance requirements - PCI DSS scope, EMV certification, payment card industry regulations
• Platform limitations - iOS requires physical device testing, Android permission hell varies by version
• Beta software instability - Recent GitHub issues show connection failures, Bluetooth pairing problems, and random crashes

Current Capabilities (August 2025)

Based on the latest beta release and real-world testing:

Supported Payment Methods:

• EMV chip cards (contact and contactless)
• Magstripe cards (where legally required)
• Apple Pay / Google Pay via NFC
• Tap to Pay on iPhone - Turn any iPhone 8+ into a payment terminal
• Tap to Pay on Android - Newer Android devices with NFC

Supported Card Readers:

• Stripe Reader M2 - Compact Bluetooth reader, 28-hour battery life
• Stripe Reader S700 - WiFi-enabled countertop reader
• BBPOS WisePad 3 - Mobile Bluetooth reader with PIN pad
• BBPOS WisePOS E - Android-powered smart terminal

Real-World Gotchas You'll Hit:

The GitHub issues tell the real story - these are production failures happening right now:

• Issue #993: Bluetooth readers get "stuck in processing" after SDK updates
• Issue #972: Reader discovery fails 95% of the time after app restarts (Android M2 readers)
• Issue #936: React Native 0.77.2+ compatibility breaks, stick with 0.78
• Issue #1003: Card reader firmware updates brick devices during update process
• Connection tokens expire in 10 minutes causing mysterious "authentication failed" errors
• iOS kills Bluetooth connections when apps go to background - no graceful reconnect

Who Should Use This

Good fit:

• Retail apps that need in-person payments
• Food trucks, farmers markets, popup shops
• Field service businesses (repair, delivery, etc.)
• Existing Stripe merchants expanding to physical locations

Not a good fit:

• Apps that rarely need in-person payments
• Teams without hardware debugging experience
• Projects with tight deadlines (beta software = surprises)
• High-volume point-of-sale systems (hardware limitations)

If this sounds like what your app needs, the next section covers the reality of implementation - including what actually works in production and what will have you debugging at 3am.

Prerequisites That Matter

• Node.js 18+ (older versions break with cryptic errors)
• React Native 0.78 (0.77.2+ has known issues per GitHub #936)
• Physical device for testing - Simulator testing is worse than useless, gives false confidence
• Real Stripe account - Test mode has different behavior than production
• Actual card reader - Can't fully test without hardware

Installation That Usually Works

npm install @stripe/stripe-terminal-react-native@0.0.1-beta.27

The pod install step downloads the native iOS Terminal SDK. If this fails, you're fighting with CocoaPods dependency conflicts. Delete your ios/Pods directory and Podfile.lock, then try again.

iOS Configuration:

<!-- Add to Info.plist -->
<key>NSBluetoothPeripheralUsageDescription</key>
<string>This app uses Bluetooth to connect to card readers for payment processing</string>
<key>NSBluetoothAlwaysUsageDescription</key>
<string>This app uses Bluetooth to connect to card readers for payment processing</string>

<!-- Enable in capabilities -->
<key>UIBackgroundModes</key>
<array>
    <string>bluetooth-central</string>
</array>

For Tap to Pay on iPhone, add the proximity reader entitlement:

<key>com.apple.developer.proximity-reader.payment.acceptance</key>
<true/>

Critical: iOS app review requires physical hardware testing screenshots and takes 2-4 weeks for payment apps.

Android Configuration:

<!-- Add to AndroidManifest.xml -->
<!-- For all Android versions -->
<uses-permission android:name="android.permission.BLUETOOTH" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Android 12+ (API 31+) additional permissions -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" 
    android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.BLUETOOTH_ADVERTISE" />

<uses-feature android:name="android.hardware.bluetooth" android:required="true" />

Android Gotcha: Location permission is required for Bluetooth Low Energy scanning - not for tracking you, just Android being Android.

The Connection Dance

import { useStripeTerminal } from '@stripe/stripe-terminal-react-native';

const terminalConfig = {
  fetchConnectionToken: async () => {
    // This needs to hit YOUR backend, not Stripe directly
    // See: https://docs.stripe.com/terminal/fleet
    const response = await fetch('/terminal/connection-token');
    const { secret } = await response.json();
    return secret;
  }
};

const { discoverReaders, connectReader } = useStripeTerminal(terminalConfig);

const startReaderDiscovery = async () => {
  const { error } = await discoverReaders({
    discoveryMethod: 'bluetoothScan',
    simulated: __DEV__, // Simulated readers lie to you - they always work
  });
  
  if (error) {
    // Error messages are useless, but here's what they usually mean:
    // \"Bluetooth not enabled\" = user needs to enable Bluetooth
    // \"Location permission denied\" = Android being Android  
    // \"Discovery timeout\" = reader is dead/disconnected/having an existential crisis
    console.log('Reader discovery shit the bed:', error);
  }
};

Payment Processing When It Works

const processPayment = async (reader) => {
  try {
    // Step 1: Create PaymentIntent on your backend
    const paymentIntent = await createPaymentIntent({ amount: 1000 });
    
    // Step 2: Collect payment from card reader
    const { error: collectError } = await collectPaymentMethod({
      paymentIntent: paymentIntent.client_secret
    });
    
    if (collectError) {
      throw new Error(`Payment collection failed: ${collectError.message}`);
    }
    
    // Step 3: Confirm payment on backend  
    const confirmedPayment = await confirmPaymentIntent({
      paymentIntentId: paymentIntent.id
    });
    
    return confirmedPayment;
    
  } catch (error) {
    // Real error handling for production:
    if (error.code === 'USER_ERROR.CANCELED') {
      // Customer canceled - this is normal
    } else if (error.code === 'INTEGRATION_ERROR.NOT_CONNECTED_TO_READER') {
      // Reader disconnected mid-transaction - reconnect and retry
    } else {
      // Everything else - log it and show generic error to user
      console.error('Payment failed:', error);
    }
  }
};

Production Gotchas I Learned the Hard Way

Connection Token Expiration Hell: Connection tokens expire in exactly 10 minutes and are single-use. Never cache them. Your backend should generate fresh ones for each connection attempt or you'll get cryptic "authentication failed" errors that waste hours debugging.

Payment Intent Lifecycle: When cards get declined, reuse the same PaymentIntent rather than creating new ones. Stripe's fraud detection tracks retry attempts per PaymentIntent. Creating new ones for the same purchase triggers red flags.

iOS Background Mode Death: iOS immediately kills Bluetooth connections when your app goes to background. There's no graceful reconnection - you need to detect app state changes and reconnect readers when the app becomes active. Our production broke at 2am because of this.

Android Permission Evolution:

• Android 10: Just BLUETOOTH permission
• Android 11: Adds ACCESS_FINE_LOCATION requirement
• Android 12+: Completely new permission model with BLUETOOTH_SCAN/BLUETOOTH_CONNECT
• Each version breaks differently - test on actual devices, not just simulators

Misleading Error Codes: The SDK throws 50+ different error codes, but half are lies:

• UNEXPECTED_SDK_ERROR = something specific broke, not the SDK itself
• READER_ERROR.READER_BUSY = usually means the reader is stuck from a previous transaction
• INTEGRATION_ERROR.NOT_CONNECTED_TO_READER = connection token expired, not actually disconnected

Firmware Update Russian Roulette: Card readers need firmware updates every 2-3 months, and they fail 20% of the time. GitHub #1003 shows readers getting bricked during updates. Only update during slow business hours with backup readers ready.

With the technical realities covered, choosing the right hardware becomes critical. The next section compares the major reader options to help you avoid expensive mistakes.