On Windows using REST
IMPORTANT
The REST service is no longer provided with the Windows SDK as of version 3.0. This section applies to v1.4 and is provided for reference purposes only.
The CloverConnector REST service is a Windows service that allows communication with a customer-facing Clover device through a REST interface, without accessing the Clover Connector SDK .NET DLL directly.
The REST Service mimics ICloverConnector’s methods and arguments. The ICloverConnectorListener is also implemented as a REST callback service and expects to make REST calls back to a provided REST service.
This tutorial guides you through the process of connecting to your Clover device, initiating a Sale request, and handling the response to your Sale request.
Platform-specific prerequisites
In addition to the prerequisites in Use Clover Connector, this tutorial assumes you have already:
- Installed the USB 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 Mini and Clover Mobile).
- Installed Visual Studio on your computer. The Windows SDK also requires .NET Framework version 4.0.
Connectivity
The CloverConnector REST service runs as a Windows service and connects to the Clover device over USB. The REST service is incompatible with the Clover Connector SDK DLL and the WebSocket service, as they will compete for the USB connection to the Clover device.
NOTE
The CloverConnector REST service will only allow connections from localhost.
Ports
The CloverConnector REST service will listen on port 8181 by default. You can change the listening port using the /P command-line argument:
CloverConnectorRESTService.exe /P 9250
The service will callback on port 8282 on localhost. You can change the callback location using the /C command-line argument:
CloverConnectorRESTService.exe /C http://127.0.0.1:9255/CloverCallbackListener
Configure a connection
Configure the connection between your Windows device and the Clover device. The following example demonstrates how to configure a USB connection. You can also configure a network connection.
var usbConfiguration = new USBCloverDeviceConfiguration("__deviceID__",
"YourRAID", false, 1);
Create a Clover Connector
Create a Clover Connector and pass in the configuration from the previous step. The following example is for a network connection. You can also pass in a USB configuration.
var cloverConnector = new CloverConnector(GetNetworkConfiguration());
Add a listener to the Clover Connector
- Define an
ICloverConnectorListenerthat 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, aMerchantInfoobject with information about the device, merchant, and some potential merchant payment configuration data (such assupportsAuthsorsupportsVaultCards) will automatically be passed in.
public class ExampleCloverConnectionListener : DefaultCloverConnectorListener
{
public ExampleCloverConnectionListener(ICloverConnector cloverConnector) : base(cloverConnector)
{
}
public override void OnDeviceReady(MerchantInfo merchantInfo)
{
base.OnDeviceReady(merchantInfo);
//Connected and available to process requests
}
public override void OnDeviceConnected()
{
base.OnDeviceConnected();
// Connected, but not available to process requests
}
public override void OnDeviceDisconnected()
{
base.OnDeviceDisconnected();
Console.WriteLine("Disconnected");
//Disconnected
}
}
- Add the listener to the Clover Connector.
// Add an instance of an ICloverConnectorListener
var ccl = new ExampleCloverConnectorListener(cloverConnector);
cloverConnector.AddCloverConnectorListener(ccl);
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.
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:
- Define how to handle the
SaleResponsein yourICloverConnectorListenerfirst. 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 theSaleResponseappears in the Handle the result of a Sale transaction section.
public class ExampleCloverConnectorListener : DefaultCloverConnectorListener {
…
public override void OnSaleResponse(SaleResponse response)
{
// check response for success and process accordingly
// see below for more detail ‘Handling Results of a Sale Transaction’
…
}
public override void OnConfirmPaymentRequest(ConfirmPaymentRequest request)
{
// must accept or reject the payment using the ICloverConnector
// see below for more detail ‘Handling Results of a Sale Transaction’
…
}
public override void OnVerifySignatureRequest(VerifySignatureRequest verifySigRequest)
{
// must accept or reject the signature using the ICloverConnector
// see below for more detail ‘Handling Results of a Sale Transaction’
…
}
…
}
- Create a SaleRequest and call the Sale() method.
var pendingSale = new SaleRequest();
pendingSale.ExternalId = ExternalIDUtil.GenerateRandomString(32);
pendingSale.Amount = 1000;
cloverConnector.Sale(pendingSale);
NOTE
The code snippets in this tutorial are not feature-rich. For the best way to implement the SDK in production, see the Example Windows 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.
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 will also have the Payment object, which may contain the full or partial amount of the Sale request.
NOTE
A
Saletransaction may come back as a tip-adjustableAuth, depending on the payment gateway. TheSaleResponseincludes a booleanisSalevariable that indicates whether the Sale is final, or will be finalized during closeout.
class SaleConnectorListener : ICloverConnectorListener
{
public Boolean saleDone { get; set; }
public Boolean deviceReady { get; set; }
public SaleConnectorListener(ICloverConnector cloverConnector) : base(cloverConnector)
{
}
public override void OnConfirmPaymentRequest(ConfirmPaymentRequest request)
{
Console.WriteLine("Confirm Payment Request");
List<Challenge> challenges = request.Challenges;
if (challenges != null && challenges.Count > 0)
{
foreach (Challenge challenge in challenges)
{
Console.WriteLine("Received a challenge: " + challenge.type);
}
}
Console.WriteLine("Automatically processing challenges");
cloverConnector.AcceptPayment(request.Payment);
}
public override void OnDeviceReady(MerchantInfo merchantInfo)
{
base.OnDeviceReady(merchantInfo);
try
{
var pendingSale = new SaleRequest();
pendingSale.ExternalId = ExternalIDUtil.GenerateRandomString(13);
pendingSale.Amount = 1000;
pendingSale.AutoAcceptSignature = true;
pendingSale.DisableDuplicateChecking = true;
cloverConnector.Sale(pendingSale);
}
catch(Exception e)
{
Console.WriteLine("Error submitting sale request");
Console.WriteLine(e.StackTrace);
} }
deviceReady = true;
}
public override void OnSaleResponse(SaleResponse response)
{
base.OnSaleResponse(response);
try
{
if (response.Success)
{
var payment = response.Payment;
if (payment.externalPaymentId.Equals(pendingSale.ExternalId))
{
Console.WriteLine("Sale request successful");
Console.WriteLine(" ID: " + payment.id);
Console.WriteLine(" External ID: " + payment.externalPaymentId);
Console.WriteLine(" Order ID: " + payment.order.id);
Console.WriteLine(" Amount: " + payment.amount);
Console.WriteLine(" Tip Amount: " + payment.tipAmount);
Console.WriteLine(" Tax Amount: " + payment.taxAmount);
Console.WriteLine(" Offline: " + payment.offline);
Console.WriteLine(" Authorization Code: " +
payment.cardTransaction.authCode);
Console.WriteLine(" Card Type: " + payment.cardTransaction.cardType);
Console.WriteLine(" Last 4: " + payment.cardTransaction.last4);
}
else
{
Console.Error.WriteLine("Sale Request/Response mismatch - " +
pendingSale.ExternalId + " vs " + payment.externalPaymentId);
}
}
else
{
Console.Error.WriteLine("Sale Request Failed - " + response.Reason);
}
}
catch(Exception e)
{
Console.Error.WriteLine("Error handling sale response");
Console.Error.WriteLine(e.StackTrace);
}
saleDone = true;
}
public override void OnVerifySignatureRequest(VerifySignatureRequest request)
{
base.OnVerifySignatureRequest(request);
Console.WriteLine("Verify Signature Request - Signature automatically accepted by
default");
}
}
Sale transaction errors
OnSaleResponse() will also return 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—RequestExternalIdcannot 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, see Test region-based payment flows page.
Debug
You can run the service as a command process from a command window instead of a Windows service by adding a /D parameter. This will allow you to view the output in the command window. You can also set the -debug parameter on either the command line or service to log additional information to the Event Viewer.
NOTE
The Windows service must be stopped before running from the command window.
Endpoints
By default, ICloverConnector methods are exposed at the base URL http://localhost:8181/Clover. For example, the default endpoint to initiate a Sale is http://localhost:8181/Clover/Sale.
For the REST service, /Status is a call that doesn’t exist in the DLL ICloverConnector. The /Status call was added to the REST service to tell the service when a client is ready to receive callbacks. The /Status call triggers a callback for the current connection state of /CloverCallback/OnDisconnected, /CloverCallback/OnConnected, or /CloverCallback/OnReady.
Because ICloverConnectorListener is implemented via REST callbacks, a REST service must be running to receive calls from the Clover device.
Additional resources
Updated 5 months ago