Getting Started with CloverConnector

The CloverConnector SDK

The CloverConnector SDK provides a consolidated asynchronous interface for interacting with a Clover Mini as a customer facing payment device. ICloverConnector provides the calling interface for the CloverConnector SDK and ICloverConnectorListener provides the listener, or callback, interface for the CloverConnector SDK.

 

Note

The default and preferred method for communicating with the Clover Mini on Windows and Android is USB. The default method for communicating with the Mini from a browser via our CloverConnector Browser API is by using WebSockets through the Clover cloud services.

Connectivity

USB is the preferred method of communication with the device, and the SDK provides a USB connector and USB drivers for the Clover Mini. The USB connector requires the USB Pay Display app to communicate with a Clover Mini.

Overview

ICloverConnector provides the callable interface for interacting with a Clover Mini. Some of those capabilities include:

  • Processing a final sale, tip adjustable authorization or verifying a pre-authorization
  • Vaulting cards for future payments
  • Processing manual/naked refunds
  • Processing payment refunds and voids
  • Adjusting tip amounts for authorizations
  • Capturing payments for pre-authorizations
  • Displaying order details
  • Printing images or text
  • Requesting batch closeouts

ICloverConnectorListener provides the callback interface that can be registered with the ICloverConnector to receive responses or status updates from the Clover Mini. Some of the events that will callback on ICloverConnectorListener include:

  • Response to a Sale, Auth or Pre-Auth
  • Response to a VaultCard
  • Response to a manual/naked refund
  • Response to payment refunds and voids
  • Response to a TipAdjustAuth or CapturePreAuth
  • UIEvent messages as Clover Mini changes screens, with potential action options correlating to options on Clover Mini i.e. “Cancel”, “Ok”, “Done”, “Yes”, “No”, etc.
  • Closeout processing events
  • Device events when the device disconnects, connects and is ready

ICloverConnector

Initialize

Status
Returns the status and triggers a callback (OnDeviceDisconnected, OnDeviceConnected or OnDeviceReady) for the current status
InitializeConnection
Starts communication with the device. This is called after the connector is created and listeners are added to the connector.
void InitializeConnection();
SDKInfo
Gets the version information for this installation of the SDK. The return value is formatted as SDKName:Version.
AddCloverConnectorListener
Adds a CloverConnector listener.
void AddCloverConnectorListener(ICloverConnectorListener connectorListener);
RemoveCloverConnectorListener
Removes a CloverConnector listener.
void RemoveCloverConnectorListener(ICloverConnectorListener connectorListener);
Dispose
Dispose of a connection.

Sale, Auth & PreAuth

There are three transaction models, or flows, currently supported:

Sale
A Sale transaction is final and the amount cannot be adjusted.

This is how to get a sale up and running now.

Note

This approach is not feature-rich, so you may choose to modify this approach.

  1. Define an ICloverConnectorListener to listen when the device is ready and listen for the callback when the sale finishes
  2. Initialize an ICloverConnector
  3. Register your ICloverConnector listener
  4. Create SaleRequest and call Sale
// 1. Define an ICloverConnectorListener 
class MyCloverConnectorListener : DefaultCloverConnectorListener
{
   public MyCloverConnectorListener(ICloverConnector cc) : base(cc) {
   }

   // Override OnSaleResponse to get the callback from the device for the Sale call
   public override OnSaleResponse(SaleResponse response) {
      if(response.code == ResultStatus.SUCCESS) {
         // response.payment has the payment object
      } else if (response.code == ResultStatus.CANCEL) {
         // handle cancel
	} else if (response.code == ResultStatus.FAIL) {
	   // handle fail
	}
   }
}

// 2. Initialize connector
ICloverConnector cloverConnector = new CloverConnector(USBCloverDeviceConfiguration(null, "com.yourcompany.appid", false, 0))
// 3. Register ICloverConnectorListener 
ICloverConnectorListener myListener = new MyCloverConnectorListener(cloverConnector)
cloverConnector.AddCloverConnectorListener(myListener);
...
if (myListener.isReady) {
   // 4. Create a SaleRequest and call Sale
   SaleRequest request = new SaleRequest();
   request.amount = 2318; // $23.18
   request.externalPaymentId = "KAD46SD3SFR7P";
   cloverConnector.Sale(request);
}
Auth
An Auth transaction is finalized during the batch closeout, but can be tip adjusted. This is a normal model for a restaurant that adjusts the charged amount based on tips after a card is charged.

Note

An Auth’s tip can be adjusted via the TipAdjustAuth call, and can be adjusted until the batch closeout is processed. Closeout can be initiated either on a schedule or from a manual request.

void Auth(AuthRequest request);
PreAuth
A PreAuth is a validation that a card can authorize a specific amount, but won’t finalize the payment unless the Pre-Auth is captured. This is a normal model for a hotel that takes a card for a deposit, but doesn’t charge the card unless needed.

Note

A Pre-Auth can be captured via the CapturePreAuth call passing in an amount and tipAmount. The payment will not be finalized until the batch closeout is processed.

A captured Pre-Auth is effectively an Auth, so it can be tip adjusted until the batch closeout is processed.

void PreAuth(PreAuthRequest request);

Signatures

AcceptSignature
AcceptSignature can be called to accept the signature for a payment. Signatures can be captured either electronically on-screen or on the receipt.
void AcceptSignature(VerifySignatureRequest request);
RejectSignature
RejectSignature can be called to reject a customer’s signature.
void RejectSignature(VerifySignatureRequest request);

Vaulting Cards

VaultCard
VaultCard will allow a payment token for a Card to be retrieved for future use in Sale or Auth calls (If the merchant account is configured to return payment tokens).

Note

Please contact merchant services if you don’t have this capability.

void VaultCard(int? CardEntryMethods);

Manual Refund

ManualRefund
ManualRefund will allow money to be credited to a cardholder’s account. This differs from a PaymentRefund in that a ManualRefund can be made without a previous payment.
void ManualRefund(ManualRefundRequest request);

Adjusting Payments

CapturePreAuth
CapturePreAuth marks a pre-auth payment for capture by a closeout process. After a pre-auth is captured, it is effectively the same as an auth payment.
void CapturePreAuth(CapturePreAuthRequest request);
RefundPayment
RefundPayment allows a payment’s full amount, or partial amount, to be refunded.
void RefundPayment(RefundPaymentRequest request);
TipAdjustAuth
TipAdjustAuth allows an auth transaction to have its tip value adjusted until the auth payment has been finalized via a closeout.
void TipAdjustAuth(TipAdjustAuthRequest request);
VoidPayment
VoidPayment voids a payment. If a void can’t be performed, a refund of the payment may be executed.
void VoidPayment(VoidPaymentRequest request);
Closeout
Closeout will send a request to the server to close out the current batch of open payments. Open payments include Auth payments and Captured PreAuth payments.

Note

Note: Non-captured PreAuth payments will not be processed.

void Closeout(CloseoutRequest request);

Display Options for Device

ShowDisplayOrder
ShowDisplayOrder will display order details and line items on the Mini.
void ShowDisplayOrder(DisplayOrder order);
ShowMessage
ShowMessage will display a string based message on the display.
void ShowMessage(string message);
ShowWelcomeScreen
ShowWelcomeScreen will display the default welcome screen, including a merchant logo if one is configured in the merchant settings.
ShowThankYouScreen
ShowThankYouScreen will display a standard Thank You For Visiting <Merchant Name> screen.
Cancel
Cancel will send a cancel request to the current screen. For example, a cancel request sent to the “orders” screen will clear state and revert back to the welcome screen.

Some screens cannot be cancelled. For example, the payment screen cannot be cancelled while a payment authorization is occurring.

ResetDevice
ResetDevice will reset the state of the Clover Mini and reset all internal state.

Note

This should be a last resort if the mini is stuck, as any current transaction information may be lost.

DisplayPaymentReceiptOptions
Show the customer facing receipt option screen for the specified payment. This will display the receipt screen again, allowing a receipt to be reprinted, emailed, etc. for payments.
void DisplayPaymentReceiptOptions(String orderId, String paymentId);
LineItemAddedToDisplayOrder
Notify the device of a DisplayLineItem being added to a DisplayOrder
void LineItemAddedToDisplayOrder(DisplayOrder order, DisplayLineItem lineItem);
LineItemRemovedFromDisplayOrder
Notify the device of a DisplayLineItem being removed from a DisplayOrder
void LineItemRemovedFromDisplayOrder(DisplayOrder order, DisplayLineItem lineItem);
DiscountAddedToDisplayOrder
Notify device of a discount being added to the order.

Note: This is independent of a discount being added to a display line item.

void DiscountAddedToDisplayOrder(DisplayOrder order, DisplayDiscount discount);
DiscountRemovedFromDisplayOrder
Notify the device that a discount was removed from the order.

Note: This is independent of a discount being removed from a display line item.

void DiscountRemovedFromDisplayOrder(DisplayOrder order, DisplayDiscount discount);
RemoveDisplayOrder
Remove the DisplayOrder from the device.
void RemoveDisplayOrder(DisplayOrder order);

Printing

PrintText
PrintText will print the list of strings passed in, without any special formatting, through the printer that is built into the Clover Mini.

{

   “Messages”:[

       “Line 1”,

       “Line 2”,

       “Line 3”

       ]

}

void PrintText(List messages);
PrintImage
PrintImage will print the image passed in to the printer that is built into the Clover Mini.
void PrintImage(Bitmap bitmap);
PrintImageFromURL
Print an image from a url through the printer that is built into the Clover Mini.
void PrintImageFromURL(String ImgURL);

External Hardware

OpenCashDrawer
OpenCashDrawer opens the cash drawer.
void OpenCashDrawer(String reason);

Screen Management for Your POS

You may wish to reflect the state of the Clover Mini on your own POS, e.g. show “Customer is tipping” when the mini is on the tip screen in the payment flow. The methods below provide a way for you to receive messages about the state of the Mini through the SDK.

InvokeInputOption
InvokeInputOption will select an option on the screen on behalf of the user. InputOptions for a screen are sent as part of CloverDeviceEvent in onDeviceActivityStart. These input options can be sent back to the device via InvokeInputOption.
Invoke the InputOption as sent in the DeviceActivityStart callback
OnDeviceActivityStart
OnDeviceActivityStart will be called when a screen or an activity changes on the Mini. The CloverDeviceEvent passed in will contain an event type, a description and a list of available InputOptions.
OnDeviceActivityEnd
OnDeviceActivityEnd will be called when leaving a screen or an activity on the Mini. The CloverDeviceEvent passed in will contain an event type and description. Note: The start and end events are not guaranteed to process in order, so the event type should be used to make sure the start and end events are paired.

ICloverConnectorListener

Transaction Responses

Transaction Responses will have a boolean Success property and an enum Result property that provides some information on the success flag.

OnSaleResponse
OnSaleResponse will be called, one or more times, at the completion of a sale transaction request. If it is successful, the response will also have the payment object. The payment object can be the full amount or partial amount of the sale request.

Note

A sale transaction my come back as a tip adjustable auth, depending on the payment gateway. The SaleResponse has a boolean isSale to determine if it is final or will be finalized during closeout.

OnAuthResponse
OnAuthResponse will be called, one or more times, at the completion of an auth transaction request, with the same results as a SaleResponse.

Note

An auth transaction may come back as a final sale, depending on the payment gateway. The AuthResponse has a boolean isAuth to determine if it can still be tip adjusted.

OnPreAuthResponse
OnPreAuthResponse will be called, one or more times, at the completion of a pre-auth transaction request, with the same results as a SaleResponse.

Note

The isPreAuth boolean on the PreAuthResponse verifies if CapturePreAuth can be called for the returned payment.

OnManualRefundResponse
OnManualRefundResponse will be called at the completion of a manual refund request. If successful, the ManualRefundResponse will have a Credit object associated with the relevant payment information.

Signature Response

OnVerifySignatureRequest
OnVerifySignatureRequest will be called, passing in the Payment and Signature, if the user provides an on-screen signature that needs to be accepted or rejected for a payment.

Adjusted Payment Response

Adjust payment responses, like transaction responses, will have a boolean Success property and Result property.

OnTipAdjustAuthResponse
OnTipAdjustAuthResponse will be called after a tip adjust request and contains the tipAmount and paymentId if successful.
OnCapturePreAuthResponse
OnCapturePreAuthResponse will be called after a capture pre-auth request and contains the new amount, tipAmount and paymentId if successful.
OnRefundPaymentResponse
OnRefundPaymentResponse will be called after a refund payment request and contains the Refund if successful. The Refund contains the original paymentId as reference.
OnVoidPaymentResponse
OnVoidPaymentResponse will be called after a void payment request and contains the voided paymentId if successful.
OnCloseoutResponse
OnCloseoutResponse can get called multiple times at various stages. The Reason will contain information about what was successful or what failed.

Vaulted Card Response

OnVaultCardResponse
OnVaultCardResponse will be called at the completion of a vault card request, with a boolean success property. If successful, the response will contain a payment with a token value unique for the card and merchant that can be used for future Sale or Auth requests.

Clover Mini Events

OnDeviceConnected
OnDeviceConnected will be called if the device is connected, but not ready to communicate
OnDeviceDisconnected
OnDeviceDisconnected will be called if the device is not available
OnDeviceReady
OnDeviceReady will be called once the device is connected and ready to communicate. A MerchantInfo object will be passed in with various information about the device, merchant and some potential merchant payment configuration data like supportsAuths or supportsVaultCards.
OnDeviceActivityStart
OnDeviceActivityStart will be called when a screen or an activity changes on the Mini. The CloverDeviceEvent passed in will contain an event type, a description and a list of available InputOptions.
OnDeviceActivityEnd
OnDeviceActivityEnd will be called when leaving a screen or an activity on the Mini. The CloverDeviceEvent passed in will contain an event type and description. Note: The start and end events are not guaranteed to process in order, so the event type should be used to make sure the start and end events are paired.
OnDeviceError
OnDeviceError will be called when an error occurs when trying to send messages to the device.
OnTipAdded
OnTipAdded will be called when a tip is added on the mini screen.