Stripe Terminal Beta Migration Guide

    Learn how to migrate from the Stripe Terminal beta.

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

    As part of the move to general 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 the 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 June 10, 2019.

    • Terminal SDK Changes
      • We released v1 of our iOS and JS SDKs and b7 of the Android SDK. These updates include API changes as well as a number of usability improvements.
    • API Changes
      • We 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

    If you use the JavaScript or iOS SDK, you’ll need to complete this mandatory update before September 9, 2019, to continue using Stripe Terminal. If you use the Android SDK, you’ll need to complete this mandatory update within 90 days after the Android SDK enters general availability to continue using Stripe Terminal.

    SDK Accepted live payments Update Requirement
    JavaScript Yes Update to v1 or above before September 9, 2019.
    JavaScript No Update to v1 or above in order to accept live payments.
    iOS Yes Update to v1.0.0 or above before September 9, 2019.
    iOS No Update to v1.0.0 or above in order to accept live payments.
    Android Yes Update to v1.0.0 or above 90 days after the Android SDK enters general availability.
    Android No Update to v1.0.0-b7 or above in order to accept live payments. Update to v1.0.0 or above 90 days after the Android SDK enters general availability.

    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 September 9, 2019, 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 September 9, 2019, 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 beta 7

    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-b6 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 Android SDK, migrate your application to the v1.0.0 version of the Android SDK within 90 days after the Android SDK enters general availability to continue using Stripe Terminal. You must also ensure all client installations of your application are updated. If you integrate with the Android SDK in beta, Stripe will contact you when the Android SDK enters general availability via the email associated with your Stripe account.

    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.

    SDK updates

    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.

    API Changes

    Operator Account

    We will remove the operator_account parameter for Connect platforms from Stripe API libraries and the Stripe API on September 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 September 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.

    Conection 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? Yes No

    Send

    Thank you for helping improve Stripe's documentation. If you need help or have any questions, please consider contacting support.

    Questions?

    We're always happy to help with code or other questions you might have. Search our documentation, contact support, or connect with our sales team. You can also chat live with other developers in #stripe on freenode.

    On this page