Set up your integration
Note
For smart readers, such as the BBPOS WisePOS E reader or Stripe Reader S700, we recommend the server-driven integration, which uses the Stripe API instead of a Terminal SDK to collect payments.
Getting started with the Android SDK requires four steps:
- Install the SDK in your app
- Configure your app
- Set up the connection token endpoint in your app and backend
- Initialize the SDK in your app
Install the SDKClient-side
Caution
The SDK is no longer compatible with the support libraries, as we use Room to store and maintain state across the app lifecycle. Make sure your app has migrated to AndroidX.
To install the SDK, add stripeterminal
to the dependencies
block of your app/build.gradle file:
Next, since the SDK relies on Java 8, you’ll need to specify that as your target Java version (also in build.gradle
):
Note
For details on the latest SDK release and past versions, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.
For information on migrating from earlier beta versions of the Android SDK, see the Stripe Terminal Beta Migration Guide.
Configure your appClient-side
You must enable the ACCESS_FINE_LOCATION
permission. To connect a Bluetooth reader, you must also enable Bluetooth permissions. Add the appropriate permissions to your manifest as shown here:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" /> <uses-permission android:name="android.permission.BLUETOOTH" android:maxSdkVersion="30" /> <uses-permission android:name="android.permission.BLUETOOTH_ADMIN" android:maxSdkVersion="30" /> <uses-permission android:name="android.permission.BLUETOOTH_CONNECT" /> <uses-permission android:name="android.permission.BLUETOOTH_SCAN" />
Before initializing the Terminal object, add the following check to make sure that the ACCESS_FINE_LOCATION
permission is enabled in your app:
Also verify that the app user grants location permission—the SDK doesn’t function without it. To do this, override the onRequestPermissionsResult
method in your app and check the permission result.
Note
To reduce fraud risks associated with payments, and to minimize disputes, Stripe needs to know where payments occur. If the SDK can’t determine the location of the Android device, payments are disabled until location access is restored.
Set up the ConnectionToken endpointServer-sideClient-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 should only create connection tokens for clients that it trusts.
Obtain the secret from the ConnectionToken on your server and pass it to the client side.
Caution
The ConnectionToken’s secret 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, implement the ConnectionTokenProvider interface in your app, which defines a single function that requests a ConnectionToken from your backend.
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.
Certificate pinning
In most cases, you shouldn’t configure your application with certificate pinning. If your application does require it, see the certificate pinning docs.
Initialize the SDKClient-side
The Android SDK is lifecycle aware. To prevent memory leaks and ensure proper cleanup of long-running Terminal SDK processes, your application must implement an Application
subclass where TerminalApplicationDelegate
is used to inform the SDK of lifecycle events.
This subclass registers activity lifecycle callbacks:
The Terminal class made available by the Stripe Terminal SDK exposes a generic interface for discovering readers, connecting to a reader, creating payment, and updating reader software.
To get started, provide the current application context, the ConnectionTokenProvider implemented in Step 3, and a TerminalListener object. You can use this listener to handle events from the SDK, such as disconnects. For more information, see Handling disconnects.
Caution
If you’re upgrading from a version below 1.0.0-rc2
, note that TerminalLifecycleObserver
and Application
classes are now mandatory.
SDK updates
Stripe periodically releases updates to the Stripe Terminal React Native SDK, Stripe Terminal JavaScript SDK, the Stripe Terminal iOS SDK, and the Stripe Terminal Android SDK, which can include new functionality, bug fixes, and security updates. Update your integrated version of the Stripe Terminal React Native, JavaScript, iOS, or Android SDK as soon as a new version is available.