Set up your integration

The Stripe Terminal iOS SDK is compatible with apps supporting iOS 10 and above, and can be installed with CocoaPods or Swift Package Manager, or by manually integrating the framework.

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
   Key	NSLocationWhenInUseUsageDescription
   Value	Location access is required in order to accept payments.

   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 iOS device, payments are disabled until location access is restored.

2. Ensure that your app runs in the background and remains connected to the reader.

   Required background modes
   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 backgrounded, 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
   Key	NSBluetoothPeripheralUsageDescription
   Value	Bluetooth access is required in order to connect to supported card readers.

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

4. iOS 13 SDK and later: 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 introduces new, 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 they 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.

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.

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

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.

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

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.

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
    }

    // ...

}