Skip to content

v2.0.0
Compare
Choose a tag to compare
@danwaters-stripe danwaters-stripe released this 23 Jun 21:24
· 83 commits to master since this release
v2.0.0
a31ffdc
This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
GPG key ID: 4AEE18F83AFDEB23
Expired
Learn about vigilant mode.

If you're using Gradle, update your build file to:

implementation "com.stripe:stripeterminal:2.0.0"

Summary

The Stripe Terminal Android SDK has 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 are
backwards-incompatible with the current Stripe Terminal Mobile SDKs.

If you’re upgrading from a 1.x release, here’s what you need to know:

  • Connecting to a reader has changed.
  • We now support using
    locations with bluetooth
    readers like the Chipper 2X or WisePad 3.
  • Use of locations is now required.
  • In some cases, Stripe might need to push an update to readers for security or
    compliance reasons; your integration must now support a new optional /
    required update flow.

For upgrading an integration from an older release, see our SDK migration
guide

Connecting to a reader

connectReader has been split into two separate methods: connectBluetoothReader and connectInternetReader.

connectBluetoothReader

connectBluetoothReader should be used to connect to any Bluetooth reader like the BBPOS WisePad 3 and BBPOS Chipper 2X BT.

  • connectBluetoothReader requires providing a new BluetoothReaderListener
    which is used to report all reader events.
  • The onReportReaderEvent and onReportLowBatteryWarning methods have been
    moved from the TerminalListener to the BluetoothReaderListener.
  • ReaderDisplayListener has been removed and the onRequestReaderInput and
    onRequestReaderDisplayMessage methods have been moved to the
    BluetoothReaderListener.
  • ReaderSoftwareUpdateListener has been removed, and the
    BluetoothReaderListener is used for communicating to your app about updates
    for the reader.

See Updating reader software: Required
updates
for more details.

connectInternetReader

connectInternetReader should be used to connect to Internet connected
countertop readers like the Verifone P400 or the BBPOS WisePOS E. There are no
changes required between connectReader and connectInternetReader for your
countertop reader integration.

Bluetooth reader updates

The checkForUpdate method has been removed. The Stripe Terminal SDK now
checks for required and optional updates during reader connection.

Required update installation is reported to the new BluetoothReaderListener
with the onStartInstallingUpdate method. Progress will be reported to that
same delegate with onReportReaderSoftwareUpdateProgress. When the
installation of the required update finishes the delegate will receive the
onFinishInstallingUpdate.

For more information about implementing reader updates, see Updating reader
software
and simulated reader
updates.

Bluetooth reader locations

Like Internet readers, Bluetooth readers must now be registered to
Locations. Registering your
Bluetooth readers to a location ensures that the readers install the proper
regional configurations and are properly grouped on your account.

To register the reader to a location, create and use a
BluetoothConnectionConfiguration object with the locationId set accordingly,
and pass that object in when calling Terminal.connectBluetoothReader.

When discovering readers that have already been registered to a location, those
reader objects will have a valid locationId property during discovery. If it
makes sense for your application, you can pass that locationId from the
discovered Reader object into the BluetoothConnectionConfiguration
initializer to keep that reader registered to the same location. This is the
pattern we recommend when discovering and connecting to simulated Bluetooth
readers, which are now automatically registered to a mock location.

When connecting to a reader, you may want to display a list of Locations in
your app. To enable this, the SDK provides the Terminal.listLocations method
that takes the same parameters as the List all
Locations API endpoint.
You may want to adjust your connection flow to allow users to pick a location
before they select a reader, should they want to switch that reader's location
manually.

Detailed changes

  • installUpdate has been replaced by a no-argument installAvailableUpdate
    method, which installs the update stored on the connected reader's
    availableUpdate.
  • Incremental updates are now treated the same as required updates, resulting in the following
    changes:
    • Removed UPDATING from ConnectionStatus. All updates are now exclusively communicated via the
      BluetoothReaderListener. Required updates that are installed while connecting to a reader will
      be performed while the ConnectionStatus is CONNECTING.
    • All required reader software updates now report
      BluetoothReaderListener.onStartInstallingUpdate and the Cancelable provided is now
      nullable. When an incremental-only change is announced, the Cancelable will be null since
      these incremental changes are required and cannot be canceled.
    • ReaderSoftwareUpdate now has a components property that can be used to determine the changes
      that will be applied with this update. version can still be used to identify the specific
      firmware, config, and keys that will be installed with the update.
    • On SimulateReaderUpdate, replaced REQUIRED_INCREMENTAL REQUIRED_FULL with REQUIRED since
      these update types now behave the same.
  • We have changed our packaging for models and callables:
    • Models have been moved from com.stripe.stripeterminal.model to
      com.stripe.stripeterminal.external.models.
    • Callables have been moved from com.stripe.stripeterminal.callable to
      com.stripe.stripeterminal.external.callable.
  • Replaced TerminalLifecycleObserver with TerminalApplicationDelegate. Users now must invoke
    TerminalApplicationDelegate.onCreate and TerminalApplicationDelegate.onTrimMemory from their
    applications.
  • Fixed BluetoothReaderListener.onReportReaderEvent to properly report card insertion & removal
    events.
  • Updated amount types from Int to Long for the following fields:
    • PaymentIntent.amount, PaymentIntent.amountCapturable, PaymentIntent.amountReceived, &
      PaymentIntent.applicationFeeAmount
    • PaymentIntentParameters.amount & PaymentIntentParameters.applicationFeeAmount
    • Charge.amount, Charge.amountRefunded, & Charge.applicationFeeAmount
    • RefundParameters.amount
    • Refund.amount
    • SingleUseMandate.amount
  • Renamed error code PAYMENT_DECLINED_BY_STRIPE_API to DECLINED_BY_STRIPE_API
  • Renamed error code PAYMENT_DECLINED_BY_READER to DECLINED_BY_READER
  • When a reader unexpectedly disconnects during an operation, we swapped the callback order for
    TerminalListener.onUnexpectedReaderDisconnect and Callback.onFailure. Now,
    Callback.onFailure will be called first and TerminalListener.onUnexpectedReaderDisconnect will
    be called second. This fixes a bug where we incorrectly failed any new operation started within
    the context of a TerminalListener.onUnexpectedReaderDisconnect callback.

New features

  • Invite only: Added support for creating SetupIntents with the WisePad 3.
  • Added support for Interac transactions and refunds
  • Added support for setting a SimulatedCard on the SimulatorConfiguration
    object, allowing simulation of different card brands and decline types
  • Added support for the P400 in the U.S.
Assets 2
Loading