Release NotesAnnouncementsVideosBlog
Guides

On Windows using .NET

Refers to Windows SDK v4.0

United States
Canada
Europe
Latin America

This tutorial 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 version 4.0 of the SDK.

Platform-specific prerequisites

In addition to the prerequisites described in Use Clover Connector, this tutorial assumes you have already:

Connectivity

USB is the preferred method of communication with the device, and the SDK provides a USB connector and USB drivers for the Clover devices. The USB connector requires the USB Pay Display app to communicate with a Clover device. This tutorial walks through creating a USB connection using the SDK.

To see an example of how to connect using Secure Network Pay Display, see the SnpdConnectionExample project in the Remote Pay Windows Examples repository.

Create a Clover Connector

The following example demonstrates the use of CloverConnectorFactory to configure a USB connection from a Windows device to a Clover device. You can also configure a network connection. Both types of connections require your app to include your remote app ID, the application-specific value that Clover uses to log information about your integration.

var cloverConnector = CloverConnectorFactory.CreateUSBConnector(
  "SWDEFOTWBD7XT.9MGLGMDLSYWTV", // remote application ID
  "My POS", // POS name
  "Register 1" // serial number
);

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.
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
        }
}
  1. 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:

  1. Define how to handle the SaleResponse in your ICloverConnectorListener first. 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 Handlle 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’
            …
      }
      …
}
  1. 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 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.

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:

Error codeDescription
SUCCESSCall succeeded and was successfully queued or processed.
FAILCall failed due to an incorrect value that was passed in, an invalid card, insufficient funds, or another reason.
UNSUPPORTEDCurrent merchant configuration doesn’t support the capability.
CANCELMerchant or customer has pressed the Cancel or Back button on the Clover device.
ERRORUnexpected error or error that wasn't handled appropriately. 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, see Test region-based payment flows page.

Configure Windows event logging

When an integrated app launches, the SDK checks that logging sources are properly configured. If the logs are not set up, an error will be returned. See Set up the Windows Event Log for more information.

Understand SDK best practices

A robust POS application allows merchants and their customers to easily and reliably interact with the Clover device. See Remote Pay SDK best practices for more information about designing your app with Clover's recommended best practices.

Additional resources

Updated 17 days ago