In the Cloud

United States
Canada
Europe
Latin America

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

Before you begin

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.

Direct connection—Secure Network Pay Display

Advantages

  • Performance—A direct connection performs better than a cloud connection, which proxies requests through Clover servers.
  • Simple connection configuration—The configuration for a direct connection is simpler than a cloud connection configuration.

Disadvantage

  • Point of sale (POS) users need to install and trust the Clover device server certificate in any browser that runs your POS application.

Cloud connection—Cloud Pay Display

Advantages

  • Flexibility—Cloud connections support connecting to devices that are not on the same network as the POS.
  • No certificate requirements—The application connects to the device through Clover servers, which eliminates the need for browsers running the POS to install and trust the Clover device server certificate.

Disadvantages

  • Performance—Cloud proxies make requests through Clover servers, so they may not perform as well as if directly connected to the Clover device.
  • More complex connection configuration—Connection configuration for the cloud is more complex than the configuration for a direct connection.

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

📘

NOTE

The Secure Network Pay Display app must be installed and running on the Clover device before you can connect directly.

Network connection parameters
You can use the following parameters to configure network connections.

  • applicationId—Remote application ID (RAID) of the POS app.
  • uri—Endpoint of the Clover device (for example, wss://192.168.1.15:12345/remote_pay). This endpoint appears on the screen when you first launch the Secure Network Pay Display app.
  • posName—Name displayed during pairing to identify the POS attempting to connect to the device.
  • serialNumber—Serial number/identifier of the POS, as displayed in the Secure Network Pay Display app. Note: This is different from the Clover device’s serial number.
  • authTokenauthToken was retrieved from a previous pairing response and passed as an argument to onPairingSuccess. The authToken is null for the first connection. Store and use the authToken in subsequent requests to skip pairing.
  • onPairingCode—The device sends a pairing code to call the function.
  • onPairingSuccess—The paired POS and device call the function.

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.

Setting 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 (sandbox or production).
  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.

Cloud connection parameters
When you configure a cloud connection, you need to use the following parameters.

🚧

IMPORTANT

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

  • applicationId—Remote application ID (RAID) of the POS app
  • deviceId—You need to retrieve an accessToken and your merchantId before you can get thedeviceId. Then, make the following GET request to the Clover REST API:
    https://{cloverServer}/v3/merchants/{merchantId}/devices
  • merchantId—Steps for finding your merchantId are available on the Test Merchant IDs & API Tokens page.
  • accessToken—The OAuth token is used to contact the Clover server. The steps for obtaining the token are available on the Authenticate with OAuth—Canada and US and Using OAuth 2.0—Europe and Latin America pages.
  • cloverServer—Base URL for the Clover server used in the cloud connection (for example, https://api.clover.com or https://sandbox.dev.clover.com/).
  • `friendlyId'—Identifies the specific terminal connected to the Clover device. Problems with reconnection logic may occur if you don't provide a unique ID. Also, the SDK may return inaccurate error messages if another terminal is already connected to the Clover device.

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();

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);

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"});
   }

});
  1. Add the listener to the Clover Connector.
cloverConnector.addCloverConnectorListener(defaultCloverConnectorListener);

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();

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.

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);
  1. 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.

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.

📘

NOTE

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!"});
}

Sale transaction errors

onSaleResponse() returns one of the following codes:

  • SUCCESS—Call succeeded and was successfully queued or processed.
  • FAIL—Call failed due to an incorrect value passed in, an invalid card, insufficient funds, or another reason.
  • UNSUPPORTED—Current merchant configuration doesn’t support the capability.
  • CANCEL—Merchant or customer has pressed the Cancel or Back button on the Clover device.
  • ERROR—Unexpected or mishandled error. This code is returned when the SDK encounters one of the following problems:
  • Device Connection Error—Clover device is not connected.
  • Request Validation Error—Request that was passed in for processing is empty.
  • Request Validation Error—Request ExternalId cannot be null or blank.
  • Request Validation Error—Request amount cannot be zero.
  • Request Validation Error—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. See Test region-based payment flows.

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