Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Business operations
Financial services
Developer tools
Security
All products
Home
Payments
Business operations
Home
Payments
Business operations
Financial services
Developer tools
Support
Overview
Overview
What is Terminal
Design an integration
Example applications
Quickstart
Accept an in-person payment
Set up your reader
Set up your integration
Connect to a reader
Collect payments
Regional considerations
Terminal payments features
Multiparty payments with Connect
Collect tips
Save cards for future use
Refund transactions
Provide receipts
Cart display
Incremental authorizations
Extended authorizations
Operate offline
Deploy at scale
Order hardware
Manage locations
Configure readers
References
API references
Bluetooth readers
Smart readers
SDK migration guide
Testing
Deployment checklist
Stripe Terminal reader product sheets
Testing
No-code options
terminal
·
HomePaymentsIn-person payments

Set up your integration

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

SDK Reference

If you’re looking for a more detailed reference with all available methods, objects, and errors, consult our full SDK reference.

Getting started with the Android 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 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:

build.gradle
apply plugin: 'com.android.application' android { ... } dependencies { implementation "com.stripe:stripeterminal:2.11.0" // ... }

Next, since the SDK relies on Java 8, you’ll need to specify that as your target Java version (also in build.gradle):

build.gradle
compileOptions { sourceCompatibility JavaVersion.VERSION_1_8 targetCompatibility JavaVersion.VERSION_1_8 }

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 app
Client-side

You must enable location access in order to use the Android SDK.

Before initializing the Terminal object, add the following check to make sure that the ACCESS_FINE_LOCATION permission is enabled in your app:

MainActivity.java
if (ContextCompat.checkSelfPermission(getActivity(), Manifest.permission.ACCESS_FINE_LOCATION) != PackageManager.PERMISSION_GRANTED) { String[] permissions = {Manifest.permission.ACCESS_FINE_LOCATION}; // REQUEST_CODE_LOCATION should be defined on your app level ActivityCompat.requestPermissions(getActivity(), permissions, REQUEST_CODE_LOCATION); }

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.

MainActivity.java
@Override public void onRequestPermissionsResult( int requestCode, @NonNull String[] permissions, @NonNull int[] grantResults ) { super.onRequestPermissionsResult(requestCode, permissions, grantResults); if (requestCode == REQUEST_CODE_LOCATION && grantResults.length > 0 && grantResults[0] != PackageManager.PERMISSION_GRANTED) { throw new RuntimeException("Location services are required in order to " + "connect to a reader."); } }

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 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 should only create connection tokens for clients that it trusts.

Terminal
curl https://api.stripe.com/v1/terminal/connection_tokens \ -u
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \ -X "POST"

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

post '/connection_token' do token = # ... Create or retrieve the ConnectionToken {secret: token.secret}.to_json end

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.

TokenProvider.java
public class TokenProvider implements ConnectionTokenProvider { @Override public void fetchConnectionToken(ConnectionTokenCallback callback) { try { // Your backend should call /v1/terminal/connection_tokens and return the // JSON response from Stripe. When the request to your backend succeeds, // return the `secret` from the response to the SDK. callback.onSuccess(secret); } catch (Exception e) { callback.onFailure( new ConnectionTokenException("Failed to fetch connection token", e)); } } }

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 is unable to retrieve a new connection token from your backend, connecting to a reader fails with the error from your server.

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

Initialize the SDK
Client-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 should do the following:

  • Register activity lifecycle callbacks
  • Implement the onTrimMemory method to notify the SDK to prune its memory usage
TerminalApplication.java
// Substitute with your application name, and remember to keep it the same as your AndroidManifest.xml class StripeTerminalApplication extends Application { @Override public void onCreate() { super.onCreate(); TerminalApplicationDelegate.onCreate(this); } @Override public void onTrimMemory(int level) { super.onTrimMemory(level); TerminalApplicationDelegate.onTrimMemory(this, level); } }

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.

MainActivity.java
// Create your listener object. Override any methods that you want to be notified about TerminalListener listener = new TerminalListener() {}; // Choose the level of messages that should be logged to your console LogLevel logLevel = LogLevel.VERBOSE; // Create your token provider. TokenProvider tokenProvider = new TokenProvider(); // Pass in the current application context, your desired logging level, your token provider, and the listener you created if (!Terminal.isInitialized()) { Terminal.initTerminal(getApplicationContext(), logLevel, tokenProvider, listener); } // Since the Terminal is a singleton, you can call getInstance whenever you need it Terminal.getInstance();

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.

Next steps

Congratulations! You’ve setup the Stripe Terminal SDK. Next, connect your application to the reader.

  • Connect to a reader
Was this page helpful?
Questions? Contact us.
View developer tutorials on YouTube.
Check out our product changelog.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Install the SDK
Configure your app
Set up the ConnectionToken endpoint
Initialize the SDK
SDK updates
Next steps
Stripe Shell
Test mode
▗▄ ▄▟█ █▀▀ ▗▟████▙▖ ██████ ███▗▟█ ███ ███▗▟██▙▖ ▗▟█████▙▖ ███▖ ▀▀ ███ ███▀▀▀ ███ ███▀ ███ ███ ███ ▝▜████▙▖ ███ ███ ███ ███ ███ █████████ ▄▄ ▝███ ███ ▄ ███ ███ ███▄ ███ ███ ▄▄ ▝▜████▛▘ ▝▜███▛ ███ ███ ███▝▜██▛▘ ▝▜█████▛▘ ███ ▀▘
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to Stripe docs and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$