Skip to content
Sign in
An image of the Stripe logo
/
Create account
Sign in
Home
Payments
Finance automation
Banking as a service
Developer tools
No-code
All products
Home
Payments
Finance automation
Home
Payments
Finance automation
Banking as a service
Developer tools
Overview
Get started
About Stripe payments
Start an integration
Payment Links
Checkout
Web Elements
Mobile Elements
Payment scenarios
During the payment
After the payment
Add payment methods
More payment scenarios
Faster checkout with Link
Other Stripe products
Connect
Terminal
    Overview
    What is Terminal
    Design an integration
    Example applications
    Quickstart
    Accept an in-person payment
    Select your reader
    Set up your integration
    Connect to a reader
    Collect payments
    Regional considerations
    Supported card brands
    Terminal payments features
    Multiparty payments with Connect
    Collect tips
    Collect inputs
    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
Radar
Financial Connections
Crypto
Identity
Climate
Resources
About the APIs
Implementation guides
Regulation support
Testing
Terminal
·
HomePaymentsTerminal

Set up your integration

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

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.

SDK Reference

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

Getting started with the iOS 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 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.

  1. If you haven’t already done so, install a recent version of CocoaPods.

  2. If you don’t have an existing Podfile, run the following command to create one:

    Command Line
    pod init
  3. Add this line to your Podfile:

    Podfile
    pod 'StripeTerminal', '~> 3.0'
  4. Run the following command:

    Command Line
    pod install
  5. From now on, use the .xcworkspace file to open your project in Xcode, instead of the .xcodeproj file.

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

To prepare your app to work with the Stripe Terminal SDK, make a few changes to your Info.plist file in Xcode.

  1. Enable location services with the following key-value pair.

    Privacy – Location When In Use Usage Description
    KeyNSLocationWhenInUseUsageDescription
    ValueLocation 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.

  2. Make sure that your app runs in the background and remains connected to Bluetooth readers.

    Required background modes for Bluetooth readers
    KeyUIBackgroundModes
    Valuebluetooth-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.

  3. Pass app validation checks when submitting to the App Store.

    Privacy – Bluetooth Peripheral Usage Description
    KeyNSBluetoothPeripheralUsageDescription
    ValueBluetooth access is required to connect to supported card readers.

    This is an example—you can rephrase the prompt for user permission in your app.

  4. Allow your app to display a Bluetooth permission dialog.

    Privacy - Bluetooth Always Usage Description
    KeyNSBluetoothAlwaysUsageDescription
    ValueThis 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 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.

Command Line
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

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.

APIClient.swift
import StripeTerminal // Example API client class for communicating with your backend class APIClient: ConnectionTokenProvider { // For simplicity, this example class is a singleton static let shared = APIClient() // Fetches a ConnectionToken from your backend func fetchConnectionToken(_ completion: @escaping ConnectionTokenCompletionBlock) { let config = URLSessionConfiguration.default let session = URLSession(configuration: config) guard let url = URL(string: "https://{{YOUR_BACKEND_URL}}/connection_token") else { fatalError("Invalid backend URL") } var request = URLRequest(url: url) request.httpMethod = "POST" let task = session.dataTask(with: request) { (data, response, error) in if let data = data { do { // Warning: casting using `as? [String: String]` looks simpler, but isn't safe: let json = try JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] if let secret = json?["secret"] as? String { completion(secret, nil) } else { let error = NSError(domain: "com.stripe-terminal-ios.example", code: 2000, userInfo: [NSLocalizedDescriptionKey: "Missing `secret` in ConnectionToken JSON response"]) completion(nil, error) } } catch { completion(nil, error) } } else { let error = NSError(domain: "com.stripe-terminal-ios.example", code: 1000, userInfo: [NSLocalizedDescriptionKey: "No data in response from ConnectionToken endpoint"]) completion(nil, error) } } task.resume() } }

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 SDK
Client-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.

AppDelegate.swift
import UIKit import StripeTerminal @UIApplicationMain class AppDelegate: UIResponder, UIApplicationDelegate { func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool { Terminal.setTokenProvider(APIClient.shared) // ... return true } // ... }

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?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
Code quickstart
On this page
Install the SDK
Configure your app
Set up the ConnectionToken endpoint
Initialize the SDK
SDK updates
See also
Products Used
Terminal
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe 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.
$