Release NotesAnnouncementsVideosCommunityBlog

In the Cloud

United States
Canada
Europe
Latin America

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

These steps will guide you through the process of connecting to your Clover device, initiating a Sale request, and handling the response to your Sale request. It covers the current version of the SDK.

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

Platform-specific prerequisites

In addition to the prerequisites in Use Clover Connector, this tutorial assumes you have installed the Cloud Pay Display app on the Clover device. You can also use the Secure Network Pay Display app for a local network connection (currently available for Clover Flex, Clover Mini, and Clover Mobile).

Connectivity

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

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

Direct Connection: Secure Network Pay Display

Advantages

  • Performance—Direct connection performs better than a cloud connection, which proxies requests through Clover’s servers
  • Simple connection configuration—Configuration for a direct connection is less complex

Disadvantage

  • POS users must 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—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 request through Clover servers, so may not perform as well as a direct connection 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

It is recommended 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. If wanted, the constructor can be used 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
The following parameters are needed for network configurations.

  • 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 is displayed on the screen that appears 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 not the same as the Clover device’s serial number.
  • authToken—authToken retrieved from a previous pairing response, passed as an argument to onPairingSuccess. This will be null for the first connection. Store and use the authToken in subsequent requests to skip pairing.
  • onPairingCode—Function called when a pairing code is sent by the device.
  • onPairingSuccess— Function called when the POS and device are paired.

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

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

Setting the CORS domain

To establish a connection between your app and the Clover device, you must configure the CORS domain using the developer dashboard.

  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, type your app's URL.
  5. Click Save.

Cloud Connection Parameters
The following parameters are needed for cloud configurations.

🚧

IMPORTANT

When configuring the environment in production, the cloverServer should be set to https://www.clover.com. Be sure to specify the www subdomain.

  • applicationId—Remote application ID (RAID) of the POS app
  • deviceId—Get thedeviceId, you must first retrieve an accessToken and your merchantId. 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—OAuth token used when contacting the Clover server. The steps for obtaining the token are available on the Using OAuth 2.0 page.
  • cloverServer—Base URL for the Clover server used in the cloud connection (for example, https://www.clover.com or https://sandbox.dev.clover.com/).
  • `friendlyId'—Identifier for the specific terminal connected to this device. Failure to provide a unique ID may cause problems with reconnection logic, or 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 will be called:
  • 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) will automatically be 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. 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.

📘

NOTE

It is recommended that your app create, initialize, and maintain one Clover Connector for all transactions. This constant connection eliminates the overhead otherwise 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 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 Handle the result of a Sale transaction section 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);

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

Handle 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 also includes 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() also returns one of the following codes.

  • SUCCESS—Call succeeded and was successfully queued or processed.
  • FAIL—Call failed due to an incorrect value that was 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—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—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.

For information on, see Test region-based payment flows.

Dispose of the Clover Connector

To close the connection before initializing a new one, use CloverConnector.dispose(). For browser-based apps, this should be done before the window unloads to properly handle page refreshes.

Additional resources

Updated about 1 month ago