Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use caseManaged Payments
Payment methods
Payment interfaces
Payment scenarios
In-person payments
Terminal
Beyond payments

Set up your integration

Set up a Stripe Terminal SDK or server-driven integration to accept in-person payments.

Caution

Terminal’s React Native library is in public preview and in active development. Please report any issues you encounter to our github project.

Getting started with the React Native SDK requires four steps:

  1. Install the SDK in your app.
  2. Configure your app.
  3. Set up the connection token endpoint in your app and backend.
  4. Initialize the SDK in your app.

Install the SDK
Client-side

The React Native SDK is open source and fully documented. Internally, it makes use of native iOS and Android SDKs. Install the SDK by running:

Command Line
npm install @stripe/stripe-terminal-react-native

Configure your app
Client-side

Permissions

Enable the following permissions for the Stripe Terminal SDK to function properly:

  • PermissionsAndroid.PERMISSIONS.BLUETOOTH_CONNECT
  • PermissionsAndroid.PERMISSIONS.BLUETOOTH_SCAN
  • PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION

To do this, add the following check before you initialize the Terminal SDK:

useEffect(() => {
  async function init() {
    try {
      const granted = await PermissionsAndroid.request(
        PermissionsAndroid.PERMISSIONS.ACCESS_FINE_LOCATION,
        {
          title: 'Location Permission',
          message: 'Stripe Terminal needs access to your location',
          buttonPositive: 'Accept',
        }
      );
      if (granted === PermissionsAndroid.RESULTS.GRANTED) {
        console.log('You can use the Location');
      } else {
        console.error(
          'Location services are required to connect to a reader.'
        );
      }
    } catch {}
  }
  init();
}, []);

For convenience, Stripe Terminal SDK also provides a utility that handles all needed Android permissions. You can use it as follows:

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

try {
  const granted = await requestNeededAndroidPermissions({
    accessFineLocation: {
      title: 'Location Permission',
      message: 'Stripe Terminal needs access to your location',
      buttonPositive: 'Accept',
    },
  });
  if (granted) {
    // Initialize the SDK
  } else {
    console.error(
      'Location and BT services are required to connect to a reader.'
    );
  }
} catch (e) {
  console.error(e);
}

Manifest

To ensure compatibility with Android 12 and later, make sure to add android:exported="true" to AndroidManifest.xml:

<manifest ...>
    <application android:name=".MainApplication">
      <activity
        android:name=".MainActivity"
        android:exported="true">
          <!-- content -->
      </activity>
    </application>
</manifest>

For additional context on changes made in Android 12, see the Android documentation about safer component exporting.

For devices running on Android 11 or below, you must grant permissions through the manifest as well:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.stripeterminalreactnative">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
    <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
</manifest>

Set up the connection token endpoint
Server-side
Client-side

Server-side

To connect to a reader, your backend needs to give the SDK permission to use the reader with your Stripe account, by providing it with the secret from a ConnectionToken. Your backend needs to only create connection tokens for clients that it trusts.

Command Line
curl
Ruby
Python
PHP
Java
Node
Go
.NET
No results
curl https://api.stripe.com/v1/terminal/connection_tokens \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -X "POST"

Obtain the secret from the ConnectionToken on your server and pass it to the client side.

Ruby
Python
PHP
Java
Node
Go
.NET
No results
post '/connection_token' do
  token = # ... Create or retrieve the ConnectionToken
  {secret: token.secret}.to_json
end

Caution

The secret from the ConnectionToken lets you connect to any Stripe Terminal reader and take payments with your Stripe account. Be sure to authenticate the endpoint for creating connection tokens and protect it from cross-site request forgery (CSRF).

Client-side

To give the SDK access to this endpoint, create a token provider single function that requests a ConnectionToken from your backend.

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

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

This function is called whenever the SDK needs to authenticate with Stripe or the Reader. It’s also called when a new connection token is needed to connect to a reader (for example, when your app disconnects from a reader). If the SDK can’t retrieve a new connection token from your backend, connecting to a reader fails with the error from your server.

Caution

Do not cache or hardcode the connection token. The SDK manages the connection token’s lifecycle.

Initialize the SDK
Client-side

To get started, pass in your token provider implemented in Step 3 to StripeTerminalProvider as a prop.

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>
  );
}

As a last step, call the initialize method from useStripeTerminal hook. You must call the initialize method from a component nested within StripeTerminalProvider and not from the component that contains the StripeTerminalProvider.

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

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

  return <View />;
}

SDK updates

Stripe periodically releases updates which can include new functionality, bug fixes, and security updates. Update your SDK as soon as a new version is available. The currently available SDKs are:

Next steps

Was this page helpful?
YesNo