The documentation comment on the PaymentsClient.isReadyToPay(request:) method lists the following check as one of the minimum requirements to finish a transaction using the Google Pay API:
User either has or can add a card in flow according to the specifications given in the IsReadyToPayRequest.
It's not entirely clear what "can add a card in flow" means and it's not entirely clear what parts of IsReadyToPayRequest determine whether a user "can add a card in flow".
My guess is that (1) "can add a card in flow" means the Google Pay card selection sheet will show a button that allows the user to add a card to their account, and (2) setting the IsReadyToPayRequest.existingPaymentMethodRequired property to false is what communicates to Google Pay that a user "can add a card in flow".
Assuming the above two guesses are correct (please correct me if they're not 🙏): Why would an app ever want to set the IsReadyToPayRequest.existingPaymentMethodRequired property to true and thereby prohibit a user from adding a card in flow?
Your assumptions are correct.
Setting IsReadyToPayRequest.existingPaymentMethodRequired to true allows merchants to come up with different UX patterns. They could, for example, show the Google Pay button on top of a payment method list because the user is ready to pay and therefore only a few clicks are needed to complete the purchase.
On the web, in combination with the createButton() API (which is able to display the type and last four digits of the user's most-recently used card), this could result in higher click-through rates.