In the Cloud
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 toonPairingSuccess
. This will be null for the first connection. Store and use theauthToken
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.
- Log in to the developer dashboard (sandbox or production).
- On the Your Apps tab, find your app and click Settings.
- On the Settings page, click Web Configuration.
- In the CORS Domain field, type your app's URL.
- 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 tohttps://www.clover.com
. Be sure to specify thewww
subdomain.
applicationId
—Remote application ID (RAID) of the POS appdeviceId
—Get thedeviceId
, you must first retrieve anaccessToken
and yourmerchantId
. Then, make the following GET request to the Clover REST API:
https://{cloverServer}/v3/merchants/{merchantId}/devices
merchantId
—Steps for finding yourmerchantId
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
orhttps://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
- 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, aMerchantInfo
object with information about the device, merchant, and some potential merchant payment configuration data (such assupportsAuths
orsupportsVaultCards
) will automatically be passed in.
NOTE
onDeviceReady()
may be called multiple times. For this reason, we do not recommend initiating sales or other transactions fromonDeviceReady()
.
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"});
}
});
- 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:
- Define how to handle the
SaleResponse
in yourICloverConnectorListener
. The truncated code below provides a generalized overview of the methods you’ll need to use to get a response to your request for aSale
. A detailed interpretation of theSaleResponse
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);
- Create a
SaleRequest
and call theSale()
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-adjustableAuth
, depending on the payment gateway. TheSaleResponse
includes a booleanisSale
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