Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Start an integration
Payment scenarios
In-person payments
Other Stripe products

Connect to a reader

Connect your application to a Stripe Terminal reader.

Note

If you haven’t chosen a reader yet, compare the available Terminal readers and choose one that best suits your needs.

Tap to Pay on iPhone lets users accept in-person contactless payments with a compatible iPhone and the Stripe Terminal SDK. Tap to Pay on iPhone includes support for Visa, Mastercard, American Express, and Discover contactless cards and NFC-based mobile wallets (Apple Pay, Google Pay, and Samsung Pay). Tap to Pay on iPhone is included in the Terminal iOS SDK and enables payments directly in your iOS mobile app.

Create a location
Server-side
Dashboard

Create a Location for each physical location where your readers operate. Set the display_name to represent the name of the business. Your customer sees the display_name on the device’s tap screen unless you explicitly provide the name of a business when you connect to a reader. You can edit existing locations as necessary to adjust this text.

If your business requires you to move your readers frequently, your locations can use an address that represents your primary place of business.

To create a location using the API, use the create location request.

Locations for the US require:

  • line1
  • city
  • state
  • postal_code
  • country
Command Line
curl https://api.stripe.com/v1/terminal/locations \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d display_name="Venice Burrito Shop" \
  -d "address[line1]"="1272 Valencia Street" \
  -d "address[city]"="San Francisco" \
  -d "address[state]"=CA \
  -d "address[country]"=US \
  -d "address[postal_code]"=94110

To create a location in the Dashboard, click the +New button on the Locations page.

Discover readers

Use the discoverReaders method to determine whether your iPhone is supported for Tap to Pay. The completion handler invokes with an error if your application runs on a device that doesn’t meet the supported device criteria.

DiscoverReadersViewController.swift
import StripeTerminal

class DiscoverReadersViewController: UIViewController, DiscoveryDelegate {

    var discoverCancelable: Cancelable?

    // ...

    // Action for a "Discover Readers" button
    func discoverReadersAction() throws {
        let config = try LocalMobileDiscoveryConfigurationBuilder().build()
        self.discoverCancelable = Terminal.shared.discoverReaders(config, delegate: self) { error in
            if let error = error {
                print("discoverReaders failed: \(error)")
            } else {
                print("discoverReaders succeeded")
            }
        }
    }

    // ...

    // MARK: DiscoveryDelegate

    func terminal(_ terminal: Terminal, didUpdateDiscoveredReaders readers: [Reader]) {
        // In your app, display the ability to use your phone as a reader
        // Call `connectLocalMobileReader` to initiate a session with the phone
    }
}

Connect to a reader

To begin accepting Tap to Pay on iPhone payments, provide the discovered reader to the connectLocalMobileReader method. You’ll also need to create a delegate to handle potential required updates to the reader.

If you use destination charges with on_behalf_of, you must also provide the connected account ID in SCPLocalMobileConnectionConfiguration.

Optionally, you can provide a buyer-facing name to display on the payment collection screen. If you don’t provide a name, the display_name associated with the given location is shown.

APPDiscoverReadersViewController.swift
// Call `connectLocalMobileReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig = try LocalMobileConnectionConfigurationBuilder.init(locationId: 
"{{LOCATION_ID}}"
).build()
Terminal.shared.connectLocalMobileReader(selectedReader, delegate: localMobileReaderDelegate, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectLocalMobileReader failed: \(error)")
    }
}

Handle device setup

When connecting to a compatible Tap to Pay on iPhone reader, a configuration update may be required and can take up to a few minutes. We recommend connecting to the reader ahead of time in the background to reduce wait time for merchants.

Make sure your application implements SCPLocalMobileReaderDelegate to handle the configuration steps and display messaging to your merchant to stand by. You’ll see the configuration steps as a software update so you can display progress to your merchants as appropriate.

APPReaderViewController.swift
class APPReaderViewController: LocalMobileReaderDelegate {

    // MARK: LocalMobileReaderDelegate

    // ...

    func localMobileReader(_ reader: Reader, didStartInstallingUpdate update: ReaderSoftwareUpdate, cancelable: Cancelable?) {
        // In your app, let the user know that an update is being installed on the reader
    }

    func localMobileReader(_ reader: Reader, didReportReaderSoftwareUpdateProgress progress: Float) {
        // The update or configuration process has reached the specified progress (0.0 to 1.0)
        // If you are displaying a progress bar or percentage, this can be updated here
    }

    func localMobileReader(_ reader: Reader, didFinishInstallingUpdate update: ReaderSoftwareUpdate?, error: Error?) {
        // The reader has finished installing an update
        // If `error` is nil, it is safe to proceed and start collecting payments
        // Otherwise, check the value of `error` for more information on what went wrong
    }

    func localMobileReader(_ reader: Reader, didRequestReaderDisplayMesage displayMessage: ReaderDisplayMessage) {
        // This is called to request that a prompt be displayed in your app.
        // Use Terminal.stringFromReaderDisplayMessage(:) to get a user-facing string for the prompt
    }

    func localMobilereader(_ reader: Reader, didRequestReaderInput inputOptions: ReaderInputOptions = []) {
        // This is called when the reader begins waiting for input
        // Use Terminal.stringFromReaderInputOptions(:) to get a user-facing string for the input options
    }

    // ...
}

Account linking and Apple terms and conditions

Users are presented with Apple’s Tap to Pay on iPhone Terms and Conditions the first time they connect to the reader. To register with Apple, you must specify a valid Apple ID representing your business before accepting the terms presented by Apple. You only need to perform this once per Stripe account. This flow isn’t presented on subsequent connections using the same Stripe account, including on other mobile devices.

Each connected account must accept the Terms and Conditions when:

  • A Connect user creates direct charges
  • A Connect user creates a destination charge and specifies an on_behalf_of account

Link your Apple ID account to accept Tap to Pay payments

Any iPhone will be able to use up to three (3) unique Stripe accounts across apps within a rolling 24-hour period when calling connectLocalMobileReader for Tap to Pay on iPhone. If additional accounts are used for the device within the same 24-hour period, the connectLocalMobileReader method raises an SCPErrorAppleBuiltInReaderMerchantBlocked error.

Learn more about account linking in the Tap to Pay on iPhone Business Information section of the Apple Tap to Pay on iPhone FAQ

Handle disconnects

Your reader disconnects when your application enters the background or when your iPhone loses connectivity. There are two ways you can handle this:

1. Handle the disconnect manually

Your application must implement the SCPTerminalDelegate terminal:didReportUnexpectedReaderDisconnect: delegate method to handle this disconnection. You can use this callback as an opportunity to notify the user that something went wrong and that you need internet connectivity to continue. Additionally, you can also manually reconnect to the reader when your application re-enters the foreground.

ReaderViewController.swift
import StripeTerminal

class ReaderViewController: UIViewController, TerminalDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        Terminal.shared.delegate = self
    }

    // ...

    // MARK: TerminalDelegate

    func terminal(_ terminal: Terminal, didReportUnexpectedReaderDisconnect reader: Reader) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}

2. Automatically attempt reconnection

Set autoReconnectOnUnexpectedDisconnect as true on the LocalMobileConnectionConfiguration in your app and implement the callbacks found in the ReconnectionDelegate. You must also pass an autoReconnectionDelegate to your LocalMobileConnectionConfiguration.

ConnectReaderViewController.swift
let connectionConfig = try LocalMobileConnectionConfigurationBuilder(locationId: locationId)
  .setAutoReconnectOnUnexpectedDisconnect(true)
  .setAutoReconnectionDelegate(yourReconnectionDelegate)
  .build()

Terminal.shared.connectLocalMobileReader(
  reader,
  delegate: readerDelegate,
  connectionConfig: connectionConfig,
  completion: connectCompletion
)

If you automatically attempt reconnection, the following occurs:

  1. When a disconnect occurs, the SDK automatically attempts to reconnect and notifies you through onReaderReconnectStarted. Make sure your app announces that the connection was lost and a reconnection is in progress.
    • You can use the Cancelable object to stop the reconnection attempt at any time.
  2. If the SDK successfully reconnects to the reader, Stripe notifies you through onReaderReconnectSucceeded. Make sure your app announces that the connection was restored and to continue normal operations.
  3. If the SDK can’t reconnect to the reader, Stripe notifies you through onReaderReconnectFailed. Make sure your app announces that an unexpected disconnect occurred.
ReaderViewController.swift
import StripeTerminal

extension ReaderViewController: ReconnectionDelegate {
    // MARK: ReconnectionDelegate

    func terminal(_ terminal: Terminal, didStartReaderReconnect cancelable: Cancelable) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func terminalDidSucceedReaderReconnect(_ terminal: Terminal) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func terminalDidFailReaderReconnect(_ terminal: Terminal) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

Next steps

You’ve connected your application to the reader. Next, collect your first Stripe Terminal payment.

The BBPOS and Chipper™ name and logo are trademarks or registered trademarks of BBPOS Limited in the United States and/or other countries. The Verifone® name and logo are either trademarks or registered trademarks of Verifone in the United States and/or other countries. Use of the trademarks does not imply any endorsement by BBPOS or Verifone.

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
On this page
Create a location
Discover readers
Connect to a reader
Handle device setup
Account linking and Apple terms and conditions
Handle disconnects
Next steps
Products Used
Terminal