Connection recovery is a complex subject which requires thought and planning that may be unique to your POS integration. You need to account for your POS becoming disconnected from the Clover device and POS crashes, as well as other error scenarios. This section discusses some of the challenges and recommendations for handling recovery and is not meant as a strict guideline.

📘

NOTE

The example apps provided on GitHub are simple examples designed to show how the API works. They are not complete or robust POS applications, particularly with respect to recovering from connection issues. Because each merchant requires different features from their POS, you are encouraged to plan for and design recovery capabilities that will allow the merchant to operate the integrated system reliably.

Confirm device state

The status of the POS-to-Clover connection can be checked before sending (or resending) a transaction request. Prior to making a new payment, you can use CloverConnector#retrieveDeviceStatus to verify that the device is ready to process a transaction. If setSendLastMessage is true, the device returns the most recent message.

Understand response values

The retrieveDeviceStatus call’s response (ICloverConnectorListener.onRetrieveDeviceStatusResponse) will return a state of BUSY if the Clover device is in a payment flow. The response payload has a flag (setSendLastMessage) which, if set to true, returns the last message that the Clover device sent. In many cases, setting this flag to true is enough to recover. For example, the device could disconnect just before a sale response is sent. Upon re-establishing a connection (and utilizing retrieveDeviceStatus with setSendLastMessage set to true), the device will resend the SaleResponse which provides the POS the data needed to clear the pending payment.

Idle

The idle state indicates that the Clover device is connected and ready to process a transaction. Your app should only attempt to process a payment when the response is IDLE.

Waiting on the customer

When the Clover device needs the customer to select an option on screen, the WAITING_ON_CUSTOMER state is returned (including the ExternalPaymentId value of the last request sent to the device). This occurs on the Add a Tip and Need a Receipt? screens. This state can be cleared by invoking the cancel input with the CloverConnector. The response object from

const inputOption = new clover.remotepay.InputOption();
inputOption.setKeyPress(clover.remotepay.KeyPress.ESC);
cloverConnector.invokeInputOption(inputOption);

Waiting for the POS

The device is waiting for the POS to take action. This state is commonly seen when the POS needs to decide whether to accept or reject a payment in response to a challenge.

Busy

When the Clover device is in the process of taking a payment, the BUSY state is returned. The response includes the ExternalPaymentId value of the last request sent to the device.

Multiple cancel calls may be needed to return to the IDLE state. For example, if a chip card is inserted, a cancel call will not change the state until the card is removed.

📘

NOTE

From the START screen until the device returns to IDLE, a payment is in progress. If you exit the payment flow by tapping the four corners of the screen, the payment will be voided and will not appear in the transactions list.

Disconnected

If the POS and Clover device are not connected, a The Clover device is not connected response is returned. This can occur for a number of different reasons depending on the type of connection being used:

• Pay Display app is not running on the device or running in the background after being exited manually
• USB cable is not connected (USB Pay Display)
• POS or Clover device is not connected to the network (Secure Network or Cloud Pay Display)

Unknown

The UNKNOWN state is a very uncommon occurrence. It accounts for all current internal states, and is unlikely to appear.