The Stripe Terminal iOS and Android SDKs have been updated to support new readers, global payment processing, and enhanced connectivity and update behavior. To support this new functionality, we’ve made a number of changes, some of which will require that you update your integration with the Stripe Terminal SDK. This guide will walk you through the breaking changes and help you upgrade your integration.
Migrating to version 2.0.0
Here’s what you need to know about the 2.0.0 Stripe Terminal iOS and Android SDKs:
- The reader connection API has changed.
- We now support using Locations with Bluetooth readers.
- Both Bluetooth and Internet readers require the use of locations.
- In some cases, Stripe might need to dispatch an update to Bluetooth readers for security or compliance reasons. Supporting mandatory updates upon reader connection is now required.
Migrating from a prerelease SDK to 1.0.0
Terminal SDK changes
We removed the
operator_account parameter for Connect platforms from Stripe API libraries and the Stripe API on October 9, 2019. We’ve marked the
operator_account as deprecated in Stripe API libraries, and won’t allow new accounts to use the
operator_account parameter going forward.
Until October 9, 2019, your existing platform account can continue to use the
operator_account parameter in test mode. However, you will not be able to view readers registered with the
operator_account parameter in the Stripe Dashboard, and will not be able to use the
operator_account parameter in live mode.
If you’re a Connect platform using the
operator_account parameter and destination charges, group Reader objects by assigning them to Locations. Group readers for connected accounts by creating a Location object for each account. You can optionally create multiple Location objects for a single connected account, depending on your data model. Your backend needs to associate Location IDs with their corresponding connected accounts. For more information on using Locations to group Reader objects on your platform account, see Using Terminal with Connect.
Previously, you could scope the creation of a Connection Token by providing
operator_account as a parameter. Because
operator_account is now deprecated, you can scope Connection Tokens by providing a Location.
Previously, if you registered a Verifone P400 reader to your Stripe Account without specifying a Location object, the reader would be assigned to a “default” Location object created for each Stripe Account. We’ve made changes to how the default Location object appears in the Stripe API and the Stripe Dashboard. For more information on using locations to group readers, see Fleet Management.
- When listing Location objects, the API no longer returns the ID of the default Location object. If you haven’t created any Locations, listing all Locations returns an empty list.
- Readers created without specifying a Location ID now return an empty location field.
- Readers created without specifying a Location ID now appear under the Ungrouped Readers tab in the Stripe Dashboard.
Reader software updates
Stripe and our hardware partners periodically release reader software updates, which can include improvements and required security updates. The Verifone P400 reader software updates automatically. The BBPOS Chipper 2X BT reader software and BBPOS WisePad 3 reader software must be updated manually. As reader software updates are made available, update your readers to the latest available version to continue using Stripe Terminal. Failing to install a required manual update can prevent a reader from accepting payments.
BBPOS Chipper 2X BT
If you use the BBPOS Chipper 2X BT, you must update all of your readers to the latest available software version immediately to continue using Stripe Terminal. This mandatory update includes the latest configuration for the BBPOS Chipper 2X BT that fixes a read failure issue when processing certain American Express contactless transactions.
You must support updating the BBPOS Chipper 2X BT from your app. The reader can’t update itself. For more information, see Updating reader software.
Previously, when using the reader in test mode, the red
X button would clear the full transaction state, similar to the
clearReaderDisplay method, and reset the reader to the splash screen. This was different from behavior in live mode. In live mode, the red
X button clears the payment state, similar to
cancelCollectPaymentMethod, returning the screen to the cart display.
We’ve changed the test mode behavior of the red
X button to match live mode behavior. In both test and live modes, the red
X button now clears the payment state, returning the screen to the cart display.