Getting started with Clover Connector

The Clover Connector SDK

The Clover Connector SDK provides a consolidated asynchronous interface that enables your point-of-sale (POS) software to interact with Clover’s customer-facing payment devices.

ICloverConnector provides the callable interface. Some of its capabilities include:

  • Processing cards as:
    • Sales – Fixed-amount payments
    • Auths – Tip-adjustable payments
    • PreAuths – Pre-authorizations for a specific amount that can be updated before finalizing payment
  • Vaulting card tokens for future payments
  • Processing payment refunds and voids
  • Displaying order details
  • Printing images and text
  • Requesting batch closeouts
  • Requesting device and payment status
  • Starting and communicating with Custom Activities

ICloverConnectorListener provides the callback interface. Some of the events that will call back on ICloverConnectorListener include:

  • Responses to sales, authorizations, and pre-authorizations
  • Responses to card vaulting requests
  • Responses to payment refunds and voids
  • Responses to tip amount adjustments and captured payments for pre-authorizations
  • UI event messages sent as the Clover device changes screens, along with appropriate actions correlating to options on the device (e.g., Cancel, Ok, Done, Yes, No, etc.)
  • Closeout processing events
  • Requests to confirm payments or signatures
  • Events sent when the device disconnects, connects, or is ready
  • Responses to device and payment status requests
  • Responses or messages from Custom Activities

This tutorial will guide you through the process of connecting to your Clover device, initiating a Sale request, and handling the response to your Sale request.

Prerequisites

The tutorial assumes you have already:

Connectivity

The JavaScript Cloud Connector leverages WebSockets to communicate with the Clover device either through Clover’s servers (Cloud Pay Display), or through a direct connection (Network Pay Display) with the Clover device.

If you’re on the same network as the device, we recommend that you use the Network Pay Display app on the Clover device and connect directly.

If you are not on the same network you must use the Cloud Pay Display app on the Clover device.

Configure a connection

Configure a connection to the Clover device.

Option 1: Cloud Pay Display

If you’re communicating through the Clover servers, your code should be similar to this example:

 

var cloudConfiguration = new clover.WebSocketCloudCloverDeviceConfiguration(
   "com.mycompany.app.remoteApplicationId:0.0.1", // the applicationId that uniquely identifies the POS.
   clover.BrowserWebSocketImpl.createInstance, // function that will return an instance of the
   // CloverWebSocketInterface that will be used when connecting.  For Browser implementations, this can be
   // BrowserWebSocketImpl.createInstance.  For NodeJS implementations, this will be defined differently.  See
   // CloverWebSocketInterface
   new clover.ImageUtil(), // utility to translate images into base64 strings.
   "https://sandboxdev.dev.clover.com/", //the base url for the clover server used in the cloud connection.
   // EX:  https://www.clover.com, http://localhost:9000
   "7aacbd26-d900-8e6a-80f0-ae55f5d1cae2", // the OAuth access token that will be used when contacting the clover server. Tied to the
   // merchant and the app.
   new clover.HttpSupport(XMLHttpRequest), // the helper object used when making http requests.
   "VKYQ0RVGMYHRR", // the merchant the device belongs to.
   "f0f00afd4bc9c55ef0733e7cb8c3da97", // the id (not uuid) of the device to connect to
   "testTerminal1_connection1", //an identifier for the specific terminal connected to this device.  This id is used
   // in debugging and may be sent to other clients if they attempt to connect to the same device.  It will also be
   // sent to other clients that are currently connected if this device does a forceConnect.
   true
);

 

Option 2: Network Pay Display

If you’re using a direct connection with the Clover device, your code should look like this:

 

var ExampleWebsocketPairedCloverDeviceConfiguration = function() {
   clover.WebSocketPairedCloverDeviceConfiguration.call(this,
       "wss://192.168.0.20:12345/remote_pay", //endpoint
       "com.cloverconnector.javascript.simple.sample:1.3.1", //remoteApplicationID
       "Javascript Simple Sample", // Displayed during pairing to display the POS name on the Mini. e.g. MyPOS
       "Register_1", // Displayed during pairing to display the device identifier. e.g. 'Aisle 3' or 'POS-35153234'
       null, // The authToken retrieved from a previous pairing activity, passed as an argument to onPairingSuccess. This will be null for the first connection
       clover.BrowserWebSocketImpl.createInstance, // function that will return an instance of the
       // CloverWebSocketInterface that will be used when connecting.  For Browser implementations, this can be
       // BrowserWebSocketImpl.createInstance.  For NodeJS implementations, this will be defined differently.  See
       // CloverWebSocketInterface
       new clover.ImageUtil() // // utility to translate images into base64 strings.
       // [heartbeatInterval] - duration to wait for a PING before disconnecting
       // [reconnectDelay] - duration to wait until a reconnect is attempted
   );
};
ExampleWebsocketPairedCloverDeviceConfiguration.prototype = Object.create(clover.WebSocketPairedCloverDeviceConfiguration.prototype);
ExampleWebsocketPairedCloverDeviceConfiguration.prototype.constructor = ExampleWebsocketPairedCloverDeviceConfiguration;

ExampleWebsocketPairedCloverDeviceConfiguration.prototype.onPairingCode = function(pairingCode) {
   console.log("Pairing code is " + pairingCode);
};

ExampleWebsocketPairedCloverDeviceConfiguration.prototype.onPairingSuccess = function(authToken) {
   console.log("Pairing succeeded, authToken is " + authToken);
};
var networkConfiguration = new ExampleWebsocketPairedCloverDeviceConfiguration();

Create a Clover Connector

Create a Clover Connector and pass in the configuration from the previous step.

var builderConfiguration = {};
builderConfiguration[clover.CloverConnectorFactoryBuilder.FACTORY_VERSION] = clover.CloverConnectorFactoryBuilder.VERSION_12;
var cloverConnectorFactory = clover.CloverConnectorFactoryBuilder.createICloverConnectorFactory(builderConfiguration);

var cloverConnector = cloverConnectorFactory.createICloverConnector(networkConfiguration);

Add a listener to the Clover Connector

1. Define an ICloverConnectorListener that will listen for callbacks when transactions finish and other events occur. Include the connection status methods that will be called:

  • OnDeviceDisconnected() – The Clover device is not available.
  • OnDeviceConnected() – The Clover device is connected, but not available to process requests.
  • OnDeviceReady() – The device is connected and available to process requests. Once the device is ready, a MerchantInfo object with information about the device, merchant, and some potential merchant payment configuration data (such as supportsAuths or supportsVaultCards) will automatically be passed in.

 

var ExampleCloverConnectorListener = function (cloverConnector, progressinfoCallback) {
   clover.remotepay.ICloverConnectorListener.call(this);
   this.cloverConnector = cloverConnector;
   this.progressinfoCallback = progressinfoCallback;
   this.testStarted = false;
};
ExampleCloverConnectorListener.prototype = Object.create(clover.remotepay.ICloverConnectorListener.prototype);
ExampleCloverConnectorListener.prototype.constructor = ExampleCloverConnectorListener;

ExampleCloverConnectorListener.prototype.onDeviceReady = function (merchantInfo) {
...
};

ExampleCloverConnectorListener.prototype.onDeviceDisconnected = function(request) {
...
};

ExampleCloverConnectorListener.prototype.onDeviceConnected = function (request) {
...
};

 

2. Add the listener to the Clover Connector.

var connectorListener = new ExampleCloverConnectorListener(cloverConnector);
cloverConnector.addCloverConnectorListener(connectorListener);

Initialize the connection

Initialize the connection to start communication with the Clover device. Note that you must do this before calling any other methods (other than those that add or remove listeners).

cloverConnector.initializeConnection();

Display a message on the Clover device

Send a test message to the Clover device.

this.cloverConnector.showMessage("Welcome to Clover Connector!");

 

Now that you’ve connected to the Clover device and sent a successful test message, you’re ready to start making requests.

Initiate a Sale from your POS software

To make a Sale() request:

1. Define how to handle the SaleResponse in your ICloverConnectorListener. The truncated code below provides a generalized overview of the methods you’ll need to use to get a response to your request for a Sale. (A detailed interpretation of the SaleResponse appears in the Handling the result of a Sale transaction section below.)

 

var ExampleCloverConnectorListener = function (cloverConnector, progressinfoCallback) {
   clover.remotepay.ICloverConnectorListener.call(this);
   this.cloverConnector = cloverConnector;
   this.progressinfoCallback = progressinfoCallback;
   this.testStarted = false;
};
ExampleCloverConnectorListener.prototype = Object.create(clover.remotepay.ICloverConnectorListener.prototype);
ExampleCloverConnectorListener.prototype.constructor = ExampleCloverConnectorListener;

ExampleCloverConnectorListener.prototype.onConfirmPaymentRequest = function(request) {
...
};

ExampleCloverConnectorListener.prototype.onVerifySignatureRequest = function (request) {
...
};

ExampleCloverConnectorListener.prototype.onSaleResponse = function (response) {
...
}

 

2. Create a SaleRequest and call the Sale() method.

var saleRequest = new sdk.remotepay.SaleRequest();
saleRequest.setExternalId(clover.CloverID.getNewId());
saleRequest.setAmount(10);
console.log({message: "Sending sale", request: saleRequest});
this.cloverConnector.sale(saleRequest);
Note

The code snippets in this tutorial are not feature-rich. For the best way to implement the SDK in production, see the Example Browser POS.

Once you call the Sale() method, Clover will contact the payment gateway and return information about the result of the transaction to your POS.

Handling the result of a Sale transaction

After Clover has finished processing the Sale transaction request, OnSaleResponse() will be called. Transaction responses have a boolean Success property, as well as an enum Result property that provides information on the success flag.

If the transaction is successful, the response will also have the Payment object, which may contain the full or partial amount of the Sale request.

Note

A Sale transaction may come back as a tip-adjustable Auth, depending on the payment gateway. The SaleResponse includes a boolean isSale variable that indicates whether the Sale is final, or will be finalized during closeout.

 

console.log({message: "Sale response received", response: response});
if (!response.getIsSale()) {
   console.log({error: "Response is not a sale!"});
}

Sale transaction errors

OnSaleResponse() will also return one of the following codes.

  • SUCCESS – The call succeeded and was successfully queued or processed.
  • FAIL – The call failed due to an incorrect value that was passed in, an invalid card, insufficient funds, or another reason.
  • UNSUPPORTED – The current merchant configuration doesn’t support the capability.
  • CANCEL – The merchant or customer has pressed the Cancel or Back button on the Clover device.
  • ERROR – An error that wasn’t expected or handled appropriately occurred. This code is returned when the SDK encounters one of the following problems:
    • Device Connection Error – The Clover device is not connected.
    • Request Validation Error – The request that was passed in for processing is empty.
    • Request Validation Error – The request ExternalId cannot be null or blank.
    • Request Validation Error – The request amount cannot be zero.
    • Request Validation Error – The request tip amount cannot be less than zero.
    • Merchant Configuration Validation Error – Not offered by the merchant-configured gateway.

Test your app

Test your app using the Test card numbers for declines and partial transactions.

For information on Clover’s testing requirements, please see the Testing & validation page.

Additional resources