DOCSEARCHbyAlgolia
Submit Docs

Stripe Terminal React Native SDK

repository·main·Indexed 41 days ago

https://github.com/stripe/stripe-terminal-react-native

A public preview SDK (version 0.0.1-beta.33) for integrating Stripe Terminal into React Native applications to enable physical card reader connectivity. Features include the StripeTerminalProvider for initialization, the useStripeTerminal hook for reader discovery and connection management, and support for Tap to Pay on Android.

Tokens
6.9K
Snippets
22
Records
38
Agent score
51%

What's inside Stripe Terminal

  1. Manage SDK versioning and end-of-life enforcement

    main

    React Native SDK versions wrap specific versions of the Terminal iOS and Android SDKs. The lifecycle and support enforcement for the React Native SDK are tied to the major versions of these underlying native SDKs.

    Critical Warning: End-of-Life (EOL) Enforcement When a native SDK major version reaches the end of its Deprecated phase, any React Native SDK version containing that native SDK version will be blocked from connecting to Terminal readers.

    Blocked SDK versions will be unable to:

    • Discover readers
    • Connect to readers
    • Process payments

    To avoid interruptions to payment processing, you must upgrade to a React Native SDK version that includes supported native SDK versions before the hard block date.

  3. The Payment Collection Workflow

    main

    The standard lifecycle for collecting an in-person payment follows these steps:

    1. Create a PaymentIntent: Your server creates a PaymentIntent and returns the client_secret.
    2. Fetch the PaymentIntent: The client requests the PaymentIntent from your server to initiate the process.
    3. Collect Payment Method: Call collectPaymentMethod with the PaymentIntent ID.
      • Simulated Reader: This immediately updates the PaymentIntent with a simulated test card.
      • Physical Reader: The reader waits for a card to be presented.
    4. Process the Payment: Call processPayment with the updated PaymentIntent. A successful call results in a PaymentIntent status of requires_capture.
    5. Capture the Payment: Notify your backend to call the Stripe API to capture the PaymentIntent using its ID.

  4. Understand the Stripe Terminal React Native SDK lifecycle

    main

    The SDK is currently in public preview and is released as beta versions (e.g., 0.0.1-beta.x).

    Because the SDK aims to keep pace with the underlying native Terminal iOS and Android SDKs, users should expect regular updates and potential breaking changes. It is highly recommended to actively update to the latest beta version to ensure compatibility with the latest native features, fixes, and reliability improvements.

  5. Initialize the Stripe Terminal SDK with StripeTerminalProvider

    main

    To initialize the SDK, wrap your application's root component with StripeTerminalProvider. You must provide a tokenProvider function that fetches a connection token from your backend server.

    Note: After setting up the provider, you must call the initialize method from the useStripeTerminal hook within a component nested inside the provider.

    // Root.tsx
import { StripeTerminalProvider } from '@stripe/stripe-terminal-react-native';

function Root() {
  const fetchTokenProvider = async () => {
    const response = await fetch(`${API_URL}/connection_token`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    });
    const { secret } = await response.json();
    return secret;
  };

  return (
    <StripeTerminalProvider
      logLevel="verbose"
      tokenProvider={fetchTokenProvider}
    >
      <App />
    </StripeTerminalProvider>
  );
}

// App.tsx
function App() {
  const { initialize } = useStripeTerminal();

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

  return <View />;
}

  6. Configure SDK requirements for JS, Android, and iOS

    main

    Ensure your project meets the following platform requirements:

    JavaScript

    • Requires Babel version 7.9.0 or above, or the plugin-transform-typescript plugin.

    Android

    • Minimum API level: 26 (Note: You cannot override minSdkVersion to a lower value due to internal runtime validation).
    • compileSdkVersion: 35
    • targetSdkVersion: 35

    iOS

    • Compatible with apps targeting iOS 15.1 or above.

  7. Run e2e tests on iOS

    main

    To run end-to-end tests on iOS, ensure an iOS simulator is booted, then build, install, and execute the release tests using the following steps:

    # 1. Boot an iOS simulator
# 2. Build the dev app
yarn e2e:build:ios:release

# 3. Install it
xcrun simctl install Booted dev-app/ios/build/Build/Products/Release-iphonesimulator/StripeTerminalReactNativeDevApp.app

# 4. Run the tests
yarn e2e:test:ios:release

  8. Use the Terminal example application to learn the integration flow

    main

    Before building your own integration, use the provided example application to understand how the Stripe Terminal SDK, the physical reader, your point-of-sale (POS) application, and your backend code interact. This helps visualize the full lifecycle of a Terminal transaction.

    Full instructions for setting up the example application and a sample backend can be found at the official Stripe documentation: https://stripe.com/docs/terminal/example-applications

  9. Set up the backend for Stripe Terminal

    main

    To use the SDK, your backend must provide a ConnectionToken to authorize the client to use readers with your Stripe account.

    1. Install the Stripe Node library: Use npm install --save stripe to manage Stripe API interactions on your server.
    2. Create a ConnectionToken endpoint: Implement an endpoint that generates a ConnectionToken.
      • You can pass a location ID to the token to restrict access to specific readers.
      • If using Stripe Connect, ensure the token is scoped to the relevant connected accounts.
    npm install --save stripe

  11. Run e2e tests on Android

    main

    To run end-to-end tests on Android, ensure an Android emulator is running, then build, install, and execute the release tests using the following steps:

    # 1. Start an Android emulator
# 2. Build the dev app
yarn e2e:build:android:release

# 3. Install it
adb install dev-app/android/app/build/outputs/apk/release/app-release.apk

# 4. Run the tests
yarn e2e:test:android:release