The Clover Connector Browser SDK provides an interface that lets you use your web-based point of sale (POS) software to interact with Clover customer-facing payment devices through the cloud.

You can use these instructions to connect to your Clover device, initiate a Sale request, and handle the response to your Sale request. The instructions cover the current version of the SDK.

A more comprehensive tutorial for this SDK is available on GitHub: Remote Pay Cloud Codelab.

Prerequisites

• Read the Overview of the Clover platform
• Set up a developer account (including your test merchant settings).
• Order and set up a Clover Developer Kit (Dev Kit).
• Create a Remote App ID (remoteApplicationID) for your semi-integration POS. This is different from your App ID.

Before you begin

• Install the Cloud Pay Display app on the Clover device.
• Use the Secure Network Pay Display app for a local network connection on the Clover Flex, Clover Mini, and Clover Mobile.

Connectivity

The JavaScript Cloud Connector uses WebSockets to communicate with the Clover device through a direct connection (using the Secure Network Pay Display app) or Clover servers (using the Cloud Pay Display app).

Whether you use a direct or cloud configuration depends on several factors.

1. Configure a connection

Clover recommends that connections to the Clover device use the builder for a paired or cloud configuration. The builders reduce the amount of code needed to connect to the device. You can use the constructor directly.

Option 1: Direct connection with Secure Network Pay Display

You need to install the Secure Network Pay Display and run the app on the Clover device before you can connect directly.

Parameters for network connection

Use the following parameters to configure network connections:

Sample code

The following is an example code of a direct connection using the paired configuration builder:

const clover = require ("remote-pay-cloud");
...

const networkConfigurationBuilder = new clover.WebSocketPairedCloverDeviceConfigurationBuilder(
  "SWDEFOTWBD7XT.9MGLGMDLSYWTV", // applicationId
  "wss://192.168.0.20:12345/remote_pay", // uri
  "myPOS", //posName
  "Register_1", //serialNumber
  null, //authToken
  onPairingCode, //onPairingCode
  onPairingSuccess //onPairingSuccess
);

const pairedConfiguration = networkConfigurationBuilder.build();

Option 2: Cloud Pay Display

You need to install and start the Cloud Pay Display on the Clover device before you can connect.

Set the CORS domain

You need to configure the CORS domain using the Developer Dashboard to establish a connection between your app and the Clover device.

1. Log in to the Developer Dashboard.
2. On the Your Apps tab, find your app and click Settings.
3. On the Settings page, click Web Configuration.
4. In the CORS Domain field, enter your app's URL.
5. Click Save.

Parameters to configure a cloud connection

Use the following parameters to configure a cloud connection:

🚧

IMPORTANT

When you configure the environment in production, set the cloverServer to https://api.clover.com. Be sure to enter the www subdomain.

Sample code

The following sandbox example code shows a cloud connection using the cloud configuration builder:

const clover = require ("remote-pay-cloud");
...

const cloudConfigurationBuilder = new clover.WebSocketCloudCloverDeviceConfigurationBuilder(
  "SWDEFOTWBD7XT.9MGLGMDLSYWTV", // applicationId
  "f0f00afd4bc9c55ef0733e7cb8c3da97", // deviceId
  "VKYQ0RVGMYHRR", // merchantId 
  "7aacbd26-d900-8e6a-80f0-ae55f5d1cae2", // accessToken
);

const cloudConfiguration = cloudConfigurationBuilder.setCloverServer("https://sandbox.dev.clover.com")
    .setFriendlyId("A unique ID for your POS terminal")
    .build();

2. Create a Clover Connector

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

const clover = require ("remote-pay-cloud");
...
var builderConfiguration = {};
builderConfiguration[clover.CloverConnectorFactoryBuilder.FACTORY_VERSION] = clover.CloverConnectorFactoryBuilder.VERSION_12;
var cloverConnectorFactory = clover.CloverConnectorFactoryBuilder.createICloverConnectorFactory(builderConfiguration);

var cloverConnector = cloverConnectorFactory.createICloverConnector(connectorConfiguration);

3. 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 the listener calls:

• onDeviceDisconnected()—Clover device is not available.
• onDeviceConnected() —Clover device is connected but not available to process requests.
• onDeviceReady() —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) is passed in.

📘

NOTE

onDeviceReady() may be called multiple times. For this reason, we do not recommend initiating sales or other transactions from onDeviceReady().

const clover = require ("remote-pay-cloud");
...

var defaultCloverConnectorListener = Object.assign({}, clover.remotepay.ICloverConnectorListener.prototype, {

   onDeviceReady: function (merchantInfo) {
       updateStatus("Pairing successfully completed, your Clover device is ready to process requests.");
       console.log({message: "Device Ready to process requests!", merchantInfo: merchantInfo});
   },

   onDeviceDisconnected: function () {
       console.log({message: "Disconnected"});
   },

   onDeviceConnected: function () {
       console.log({message: "Connected, but not available to process requests"});
   }

});

2. Add the listener to the Clover Connector.

cloverConnector.addCloverConnectorListener(defaultCloverConnectorListener);

4. Initialize the connection

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

cloverConnector.initializeConnection();

5. Display a message on the Clover device

Send a test message to the Clover device.

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

After you connect to the Clover device and send a successful test message, you can start making requests.

📘

NOTE

Clover recommends that your app create, initialize, and maintain one Clover Connector for all transactions. A constant connection eliminates the overhead needed to re-open the connection.

6. 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 is an overview of the methods you need to use to get a response to a Sale request. A detailed interpretation of the SaleResponse appears in the Handle the result of a Sale transaction section.

var saleListener = Object.assign({}, defaultCloverConnectorListener, {
   onSaleResponse: function (response) {
      ….
   },

   onConfirmPaymentRequest: function (request) {
       ...
   },

   onVerifySignatureRequest: function (request) {
       ...
   }
});

 cloverConnector.addCloverConnectorListener(defaultCloverConnectorListener);

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

const clover = require ("remote-pay-cloud");
const sdk = require ("remote-pay-cloud-api");
...
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);

When you call the Sale() method, Clover contacts the payment gateway and returns information about the result of the transaction to your POS.

7. Handle the result of a sale transaction

After Clover processes the Sale transaction request, Clover calls onSaleResponse(). Transaction responses have a boolean Success property and an enum Result property that provides information on the success flag.

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

A Sale transaction may return 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!"});
}

8. Sale transaction errors

onSaleResponse() returns one of the following codes:

9. Test your app

Test your app using the test card numbers for declines and partial transactions. See Test region-based payment flows.

10. Dispose of the Clover Connector

You can use CloverConnector.dispose() to close the connection before you initialize a new one. To handle page refreshes properly, you can do this for browser-based apps before the window unloads.

Additional resources

• Clover Connector Browser SDK
• API documentation
• API class documentation
• Example apps