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 and which country you accepted payments in.

    • 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
      • Merged the CA beta JS SDK into v1. Updates include API changes to the client-side refund methods.
    • API Changes
      • Updated our handling of issuer soft declines on tapped transactions, which may result in you seeing multiple charges for a single PaymentIntent.
    • Reader Software Updates
      • Verifone P400: Changed the behavior of the reader for issuer soft declines on tapped transactions; we now support a soft decline recovery flow.

    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 July 1, 2020, to continue using Stripe Terminal for live payments.

    SDK Accepted live payments Update Requirement
    JavaScript Yes Update to v1 or above before July 1, 2020.
    JavaScript No Update to v1 or above in order to accept live payments.
    iOS Yes Update to v1.0.0 or above before July 1, 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 July 1, 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 July 1, 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 July 1, 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 July 1, 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. 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 v1.0.0 or later before July 1, 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.

    JavaScript SDK v1

    If it’s your first time using Terminal, skip to Getting Started and review our Canada documentation.

    If you already accept live mode payments with the CA beta version of the JS SDK, migrate your application to use v1 before August 1, 2020, to continue using Stripe Terminal.

    v1 includes the following changes:

    • The processRefund method processes a client-side refund and is required in order to initiate Interac refunds. In the CA beta SDK, if a refund fails, the method returns a Promise that resolves to a refund object. You may have used the status property of the returned refund object to check for refund failures. We have updated this method to return a Promise that resolves to either:
      • a refund object if the refund was successful, or
      • an error, if the command failed.
    • The collectRefundPaymentMethod method now requires a currency parameter.

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

    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.

    We updated our handling of issuer soft declines, which may improve your authorization rates but will also impact your API integration.

    A soft decline is when a cardholder attempts a tapped transaction and their issuing bank declines it out of preference for a chip-insert, PIN-authenticated transaction. This occasionally happens for high risk or high value transactions. We now support a new soft decline recovery flow: after a soft decline, the reader will prompt the customer to insert their card and retry the payment.

    For these transactions, you will see multiple charges for a single PaymentIntent. The first will be the soft-declined charge with an offline_pin_required message and contactless_emv read method, and the second will be the retried charge with contact_emv read method. The retried contact_emv charge will result in an authorization or a hard decline.

    If you are already re-using PaymentIntents for multiple charge attempts, you will not need to update your integration.

    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.

    As of May 26, 2020, after a soft decline on a tapped transaction, the reader now prompts the customer to insert their card and retry the payment.

    Was this page helpful?

    Feedback about this page?

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

    On this page