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 iOS 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
The Stripe Terminal iOS SDK is compatible with apps supporting iOS 11 and above, and can be installed with CocoaPods or Swift Package Manager, or by manually integrating the framework.
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 or subscribe to the Github Releases RSS feed.
For information on migrating from previous versions of the iOS SDK, see the Stripe Terminal SDK Migration Guide.
Configure your appClient-side
To prepare your app to work with the Stripe Terminal SDK, make a few changes to your Info.plist file in Xcode.
Enable location services with the following key-value pair.
Privacy – Location When In Use Usage Description Key NSLocationWhenInUseUsageDescription Value Location access is required to accept payments. To reduce fraud risks associated with payments, and to minimize disputes, Stripe must know where payments occur. If the SDK can’t determine the location of the iOS device, payments are disabled until location access is restored.
Make sure that your app runs in the background and remains connected to Bluetooth readers.
Required background modes for Bluetooth readers Key UIBackgroundModes Value bluetooth-central (Uses Bluetooth LE accessories) Setting the bluetooth-central background mode lets the reader remain in standby mode when your app is running in the background, or when the iOS device is locked. Without this value, standby fails. When your app is running in the background, the reader can turn off automatically to conserve power.
Pass app validation checks when submitting to the App Store.
Privacy – Bluetooth Peripheral Usage Description Key NSBluetoothPeripheralUsageDescription Value Bluetooth access is required to connect to supported card readers. This is an example—you can rephrase the prompt for user permission in your app.
Allow your app to display a Bluetooth permission dialog.
Privacy - Bluetooth Always Usage Description Key NSBluetoothAlwaysUsageDescription Value This app uses Bluetooth to connect to supported card readers. iOS 13 introduced more granular permissions surrounding an app’s use of Bluetooth peripherals. Any apps that use the device’s Bluetooth APIs must include this key in their Info.plist file or else the app will crash on first launch.
Save your app’s Info.plist. Now it’s configured correctly and ready for use with the Stripe Terminal SDK.
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 protocol 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 Terminal
class made available by the Stripe Terminal SDK exposes a generic interface for discovering readers, connecting to a reader, creating payments, and updating reader software.
To get started, provide your ConnectionTokenProvider
implemented in Step 3. You can only call setTokenProvider
once in your app, and must call it before accessing Terminal.shared
. We recommend calling setTokenProvider
in your AppDelegate’s application:didFinishLaunchingWithOptions
method. Alternatively, you can use dispatch_once
in Objective-C, or a static
constructor in Swift.
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.