4.2.0 release (#554)

Author: sjl-stripe

CHANGELOG.md

@@ -3,6 +3,18 @@
 This document details changes made to the SDK by version. The current status
 of each release can be found in the [Support Lifecycle](SUPPORT.md).
 
+## 4.2.0 - 2025-02-24
+
+### Core
+- New: Added error code [`READER_TAMPERED`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/-r-e-a-d-e-r_-t-a-m-p-e-r-e-d/index.html)
+- Fix: Addressed an issue where readers lose optional software updates after auto-reconnecting.
+
+### Tap to Pay
+
+- New: [`HIDE_OVERLAY_WINDOW`](https://developer.android.com/security/fraud-prevention/activities#hide_overlay_windows) permission is now required for Tap to Pay to ensure a secure environment while operating.
+- Fix: Allow the Tap to Pay reader to connect from applications that have enabled installer checks in Google Play. Fixes [issue 866](https://github.com/stripe/stripe-terminal-react-native/issues/866).
+- Fix: Localization issues for Tap to Pay on Android PIN preview.
+
 ## 4.1.0 - 2024-11-18
 
 ### Core
@@ -12,7 +24,7 @@ of each release can be found in the [Support Lifecycle](SUPPORT.md).
 - Update: Added support for operating offline with simulated Bluetooth and USB readers.
 - Preview: Added a new enum value `Manual` to [`CardPresentCaptureMethod`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-card-present-capture-method/-companion/index.html) which will override the top level [`captureMethod`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-payment-intent-parameters/index.html?query=class%20PaymentIntentParameters) set on the Paymentintent specifically for `card_present` transactions.
   - If you are interested in joining this preview, please email [[email protected]](mailto:[email protected]).
-- Preview: [`Terminal::collectData`](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/collect-data.html) will be supported on Smart readers. 
+- Preview: [`Terminal::collectData`](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/collect-data.html) will be supported on Smart readers.
   - _Note: [This feature](https://docs.stripe.com/terminal/features/collect-data) requires [reader software version](https://stripe.com/docs/terminal/readers/bbpos-wisepos-e#reader-software-version) `2.28` or later to be installed on your smart reader._
   - If you are interested in joining this preview, please email [[email protected]](mailto:[email protected]).
 - Fix: Fixed an issue where, if the SDK was initialized offline and a user immediately attempts to pair a reader offline, the first attempt fails with "The selected reader requires a software update", despite the reader being up-to-date.
@@ -30,7 +42,7 @@ Add support for apps built with `targetSdkVersion = 35` targeting Android 15 dev
   - Note: This update includes support for Tap to Pay on Android. Users who were previously advised not to upgrade can now safely target version 35.
 
 #### New Features
-* [Mail order / telephone order (MOTO)](https://docs.stripe.com/terminal/features/mail-telephone-orders/overview) payment support for smart readers. 
+* [Mail order / telephone order (MOTO)](https://docs.stripe.com/terminal/features/mail-telephone-orders/overview) payment support for smart readers.
   - Contact Stripe support to enable this feature on your account.
 * Global [card saving after payment](https://docs.stripe.com/terminal/features/saving-cards/save-after-payment) support by updating customer consent capture. The following **breaking changes** are required:
   - Removed the `customerConsentCollected` parameter from `Terminal::collectSetupIntentPaymentMethod` and replaced it with `allowRedisplay`.
@@ -45,11 +57,11 @@ Add support for apps built with `targetSdkVersion = 35` targeting Android 15 dev
 - Update: Internet and Tap to Pay discovery will now call the [`discoverReaders`](https://stripe.dev/stripe-terminal-ios/docs/Classes/SCPTerminal.html#/c:objc(cs)SCPTerminal(im)discoverReaders:delegate:completion:) completion block when the operation completes since these are not long running discovery operations.
 - Update: Fields on the [`Location`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-location/index.html) object are no longer mutable.
 
-#### Reader connection 
+#### Reader connection
 
 - Update: There is now a single [`Terminal::connectReader`](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/connect-reader.html) method for all connection types. This replaces the previous methods: `connectBluetoothReader`, `connectUsbReader`, `connectInternetReader`, `connectLocalMobileReader`, and `connectHandoffReader`.
   - For mobile readers, the `readerListener` parameter has been removed from the old `connectBluetoothReader`, `connectUsbReader` methods and moved into the respective `ConnectionConfiguration` object, replacing `ReaderReconnectionListener`.
-  - For Tap to Pay readers, the `TapToPayConnectionConfiguration` now takes in a `TapToPayReaderListener` parameter, replacing `ReaderReconnectionListener`. 
+  - For Tap to Pay readers, the `TapToPayConnectionConfiguration` now takes in a `TapToPayReaderListener` parameter, replacing `ReaderReconnectionListener`.
   - For smart readers, `InternetConnectionConfiguration` now takes in an [`InternetReaderListener`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-internet-reader-listener/index.html) parameter, which will alert your integration of events such as reader disconnects.
   - For [Apps on devices](/terminal/features/apps-on-devices/overview#pos-stripe-device) in handoff mode, [`HandoffReaderListener`]((https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.callable/-handoff-reader-listener/index.html)) has been removed from the old `connectHandoffReader` method as a parameter, and moved into the `HandoffConnectionConfiguration` object.
 - Update: [Auto reconnect on unexpected disconnect](https://docs.stripe.com/terminal/payments/connect-reader?terminal-sdk-platform=android&reader-type=tap-to-pay#automatically-attempt-reconnection) is now enabled by default for mobile readers and Tap to Pay readers.
@@ -85,13 +97,15 @@ Add support for apps built with `targetSdkVersion = 35` targeting Android 15 dev
 - Update: in `ReaderSoftwareUpdate`, rename `UpdateTimeEstimate` to [`UpdateDurationEstimate`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-reader-software-update/-update-duration-estimate/index.html), and `timeEstimate` to [`durationEstimate`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-reader-software-update/duration-estimate.html).
 - Update: Converted `java.util.Date` references to timestamps in milliseconds for the following fields: `ReaderSoftwareUpdate::requiredAt`, `OfflineDetails::storedAt` and `OfflineSetupIntentDetails::storedAt`.
 
-### Tap to Pay 
+### Tap to Pay
 
 - **Update**: The Maven coordinates for the Tap to Pay on Android feature have changed to `com.stripe:stripeterminal-taptopay:4.0.0`. Please update your build dependencies to point to the new artifact name. The old one will no longer be updated.
 - Update: SafetyNet Attestation API has been removed and replaced with Play Integrity API. Fixes [issue 458](https://github.com/stripe/stripe-terminal-android/issues/458).
 - Update: `TapToPayConnectionConfiguration` now takes in a `TapToPayReaderListener` parameter. This listener inherits events from both `ReaderReconnectionListener` and `ReaderDisconnectionListener`, providing a unified interface for handling reader events.
 - Update: The `collectPaymentMethod` and `collectSetupIntentPaymentMethod` now time out after 60 seconds for Tap to Pay on Android transactions. If a timeout occurs, a [`TerminalException`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-exception/index.html) will be raised with the error code [`CARD_READ_TIMED_OUT`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/-c-a-r-d_-r-e-a-d_-t-i-m-e-d_-o-u-t/index.html)
 - Update: When PIN collection is requested for a payment, a [`TerminalException`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-exception/index.html) will be raised with error code [`FEATURE_NOT_ENABLED_ON_ACCOUNT`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/-f-e-a-t-u-r-e_-n-o-t_-e-n-a-b-l-e-d_-o-n_-a-c-c-o-u-n-t/index.html) instead of [`DECLINED_BY_STRIPE_API`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.models/-terminal-error-code/-d-e-c-l-i-n-e-d_-b-y_-s-t-r-i-p-e_-a-p-i/index.html) with an [`ONLINE_OR_OFFLINE_PIN_REQUIRED`](https://docs.stripe.com/declines/codes#:~:text=online_or_offline_pin_required) [`ApiError`](https://stripe.dev/stripe-terminal-android/external/com.stripe.stripeterminal.external.api/-api-error/index.html?query=data%20class%20ApiError(error:%20InnerError)%20:%20Serializable).
+- Update: Reduce the amount of time [`Terminal::connectReader`](https://stripe.dev/stripe-terminal-android/core/com.stripe.stripeterminal/-terminal/connect-reader.html) takes to complete attestation.
+- Update: Improve acceptance of some cards that previously would have displayed "Please use another card"
 
 - Update: "Local Mobile" has been renamed to "Tap To Pay" in all function names and error codes to align with Stripe branding:
   - `LocalMobileDiscoveryConfiguration` has been renamed to `TapToPayDiscoveryConfiguration`.

Example/javaapp/build.gradle.kts

@@ -36,7 +36,7 @@ android {
 
 val androidxLifecycleVersion = "2.6.2"
 val retrofitVersion = "2.11.0"
-val stripeTerminalVersion = "4.1.0"
+val stripeTerminalVersion = "4.2.0"
 
 dependencies {
     implementation("com.google.android.material:material:1.11.0")

Example/javaapp/src/main/java/com/stripe/example/javaapp/MainActivity.java

@@ -99,7 +99,7 @@ public void onCancelDiscovery() {
     }
 
     @Override
-    public void onRequestChangeLocation() {
+    public void onRequestLocationSelection() {
         navigateTo(
                 LocationSelectionFragment.TAG,
                 LocationSelectionFragment.newInstance(),
@@ -108,16 +108,24 @@ public void onRequestChangeLocation() {
         );
     }
 
+    @Override
+    public void onCancelLocationSelection() {
+        getSupportFragmentManager().popBackStackImmediate();
+    }
+
     @Override
     public void onRequestCreateLocation() {
         navigateTo(LocationCreateFragment.TAG, LocationCreateFragment.newInstance(), false, true);
     }
 
+    @Override
+    public void onCancelCreateLocation() {
+        getSupportFragmentManager().popBackStackImmediate();
+    }
+
     @Override
     public void onLocationCreated() {
         getSupportFragmentManager().popBackStackImmediate();
-        List<Fragment> fragments = getSupportFragmentManager().getFragments();
-        ((LocationSelectionFragment) fragments.get(fragments.size() - 1)).reload();
     }
 
     /**
@@ -349,6 +357,10 @@ public void onLocationCleared() {
      * ReaderReconnectionListener implementation.
      */
     @Override
+    public void onReaderReconnectStarted(@NonNull Reader reader, @NonNull Cancelable cancelReconnect, @NonNull DisconnectReason reason) {
+        Log.d("MainActivity", "Reconnection to reader " + reader.getId() + " started!");
+    }
+    @Override
     public void onReaderReconnectSucceeded(@NonNull Reader reader) {
         Log.d("MainActivity", "Reader " + reader.getId() + " reconnected successfully!");
     }

Example/javaapp/src/main/java/com/stripe/example/javaapp/NavigationListener.java

@@ -72,13 +72,23 @@ public interface NavigationListener {
     /**
      * Notify the `Activity` that the user has requested to change the location.
      */
-    void onRequestChangeLocation();
+    void onRequestLocationSelection();
+
+    /**
+     * Notify the `Activity` that the location selection flow has been canceled.
+     */
+    void onCancelLocationSelection();
 
     /**
      * Notify the `Activity` that the user has requested to add a location.
      */
     void onRequestCreateLocation();
 
+    /**
+     * Notify the `Activity` that the create location flow has been canceled.
+     */
+    void onCancelCreateLocation();
+
     /**
      * Notify the `Activity` that the user has finished creating a location.
      */

Example/javaapp/src/main/java/com/stripe/example/javaapp/fragment/location/LocationCreateFragment.java

@@ -12,6 +12,7 @@
 import androidx.fragment.app.Fragment;
 
 import com.google.android.material.snackbar.Snackbar;
+import com.stripe.example.javaapp.MainActivity;
 import com.stripe.example.javaapp.NavigationListener;
 import com.stripe.example.javaapp.R;
 import com.stripe.example.javaapp.network.ApiClient;
@@ -30,7 +31,10 @@ public static LocationCreateFragment newInstance() {
     public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) {
         View view = inflater.inflate(R.layout.fragment_location_create, container, false);
         binding = FragmentLocationCreateBinding.bind(view);
-        binding.locationCreateSubmit.setOnClickListener((View.OnClickListener) v -> onSubmit());
+        binding.locationCreateSubmit.setOnClickListener(v -> onSubmit());
+        binding.locationCreateCancelButton.setOnClickListener(v ->
+                ((MainActivity) requireActivity()).onCancelCreateLocation()
+        );
 
         return view;
     }
@@ -39,18 +43,18 @@ private void onSubmit() {
         try {
             ApiClient.createLocation(
                     requireValue(binding.locationCreateDisplayNameInput),
-                    getValue(binding.locationCreateAddressCityInput),
-                    requireValue(binding.locationCreateAddressCountryInput),
-                    getValue(binding.locationCreateAddressLine1Input),
+                    requireValue(binding.locationCreateAddressLine1Input),
                     getValue(binding.locationCreateAddressLine2Input),
+                    getValue(binding.locationCreateAddressCityInput),
                     getValue(binding.locationCreateAddressPostalInput),
-                    getValue(binding.locationCreateAddressStateInput)
+                    getValue(binding.locationCreateAddressStateInput),
+                    requireValue(binding.locationCreateAddressCountryInput)
             );
-            ((NavigationListener) getActivity()).onLocationCreated();
+            ((NavigationListener) requireActivity()).onLocationCreated();
         } catch (IllegalStateException e) {
             Log.d(TAG, "Missing required input");
         } catch (Throwable e) {
-            Snackbar.make(getView(), e.getMessage() == null ? "Unknown Error" : e.getMessage(), Snackbar.LENGTH_LONG).show();
+            Snackbar.make(requireView(), e.getMessage() == null ? "Unknown Error" : e.getMessage(), Snackbar.LENGTH_LONG).show();
         }
     }
 
@@ -61,7 +65,7 @@ public void onDestroyView() {
     }
 
     private String requireValue(EditText receiver) {
-        if (receiver.getText() == null || receiver.getText().toString().trim().equals("")) {
+        if (receiver.getText() == null || receiver.getText().toString().trim().isEmpty()) {
             receiver.setError(getResources().getString(R.string.field_required));
             throw new IllegalStateException();
         }
@@ -71,7 +75,7 @@ private String requireValue(EditText receiver) {
 
     @Nullable
     private String getValue(EditText receiver) {
-        if (receiver.getText() == null || receiver.getText().toString().trim().equals("")) {
+        if (receiver.getText() == null || receiver.getText().toString().trim().isEmpty()) {
             return null;
         }
         return receiver.getText().toString();

Example/javaapp/src/main/java/com/stripe/example/javaapp/fragment/location/LocationSelectionFragment.java

@@ -12,6 +12,8 @@
 import androidx.lifecycle.ViewModelProvider;
 import androidx.recyclerview.widget.LinearLayoutManager;
 
+import com.stripe.example.javaapp.MainActivity;
+import com.stripe.example.javaapp.NavigationListener;
 import com.stripe.example.javaapp.R;
 import com.stripe.example.javaapp.recyclerview.InfiniteScrollListener;
 import com.stripe.example.javaapp.viewmodel.LocationSelectionViewModel;
@@ -31,6 +33,12 @@ public void onCreate(@Nullable Bundle savedInstanceState) {
         viewModel = new ViewModelProvider(this).get(LocationSelectionViewModel.class);
     }
 
+    @Override
+    public void onResume() {
+        super.onResume();
+        viewModel.reload();
+    }
+
     @Nullable
     @Override
     public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup container, @Nullable Bundle savedInstanceState) {
@@ -43,17 +51,25 @@ public View onCreateView(@NonNull LayoutInflater inflater, @Nullable ViewGroup c
         binding.locationSelectionList.addOnScrollListener(new InfiniteScrollListener(layoutManager, () -> viewModel.loadMoreLocations()));
         binding.locationSelectionList.setAdapter(adapter);
         binding.locationSelectionToolbar.inflateMenu(R.menu.location_selection);
+        binding.locationSelectionToolbar.setOnMenuItemClickListener(item -> {
+            if (item.getItemId() == R.id.menu_location_selection_add) {
+                ((NavigationListener) requireActivity()).onRequestCreateLocation();
+                return true;
+            } else {
+                return false;
+            }
+        });
 
-        viewModel.listState.observe(getViewLifecycleOwner(), (state) -> adapter.setLocationListState(state));
+        binding.locationSelectionCancelButton.setOnClickListener(v ->
+                ((MainActivity) requireActivity()).onCancelLocationSelection()
+        );
+
+        viewModel.listState.observe(getViewLifecycleOwner(), adapter::setLocationListState);
         viewModel.error.observe(getViewLifecycleOwner(), (error) -> Toast.makeText(getActivity(), error.getErrorMessage(), Toast.LENGTH_LONG).show());
 
         return view;
     }
 
-    public void reload() {
-        viewModel.reload();
-    }
-
     public static LocationSelectionFragment newInstance() {
         return new LocationSelectionFragment();
     }

Example/javaapp/src/main/java/com/stripe/example/javaapp/network/ApiClient.java

@@ -2,14 +2,11 @@
 
 import com.stripe.example.javaapp.BuildConfig;
 import com.stripe.example.javaapp.model.ConnectionToken;
-import com.stripe.example.javaapp.model.PaymentIntentCreationResponse;
 import com.stripe.stripeterminal.external.models.ConnectionTokenException;
 
 import org.jetbrains.annotations.NotNull;
 
 import java.io.IOException;
-import java.util.HashMap;
-import java.util.Map;
 
 import okhttp3.OkHttpClient;
 import retrofit2.Callback;
@@ -42,17 +39,31 @@ public static String createConnectionToken() throws ConnectionTokenException {
         }
     }
 
-    /** @noinspection unused*/
     public static void createLocation(
-            String displayName,
-            String city,
-            String country,
-            String line1,
+            @NotNull String displayName,
+            @NotNull String line1,
             String line2,
+            String city,
             String postalCode,
-            String state
-    ) {
-        // TODO: Call backend to create location
+            String state,
+            @NotNull String country
+    ) throws Exception {
+        try {
+            final Response<Void> result = mService.createLocation(
+                    displayName,
+                    line1,
+                    line2,
+                    city,
+                    postalCode,
+                    state,
+                    country
+            ).execute();
+            if (!result.isSuccessful()) {
+                throw new Exception("Creating location failed");
+            }
+        } catch (IOException e) {
+            throw new Exception("Creating location failed", e);
+        }
     }
 
     public static void capturePaymentIntent(@NotNull String id) throws IOException {