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.
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.
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
true, the device returns the most recent message.
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
setSendLastMessage set to
true), the device will resend the
SaleResponse which provides the POS the data needed to clear the pending payment.
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
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);
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.
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.
STARTscreen 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.
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 state is a very uncommon occurrence. It accounts for all current internal states, and is unlikely to appear.
Updated about 1 month ago