Skip to content

@danj-stripe danj-stripe released this Sep 9, 2019 · 1 commit to master since this release

If you are using CocoaPods, update your Podfile:

pod 'StripeTerminal', '1.0.1'


  • Removed entries in SCPDeprecations.h from pre v1.0 beta releases. If you still need to update your app from a beta release, we recommend updating using v1.0.0 first, and then updating to the latest.
  • Fixed paymentMethodDetails.cardPresent.brand to return the correct values for .amex and .dinersClub. In v1.0.0, these brands were incorrectly being returned as .unknown.
Assets 3

@danj-stripe danj-stripe released this Jun 7, 2019 · 3 commits to master since this release

If you are using CocoaPods, update your Podfile:

pod 'StripeTerminal', '1.0.0'

Changes from 1.0.0-rc2

  • Adds Reader.simulated property, to tell whether a reader is simulated or not.

  • The Terminal.connectedReader property will now be nil when the SDK calls your TerminalDelegate.terminal(_:didReportUnexpectedReaderDisconnect:) method. In previous releases, it contained the previously connected Reader object. The previously connected reader is still available, as a parameter of this method.

  • When a SCPErrorSessionExpired has been thrown (see SCPErrors.h for more details on when this is thrown) we now call TerminalDelegate.didReportUnexpectedReaderDisconnect after a successful auto-disconnect. Note there is a small chance the disconnect fails and this callback will not be called. You can check Terminal.connectionStatus in your completion block that received the SCPErrorSessionExpired to see if your reader is still connected.
Assets 3

@danj-stripe danj-stripe released this May 30, 2019 · 5 commits to master since this release


If you are using CocoaPods, update your Podfile:

pod 'StripeTerminal', '1.0.0-rc2'

Other changes

  • Adds SCPCardPresentDetails.generatedCard, which provides a reusable card PaymentMethod from a processed PaymentIntent. See for more details.

  • The ReadReusableCardParameters object passed to Terminal.readReusableCard() now includes a customer property which, if included, will attach the newly created PaymentMethod to the specified customer.

  • Terminal.readReusableCard() no longer prompts for ReaderInputOptionTapCard

  • Fixes a race condition caused by quickly canceling Terminal.collectPaymentMethod() or Terminal.readReusableCard(), which would lead to subsequent commands failing with SCPErrorBusy.

  • Removes SCPErrorCancelFailedReaderBusy. Starting with this release, the SDK now takes as long as it needs to ensure the command is canceled or completes (whichever happens first), instead of sometimes reporting that it was unable to cancel for certain hardware states and then continuing the command.

  • We will now attempt to automatically disconnect the card reader if a server request results in an SCPErrorSessionExpired error. The reader must be reconnected to start a new session. If our attempt at disconnecting the reader fails you may need to disconnect it yourself.

  • The Terminal.checkForUpdate completion block will now be passed nil and no error rather than being passed SCPErrorNoAvailableReaderSoftwareUpdate when there is no update present.

  • Terminal.collectPaymentMethod and Terminal.readReusableCard will now fail with SCPErrorCardLeftInReader when the reader still contains the credit card from a previous transaction. The same card can be used for more than one transaction, but it must be removed and re-inserted for each one. Previously, instead of failing immediately, the collectPaymentMethod/readReusableCard request would fail silently and users needed to cancel the request in order to proceed.

Assets 3

@catriona-stripe catriona-stripe released this Apr 19, 2019 · 9 commits to master since this release

If you are using CocoaPods, update your Podfile:

pod 'StripeTerminal', '1.0.0-rc1'


The initializers for DiscoveryConfiguration have changed. Rather than specifying a readerSimulator device type, you can now specify that the configuration is simulated. This allows for the SDK to simulate all device type and discovery method combinations. The readerSimulator device type has been removed.

Previously, the init(deviceType:method:) was nullable, and would return nil if an invalid device type and discovery method combination was provided. That method has been replaced with init(deviceType:discoveryMethod:simulator:), which is no longer nullable. If an invalid device type and discovery method combination is provided, the subsequent call to discoverReaders will fail with SCPErrorInvalidDiscoveryConfiguration.


This release uses PaymentMethods instead of Sources. They're similar concepts, but it means we've shuffled things around. In b6 (and earlier), a Source would be added to your PaymentIntent during Terminal.confirmPaymentIntent(), or a standalone card_present Source could be created via Terminal.readSource().


The Terminal.confirmPaymentIntent() method has been replaced by Terminal.processPayment(). In this flow, the CardPresentSource class has been replaced by CardPresentDetails:

  • The returned PaymentIntent no longer has a CardPresentSource property. Instead, find the CardPresentDetails object on the Charge(s) in PaymentIntent.charges.
  • Each Charge has a PaymentMethodDetails object, with transaction-specific details about the payment method used. For the StripeTerminal SDK collectPaymentMethod & processPayment flow, these PaymentMethodDetails will be of type == .cardPresent, and their cardPresent property has the CardPresentDetails.
  • The CardPresentSource.stripeId, CardPresentSource.metadata, and properties are not available on CardPresentDetails.
  • CardPresentSource.receiptData is now CardPresentDetails.receipt, and the class name has changed from ReceiptData to ReceiptDetails.

There are a couple other misc related changes:

  • The PaymentIntentStatusRequiresSource status has been renamed PaymentIntentStatusRequiresPaymentMethod.
  • The ReceiptDetails.mid and ReceiptDetails.tid properties have been removed.


The Terminal.readSource() method has been replaced by Terminal.readReusableCard(). A successful readReusableCard call returns a PaymentMethod instead of a CardPresentSource.

The returned payment method is of type == .card, instead of cardPresent. It's no longer necessary to convert the payment method first, these PaymentMethods are immediately usable for online charges, and can be reused.

Properties from the CardPresentSource are now found either on the top-level PaymentMethod (ex: stripeId), or inside the PaymentMethod's card: CardDetails property (ex: brand or fingerprint).

Unexpected reader disconnects

The terminal:didDisconnectUnexpectedlyFromReader: method has been renamed terminal:didReportUnexpectedReaderDisconnect:, and is now required. Your app should handle this method, and notify your user that the reader has disconnected. You may also want to start the discoverReaders process when your app handles this method. Your app can automatically attempt to discover and connect to the previously connected reader, or display UI for your user to re-connect to a reader.

Reader Update API

The terminal:checkForReaderSoftwareUpdate has been renamed and split into two calls: terminal:checkForUpdate and terminal:installUpdate. Instead of calling terminal:checkForReaderSoftwareUpdate and receiving the update via readerSoftwareUpdateDelegate:readerSoftwareUpdateAvailable, terminal:checkForUpdate accepts a completion which is passed the update if one is available. Once you have an update you will have to call terminal:installUpdate. We are deprecating readerSoftwareUpdateDelegate:didCompleteReaderSoftwareUpdate. Instead you will pass a completion to terminal:installUpdate which will be passed nil upon successful completion and an error otherwise.

Other changes

  • The SDK will now request location permissions from the user when your app connects to a reader for the first time. (Feedback from #26)
  • We've fixed issues where connectReader took a long time under certain conditions.
  • Bugfix: In some situations, the completion: blocks for collectPaymentMethod and readSource could execute more than once: reporting a failure followed by a success #28.
  • Added a hasTokenProvider getter, in case you want to check whether you've set a token provider before accessing the shared Terminal singleton. (Feedback from #26)
Assets 3

@danj-stripe danj-stripe released this Jan 29, 2019 · 12 commits to master since this release

If you are using CocoaPods, update your Podfile:

pod 'StripeTerminal', '1.0.0-b6'

Singleton initializer

SCPTerminal is now a singleton, and you will need to update your integration.


let terminal = Terminal(configuration: terminalConfig,
                        tokenProvider: apiClient,
                        delegate: self)


// required
// optional – set a listener to incorporate SDK logs into your own logs
Terminal.setLogListener({ ... })
// optional – set a delegate to receive status updates from the SDK
Terminal.shared.delegate = self

If you rely on destroying and recreating SCPTerminal instances to clear state (for example, to switch between different Stripe accounts in your app), you should instead use the clearCachedCredentials method.

SCPTerminalConfiguration has also been removed, and the logLevel property that was previously on SCPTerminalConfiguration is now a property on SCPTerminal.


The terminal:didEmitLogline method on SCPTerminalDelegate has been removed, and replaced with a static setLogListener method on Terminal class.

Previously, this delegate method was always called on the main thread. Now, the block you provide may be called from any thread.

You can use this optional method to listen for logs from the Stripe Terminal SDK and incorporate them into your own remote logs. Note that these loglines are subject to change, and provided for informational and debugging purposes only. You should not depend on them for behavior in your app.

To print internal logs from the SDK to the console, you can set logLevel to .verbose on the Terminal instance.


The createKeyedSource method has been removed. If you were previously using this functionality, you will need to update your integration to use the Stripe iOS SDK to handle this flow.

updateReaderSoftware -> checkForReaderSoftwareUpdate

The updateReaderSoftware method has been renamed checkForReaderSoftwareUpdate, to make it clearer that this method only checks for any available reader software update. If an update is available, your delegate's readerSoftwareUpdateAvailable method will be called.

  • The UpdateReaderSoftwareParameters class has been removed. When you call checkForReaderSoftwareUpdate, you'll need to pass a ReaderSoftwareUpdateDelegate and a completion block.
  • SCPUpdateReaderSoftwareDelegate has been renamed SCPReaderSoftwareUpdateDelegate, for consistency with the SCPReaderSoftwareUpdate class.

Discovery & Connecting to Readers

This update adds some additional checks to the discovery & connect process. You will
receive errors for some common integration mistakes:

  • You must be actively discovering readers in order to connect to one. Calling
    SCPTerminal connectReader: after canceling the discoverReaders cancelable will now
    fail with SCPErrorMustBeDiscoveringToConnect
  • Calling SCPTerminal connectReader: with a Reader from a different discovery process
    will fail with SCPErrorCannotConnectToUndiscoveredReader.

We found & fixed a bug affecting reader discovery after a failed connect. The Terminal
is still discovering readers, but in previous beta releases it wasn't delivering updates
to the DiscoveryDelegate.

Reader Session reuse, and clearConnectionToken -> clearCachedCredentials

SCPTerminal now caches & re-uses the reader session when reconnecting to the same
reader. This speeds up reconnection and makes it less likely to fail in spotty network

Because of this, the public clearConnectionToken method that's necessary when changing
between testmode/livemode or between different accounts has been renamed for clarity.

Assets 3

@bg-stripe bg-stripe released this Nov 29, 2018 · 17 commits to master since this release


If you are using CocoaPods, update your Podfile:

pod 'StripeTerminal', '1.0.0-b5'

Reader software update: improved sound and visual alerting

We've released an optional reader update for the BBPOS Chipper 2X that enables beeps when a card is inserted and when the transaction completes.

  • After this update, the reader will emit a single beep when a card is inserted, and two beeps when the transaction is complete. Currently, the reader only emits these beeps for contactless transactions.
  • The reader will also issue two beeps, recurring at a 5 second interval, if an inserted card is left in the reader after the transaction has completed.

Note: you will need to update your readers in order to enable this feature. You can update your readers by implementing the SDK's updateReaderSoftware workflow, or by using the provided example app, which includes the ability to update readers. You can download the Example app directly on TestFlight, or build it from source.

You'll need to perform a series of 2 updates in order to enable this functionality on your reader.

  • The current deviceSoftwareVersion should look something like this:
  • The first update will update the firmware on your reader to
    • This firmware adds the ability to beep during contact card presentation.
    • The version for this update will look something like this:
  • The second update will update the configuration of your reader to SZZZ_Generic_v37
    • This configuration enables beeps on card insert, transaction complete, and card left in reader.
    • The version for this update will look something like this:

Other updates

  • retrievePaymentIntent has been renamed in Swift to make it clearer that you must pass a clientSecret as the first argument.
  • When discoverReaders is canceled, the completion block will now be called with nil. Previously, canceling discoverReaders would result in the completion block producing an error with code SCPErrorCanceled. This was surprising to several users, so we've changed the behavior of this method. Note that canceling collectPaymentMethod still produces an error with code SCPErrorCanceled.
  • We've fixed an issue where connecting to a reader immediately after discovery would fail when using the BluetoothDiscovery method.
  • The didRequestReaderInputPrompt delegate method has been modified in Swift to be consistent with other delegate methods.
-    func terminal(terminal: Terminal, didRequestReaderInputPrompt inputPrompt: ReaderInputPrompt) {
+    func terminal(_ terminal: Terminal, didRequestReaderInputPrompt inputPrompt: ReaderInputPrompt) {
Assets 3

@bg-stripe bg-stripe released this Nov 13, 2018 · 17 commits to master since this release

If you are using CocoaPods, update your Podfile:

pod 'StripeTerminal', '1.0.0-b4'

Integration tips

  • If you are using readSource to defer a payment for later, note that the transaction will not receive the beneficial rates and liability shift associated with card present transactions. Most integrations should not use readSource. If you are simply collecting a payment from a customer, you should create a PaymentIntent and use the associated collectPaymentMethod and confirmPaymentIntent methods.
  • Make sure your integration captures the PaymentIntent, and does so on your backend. Our example app previously included a client-side BackendSimulator class, for demonstration purposes only. You should be sure not to do this in your own app. Secret API keys should be kept confidential and stored only on your own servers. Your account’s secret API key can perform any API request to Stripe without restriction, and you should never hardcode your secret API key into your app. The example app now uses an example backend that you can easily deploy to Heroku:

API updates

  • If you are using Connect with destination charges: When using the transferDataDestination parameter to create a PaymentIntent, you you must also specify the onBehalfOf parameter, and this must match the destination account. This makes it explicit that charges are settled in the country of the specified account, and that the connected account’s address and phone number show up on the customer’s credit card statement. For more information, see
  • If you are using Connect with direct charges: The stripeAccount property on SCPPaymentIntentParameters has been removed. To create a PaymentIntent via the SDK on behalf of a connected account, you should set the Stripe-Account header when creating a connection token on your backend. The SDK will inherit this connected account setting from the connection token, and use the same Stripe-Account header whenever it creates or confirms a PaymentIntent.

Pairing improvements

We've made some updates to the Bluetooth Proximity discovery method. If you your app will be used in a busy environment, with multiple iOS devices pairing to multiple available readers at the same time, we highly recommend using the bluetooth proximity discovery method.

  • After a reader has been discovered using the proximity method, the LEDs located above the reader's power button will start flashing multiple colors. After discovering the reader, your app should prompt the user to tap a button to connect to the reader. You may want to tell your user to confirm that the reader is flashing.
  • When discovering a reader using the Bluetooth Proximity method, the didUpdateDiscoveredReaders delegate method will be called twice. It will be called for the first time when the reader is initially discovered. The reader's LEDs will begin flashing. After a short delay, didUpdateDiscoveredReaders will be called a second time with an updated reader object, populated with additional info about the device, like its battery level.
  • BluetoothProximity is now the default discovery method when initializing DiscoveryConfiguration with a device type.

Other changes

  • The timeout for reading a card with collectPaymentMethod has been increased from 1 minute to 5 minutes. If reading a card times out, collectPaymentMethod will fail with the error code SCPErrorCardReadTimedOut.
Assets 3

@bg-stripe bg-stripe released this Oct 26, 2018 · 28 commits to master since this release

Note that if you are using CocoaPods, the version format has changed slightly in this release. In your Podfile:

pod 'StripeTerminal', '1.0.0-b3'

Tap to discover

  • We've added a new discovery method, "Bluetooth Proximity", which you can use to discover a reader by holding it next to the iOS device. We think this will greatly improve the reader discovery experience – please try it out! If you have any feedback on the feature, please file an issue.
  • The initializer for DiscoveryConfiguration now requires specifying a deviceType.

Other changes

  • The batteryLevel property on Reader is now an optional NSNumber (boxing a float from [0.0, 1.0], as before). (h/t @jasonzurita)
  • ReadSourceParameters now has an optional metadata property, which you can use to attach key-value pairs to the source. (h/t @jasonzurita)
  • We've fixed a bug where collectPaymentMethod could not be canceled if a card from a previous payment was left in the reader. (h/t @sgruby-reformation)
  • ConfirmError now has an optional declineCode property. If the payment was declined, this property contains the decline_code from the Stripe API. (h/t @sgruby-reformation)
  • terminal.cancel has been renamed to terminal.cancelPaymentIntent in Swift, for clarity
  • didReport:info: has been renamed to didReportReaderEvent:info: in Swift, for clarity
  • Several error codes have been renamed:
    • ReaderError has been renamed UnknownReaderError
    • SDKError has been renamed UnexpectedSdkError
    • NetworkError has been renamed UnknownNetworkError
Assets 3

@bg-stripe bg-stripe released this Oct 1, 2018 · 40 commits to master since this release


Card insert and removal events

  • You can now use the new ReaderEvent enum to detect card insert and removal events, using the optional didReportReaderEvent method on TerminalDelegate.
  • Note: if you're a participant in the alpha program, you will need to update your existing readers to the latest firmware configuration in order to see card insert and removal events. (Any new readers you order will come pre-loaded with this configuration). You can update your readers by implementing the SDK's updateReaderSoftware workflow, or by using the provided example app, which includes the ability to update readers. You can download the Example app directly by joining the TestFlight beta, or build it from source.


UpdateReader has been renamed UpdateReaderSoftware to distinguish between updating the Reader object in the Stripe API, and updating the software on the physical reader. Other related changes:

  • The updateReader method has been renamed updateReaderSoftware, and returns a Cancelable.
  • The UpdateReaderDelegate protocol has been renamed UpdateReaderSoftwareDelegate. Methods within this protocol have also been renamed.
  • The ReaderUpdate object has been renamed ReaderSoftwareUpdate
  • InstallUpdateCompletionBlock has been renamed InstallUpdateBlock, as it is not a completion block.
  • A deviceSoftwareVersion property has been added to the ReaderSoftwareUpdate object, which you can use to determine the target update version.
  • The updateReaderSoftware method call now requires an UpdateReaderSoftwareParameters object. Typically, you will not need to modify the default parameters object, as nearly all readers are registered in the production environment. However, if you received readers as part of the alpha program, you may need to set environment to test in order to update some of your readers. If this is the case, please contact your account manager to arrange exchanging this reader for a production reader.

Other changes

  • The polymorphic Terminal.string(from:) methods in Swift have been renamed to individual stringFrom{Type} methods.
  • The didDisconnectUnexpectedlyFrom method has been renamed to didDisconnectUnexpectedlyFromReader in Swift, for consistency.
  • The AttachingSource value in the PaymentStatus enumeration has been renamed to CollectingPaymentMethod.
  • The ReaderInputPrompt enumeration has a new TryAnotherCard value, used to indicate that the presented card is invalid. This value is used to indicate that the user should try another card. This indicates the user should try a different card. In contrast, the TryAnotherReadMethod prompt means the user should either: 1. try another read method on the same card (e.g. swipe if the card was inserted), or 2. try a different card.
Assets 3
Sep 18, 2018
v1.0 beta 1
You can’t perform that action at this time.