Terminal SDK V3 migration guide

If your application currently uses an Terminal iOS SDK version prior to 3.0.0, there are a few changes you need to make to upgrade and accept card present payments globally. For a detailed list of the changes from version 2.23.1 to 3.0.0, please reference the SDK changelog.

Update your minimum supported version to iOS 13 or higher

We regularly update the minimum supported version of our SDKs in order to focus on providing the best experience for our developers.

Existing 2.X versions of the Terminal iOS SDK will continue to support devices running iOS 11 and higher.

Update your DiscoveryConfiguration usage to the specific DiscoveryConfiguration implementation

In order to support configuration for different discovery methods, SCPDiscoveryConfiguration is now a protocol that is implemented by several different types. Instead of providing a DiscoveryMethod, there are now individual classes to choose from in order to search for a specific type of reader:

Create the discovery configuration appropriate for your desired discovery method using the provided builder class and provide that to discoverReaders. The builder exposes setters for the properties that each configuration supports.

Update your discoverReaders and connectReader usage

• Canceling discoverReaders now calls the completion block with an error with code SCPErrorCanceled, just like all other cancelable methods.
• discoverReaders is now completed successfully right when connectReader is called. If connectReader fails, your integration needs to make a new call to discoverReaders in order to resume discovering readers.
• discoverReaders is no longer required to be running for connectReader to work. You’re now able to call connectReader with a previously discovered reader instance or to retry connecting without restarting discoverReaders.

Update your ReconnectionDelegate implementation

SCPReconnectionDelegate now provides the instance of the reader that is being reconnected to instead of the Terminal instance. If you implemented this delegate before you need to replace terminal in the method names with reader.

Update Parameters and Configuration class usage to use Builders

The input classes like SCPCollectConfiguration and SCPPaymentIntentParameters are now immutable and have associated builders provided to create them. All builders have a build method that validates the inputs and creates the class it builds.

• In Swift, build() throws and should be checked for errors.
• In Objective-C, you provide an NSError ** out-parameter to receive the error, if any.

let paymentParams = try PaymentIntentParametersBuilder(amount: 100, currency: "cad")
  .setCaptureMethod(.automatic)
  .build()

Remove any dependency on SCPErrorBusy

SCPErrorBusy is removed. In SDK 3.0.0 and later, if you call a Terminal method while another is still in-progress the new calls now queue up. The commands are executed after all previous commands complete. If you were previously tracking state to prevent SCPErrorBusy, or were queuing your own commands to work around SCPErrorBusy, you can now make use of the command queue to simplify your code. If your application relied on SCPErrorBusy to know if a command is running, review your code to see if this could cause problems with queuing too many commands.

Review support for Offline Payments

SCPPaymentIntent.stripeId is null for offline payments. If your integration only supports online payments, the stripeId will always be present and no changes are needed beyond checks to satisfy the presence of the ID. See Collect card payments while offline for more details on how to process payments offline.

Terminal.shared.createPaymentIntent(params) { intent, error in
  if let error = error {
    // Placeholder for handling exception
  }
  guard let intentId = intent.stripeId else {
    // PaymentIntent was created offline without an id. See intent.offlineDetails.
    // This is only expected when offline mode is enabled.
  }
}

Update your process calls to confirm

SCPTerminal.processPayment is renamed to SCPTerminal.confirmPaymentIntent and SCPTerminal.processRefund is renamed to SCPTerminal.confirmRefund. The parameters for these methods haven’t changed but the error types have also been renamed to SCPConfirmPaymentIntentError and SCPConfirmRefundError respectively.

Update your readReusableCard usage to SetupIntents

SCPTerminal.readReusableCard is removed. SetupIntents are the recommended path for saving payment methods without charging. SetupIntents follow a similar pattern to PaymentIntents where you create, collect, and then confirm the SetupIntent in the SDK. See Save payment details for online re-use for more details.