[Woo POS] Handle external reader disconnection gracefully in Point of Sale

[joshheald]

Closes: #13738
Closes: #13876
Merge after: #14994

Description

This PR prevents the "Connect your reader" view from showing on TotalsView unless the payment is still to be taken. (N.B. the reader connection status is still shown, it's the large CTA view which we don't want to show as it replaces other more relevant detail, and can lead to confusion.)

Previously, it was possible to see the Connect your reader message in inappropriate parts of the flow, where it could cause confusion.

For example, if we were on the Payment Successful, or other payment related views, and lost connection to the card reader (from battery drain, switched off, bluetooth disabled,) then it would show Connect your reader.

After connecting, the POS would be in a strange state, and it could lead the merchant to thinking a new order was paid for when actually it was the previous order.

Steps to reproduce

Processing payment

1. Launch the app and go to POS
2. Connect your card reader
3. Go to checkout
4. Open control centre and be ready to disable bluetooth
5. Tap your card, then immediately disable bluetooth
6. Close control centre
7. Observe that the payment continues as normal, and the connect your reader prompt isn't shown
8. Check in the Orders tab or WP-admin; observe that the order is paid for

Payment successful

1. Launch the app and go to POS
2. Connect your card reader
3. Checkout, and complete the payment
4. When you see payment successful, turn off your card reader
5. Observe that the POS remains on the payment successful screen.
6. Tap New Order
7. Observe that you can complete a new order and take payment as normal, without being told that the order is complete even when you've not tapped the card.

Testing information

It's worthwhile testing various payment flows with the reader connected and disconnected in different ways.

I tested using an iPad Air running iOS 17.7.

I tested cash and card payments, and I tested disabling bluetooth, turning off the reader, and taking the reader out of range.

Note that there's a pre-existing separate issue where if you get an error after disabling bluetooth, the Try another payment button doesn't work and you have to exit POS. I'm not sure what causes that, but it's not this PR, and I'm going to tackle it separately.

Screenshots

Before

(note that to test this you'll need to use the branch issue/14992-update-connection-status-when-reader-turned-off) – before this, the issue was hidden by the card reader disconnecting not being reported in POS.

before.fixes.to.connect.your.reader.view.mp4

After

after.disconnection.improvements.mp4

---

• I have considered if this change warrants user-facing release notes and have added them to RELEASE-NOTES.txt if necessary.

Reviewer (or Author, in the case of optional code reviews):

Please make sure these conditions are met before approving the PR, or request changes if the PR needs improvement:

• The PR is small and has a clear, single focus, or a valid explanation is provided in the description. If needed, please request to split it into smaller PRs.
• Ensure Adequate Unit Test Coverage: The changes are reasonably covered by unit tests or an explanation is provided in the PR description.
• Manual Testing: The author listed all the tests they ran, including smoke tests when needed (e.g., for refactorings). The reviewer confirmed that the PR works as expected on all devices (phone/tablet) and no regressions are added.

[wpmobilebot]

📲 You can test the changes from this Pull Request in WooCommerce iOS by scanning the QR code below to install the corresponding build.

	App Name	WooCommerce iOS
	Build Number	pr14995-a5891df
	Version	21.5
	Bundle ID	com.automattic.alpha.woocommerce
	Commit	a5891df
	App Center Build	WooCommerce - Prototype Builds #12716

Automatticians: You can use our internal self-serve MC tool to give yourself access to App Center if needed.

[dangermattic]

	1 Warning
⚠️	This PR is assigned to the milestone 21.6. This milestone is due in less than 2 days. Please make sure to get it merged by then or assign it to a milestone with a later deadline.

Generated by 🚫 Danger

[staskus]

Thanks, the fix works well and the disconnected message is not shown if the reader is disconnected in most of the states.

I kept finding weird issues though:

1. Disconnecting never finishes

If I connect the reader, if I make the payment and disconnect. The disconnecting state only disappears after exiting and reopening the POS. Card reader remains in a connected state.

disconnection.never.finishes.until.reopening.pos.MP4

2. I was able to reproduce instant-success

It's only reproducible after getting POS in a weird state after disconnecting the reader during the payment. The only way out is to kill and relaunch the Woo app. But it's not consistently reproducible to me. Likely need to address it in the scope of #14593 (p1737620243820579-slack-C070SJRA8DP).

instant.success.MP4

[staskus]

Good use of arguments 👍

[joshheald]

Thanks for the review and the related findings...

1. Disconnecting never finishes

If I connect the reader, if I make the payment and disconnect. The disconnecting state only disappears after exiting and reopening the POS. Card reader remains in a connected state.

I've tried this a bunch of times now and can't repro it.

We set the disconnecting state just by you tapping the button, and then assume it'll be set to .disconnected when the flow completes. I'm guessing there's somewhere that it can fail to disconnect without us updating the state, which is why the reader stays connected.

The only place I can see where we wouldn't get a callback one way or another though, is if the Stripe Terminal SDK doesn't ever call our disconnect completion block, passed in StripeCardReaderService.disconnect()

2. I was able to reproduce instant-success

It's only reproducible after getting POS in a weird state after disconnecting the reader during the payment. The only way out is to kill and relaunch the Woo app. But it's not consistently reproducible to me. Likely need to address it in the scope of #14593 (p1737620243820579-slack-C070SJRA8DP).
instant.success.MP4

This is still strange. It looks to me like the deliberate handling of an order which already has datePaid != nil – intended to stop people double-charging for the same order.

It could perhaps point to us not correctly resetting an order after it's paid.

[staskus]

This is still strange. It looks to me like the deliberate handling of an order which already has datePaid != nil – intended to stop people double-charging for the same order. It could perhaps point to us not correctly resetting an order after it's paid.

I'll check it today more closely in the scope of [Woo POS] Checkout screen occasionally gets stuck in Preparing Card for Payment state after card reader connection · Issue #14593 · woocommerce/woocommerce-ios

I even managed to get an actual successful $0.01 payment screen although it doesn't show up in orders.

ScreenRecording_01-30-2025.11-36-35_1.MP4