Terminal
Beta migration guide

Stripe Terminal beta migration guide

Learn how to migrate from the Stripe Terminal beta.

Thank you for being part of the Stripe Terminal beta programs — your feedback has been invaluable!

As part of the move to scaled availability of the the Terminal APIs and SDKs, we’ve made a number of changes to improve functionality, consistency across the SDKs, and interoperability with other Stripe products. Some of these changes are backwards-incompatible and may require you to update your Stripe Terminal integration.

If you built a Stripe Terminal integration during a beta, use this guide to update your integration. The deadline for these required changes depends on whether you started accepting live payments using Stripe Terminal before October 22, 2019.

Summary

  • Terminal SDK Changes
    • Released v1 of our iOS, JS, and Android SDKs. Updates include API changes as well as a number of usability improvements.
  • API Changes
    • Deprecated the operator_account parameter from the Stripe Terminal APIs and added functionality to the Location and Connection Token endpoints.
  • Reader Software Updates
    • BBPOS Chipper 2X BT: Fixed an issue with American Express contactless transactions.
    • Verifone P400: Changed the behavior of the red X button in test mode.

Terminal SDK changes

Stripe periodically releases updates to the Stripe Terminal JavaScript SDK, the Stripe Terminal iOS SDK, and the Stripe Terminal Android SDK, which can include new functionality, bug fixes, and security updates. Update your integrated version of the Stripe Terminal JavaScript, iOS, or Android SDK as soon as a new version is available.

You’ll need to complete this mandatory update before October 2020, to continue using Stripe Terminal for live payments.

SDK Accepted live payments Update Requirement
JavaScript Yes Update to v1 or above before October 2020.
JavaScript No Update to v1 or above in order to accept live payments.
iOS Yes Update to v1.0.0 or above before October 2020.
iOS No Update to v1.0.0 or above in order to accept live payments.
Android Yes Update to v1.0.0 or above before October 2020.
Android No Update to v1.0.0-b7 or above in order to accept live payments. Update to v1.0.0 or above before October 2020.

JavaScript SDK v1

If it’s your first time using Terminal, skip to Getting Started.

If you used Terminal in test mode prior to June 10, 2019, migrate your application to v1 in order to begin accepting live mode payments. Be sure to review the Integration Checklist before using your application to accept live payments.

If you already accept live mode payments with an earlier version of the JavaScript SDK, migrate your application to use v1 before October 2020, to continue using Stripe Terminal.

To view the changelog and update your integration, see the JavaScript SDK Changelog.

iOS SDK v1.0.0

If it’s your first time using Terminal, skip to Getting Started.

If you used Terminal in test mode prior to June 10, 2019, migrate your application to use v1.0.0 or later in order to begin accepting live mode payments. Be sure to review the Integration Checklist before using your application to accept live payments.

If you already accept live mode payments with an earlier version of the iOS SDK, migrate your application to use v1.0.0 or later before October 2020, to continue using Stripe Terminal. You must also ensure all client installations of your application are updated.

To view the changelog and update your integration, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.

Android SDK v1.0.0

If it’s your first time using Terminal, skip to Getting Started.

If you used Terminal in test mode prior to October 21, 2019, migrate your application to use v1.0.0 or later in order to begin accepting live mode payments. In particular, please review step 4 of the SDK set up guide, as the dependencies on TerminalLifeCycleObserver and having an Application are new. Also review the Integration Checklist before using your application to accept live payments.

If you already accept live mode payments with an earlier version of the Android SDK, migrate your application to v1.0.0 or later before October 2020, to continue using Stripe Terminal. You must also ensure all client installations of your application are updated.

To view the changelog and update your integration, see the Releases page on GitHub. To receive notifications when a new release is published, watch releases for the repository.

API changes

Operator account

We will remove the operator_account parameter for Connect platforms from Stripe API libraries and the Stripe API on October 9, 2019. We have marked the operator_account as deprecated in Stripe API libraries, and will not 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 are a Connect platform using the operator_account parameter and destination charges, the best way to group Reader objects is by assigning them to Locations. We suggest that you group Readers for connected accounts by creating a Location object for each account. You may optionally create multiple Location objects for a single connected account, depending on your data model. Your backend will need 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.

Connection tokens

Previously, you could scope the creation of a Connection Token by providing operator_account as a parameter. Since operator_account is now deprecated, Connection Tokens can now be optionally be scoped by providing a Location(/docs/api/terminal/locations).

Default 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 have 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 have not created any Locations, listing all Locations returns an empty list.
  • Readers created without specifying a Location ID will now return an empty location field.
  • Readers created without specifying a Location ID will 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 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 cannot update itself. For more information, see Updating reader software.

Verifone P400

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.

Was this page helpful?
Questions? Contact us.
Developer tutorials on YouTube.