Terminal SDK V4 migration guide

If your application currently uses an Terminal iOS SDK version earlier than 4.0.0, you need to make a few changes to upgrade and accept card present payments globally. For a detailed list of the changes from version 3.9.1 to 4.0.0, see the SDK changelog.

Update your minimum supported version to iOS 14 or higher

We regularly update the minimum supported version of our SDKs to streamline our developer support efforts.

Existing 3.X versions of the Terminal iOS SDK continue to support devices running iOS 13 and later.

Update saving cards after PaymentIntents integration

If you save a payment method after a successful in-person PaymentIntent, you need to make the following updates to your integration:

• When creating Terminal PaymentIntents, pass the setup_future_usage parameter, which informs Stripe that you want to make future payments with the same card.

• You also need to pass allow_redisplay as always or limited in SCPCollectConfiguration. Pass always if you want the customer’s saved card to be presented to them in all future checkout flows, and limited if they can only use it in the context of the initially scoped use, such as a subscription.

  Learn more about saving payment details after a payment.

Update saving cards without payment with SetupIntents integration

To ensure a consistent integration pattern between SetupIntents and PaymentIntents, and in-person and online transactions, in SCPTerminal’s collectSetupIntentPaymentMethod, we removed the customerConsentCollected parameter that was previously required on all SetupIntent transactions, and replaced it with the allowRedisplay parameter.

Learn more about saving directly without charging.

Update your discoverReaders usage

• We added a new enum value, discovering, to SCPConnectionStatus to represent when reader discovery is running. Make sure your integration can handle this new state and provide relevant information to your customers.

• We improved the handling of multiple simultaneous reader discover operations. Previously, calling discoverReaders multiple times would queue the operations. Now, when a new discoverReaders is called while an existing one is already in progress, the SDK cancels the ongoing operation and returns a SCPErrorCanceledDueToIntegrationError error. The new discoverReaders operation then starts immediately.

• Discovering smart and Tap to Pay readers now calls the discoverReaders completion block when the operation ends. This change reflects the reality that reader discovery for these reader types isn’t a long-running operation.

• We fixed a bug that strongly held a reference to the SCPDiscoveryDelegate in the SDK. Make sure your application is holding a strong reference to your delegate to receive the discovery events.

Update your reader connection usage

• To ensure a consistent integration pattern across reader discovery and connection, we consolidated all previous reader connection methods (connectBluetoothReader, connectInternetReader, connectLocalMobileReader) into connectReader. The exact connection type is still determined by the passed in connection configuration.

• For mobile readers and Tap to Pay readers, the ReaderDelegate parameter has been removed from the connectReader method and instead moved into the connectionConfig, replacing SCPReconnectionDelegate. Consistent with other reader types, smart readers InternetConnectionConfiguration now also expects an InternetReaderDelegate to be passed in, which alerts your integration of events, including when a reader disconnects.

Before

// Call `connectBluetoothReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(locationId: 
"{{LOCATION_ID}}").build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectBluetoothReader(selectedReader, delegate: readerDelegate, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectBluetoothReader failed: \(error)")
    }
}

After

// Call `connectReader` with the selected reader and a connection config
// to register to a location as set by your app.
let connectionConfig: BluetoothConnectionConfiguration
do {
    connectionConfig = try BluetoothConnectionConfigurationBuilder(delegate: yourMobileReaderDelegate, locationId: 
"{{LOCATION_ID}}")
    .build()
} catch {
    // Handle the error building the connection configuration
    return
}
Terminal.shared.connectReader(selectedReader, connectionConfig: connectionConfig) { reader, error in
    if let reader = reader {
        print("Successfully connected to reader: \(reader)")
    } else if let error = error {
        print("connectReader failed: \(error)")
    }
}

For more details, refer our documentation about connecting to a reader.

Auto reconnection is now enabled by default for mobile and Tap to Pay readers

• To increase the resiliency of your Terminal integration with mobile and Tap to Pay readers, we enabled auto reconnection by default when a reader unexpectedly disconnects.

• We recommend displaying notifications in your app to inform the users about the reader status throughout the reconnection process. To handle reader reconnection methods, we removed the SCPReconnectionDelegate. Its responsibilities have been integrated into the respective ReaderDelegates. Use MobileReaderDelegate for mobile readers, and TapToPayReaderDelegate for Tap to Pay readers to handle reconnection events.

• If you implemented your own reader reconnection logic and want to maintain this behavior, you can turn off auto reconnection by setting setAutoReconnectOnUnexpectedDisconnect to false.

Before

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
    }
}

After

import StripeTerminal

extension ReaderViewController: MobileReaderDelegate {
    // MARK: MobileReaderDelegate

    func reader(_ reader: Reader, didStartReconnect cancelable: Cancelable, disconnectReason: DisconnectReason) {
        // 1. Notified at the start of a reconnection attempt
        // Use cancelable to stop reconnection at any time
    }

    func readerDidSucceedReconnect(_ reader: Reader) {
        // 2. Notified when reader reconnection succeeds
        // App is now connected
    }
    func readerDidFailReconnect(_ reader: Reader) {
        // 3. Notified when reader reconnection fails
        // App is now disconnected
    }
}

For more details and code snippets, see automatically attempting to reconnect.

Update your reader disconnect handling

• To be informed when a reader disconnects, we consolidated the reader disconnect callbacks for all reader types by removing terminal:didReportUnexpectedReaderDisconnect: from the SCPTerminalDelegate. Use reader:didDisconnect: as part of the ReaderDelegates to be notified when a reader disconnects. For mobile readers, the SCPDisconnectReason can help identify the reason for the disconnection.

With auto-reconnection enabled, both -readerDidFailReconnect: and reader:didDisconnect: methods are called if the SDK fails to reconnect to the reader and it becomes disconnected.

Before

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
    }
}

After

import StripeTerminal

class ReaderViewController: UIViewController, MobileReaderDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Set the reader delegate when connecting to a reader
    }

    // ...



    func reader(_ reader: Reader, didDisconnect reason: DisconnectReason) {
        // Consider displaying a UI to notify the user and start rediscovering readers
    }
}

For more details, refer to our documentation about handling disconnects manually.

Update your payment acceptance integration

• You can now cancel confirmPaymentIntent using the returned Cancelable object. You can use this for QR code payments, which have an asynchronous confirmation process. Similarly, confirmSetupIntent and confirmRefund are also now cancelable.
• We improved type safety and consistency between the mobile SDKs by updating the way paymentMethodTypes are specified in SCPPaymentIntentParameters and SCPSetupIntentParameters. Previously, this parameter was represented as an array of strings (for example, [“card_present”]). It now uses enum values from SCPPaymentMethodType.
• To improve the cancellation flow for PaymentIntents and SetupIntents, calling Terminal::cancelPaymentIntent or Terminal::cancelSetupIntent now also cancels any ongoing payment processing. You no longer need to cancel payment operations such as .collectPaymentMethod separately before canceling the PaymentIntent.
• SCPSetupIntent.stripeId is now nullable to be consistent with SCPPaymentIntent.stripeId. Although the stripeId value will continue to exist, make sure your code safely handles the case where SCPSetupIntent.stripeId might be null to avoid compiler errors.

Update usage for renaming and deprecation

• BluetoothReaderDelegate has been renamed to MobileReaderDelegate.
• In SCPReaderSoftwareUpdate, we renamed SCPUpdateTimeEstimate to SCPUpdateDurationEstimate and estimatedUpdateTime to durationEstimate to better represent their intent.
• In SCPOfflineDetails, which represents payment details available when a payment is created or confirmed while offline, we renamed the time that the offline payment happened from collectedAt to storedAt, aligning with the naming conventions in the Terminal Android SDK.
• We renamed “local mobile” and “apple built in” to “Tap To Pay” in all SDK function names and error codes.