Create custom receipts with CloverConnector

If your integration requires receipt features beyond those provided by Clover (see Set up payment receipts), you can disable the default receipts Per-transaction settings and print your own using the Clover device printer. It is your responsibility to ensure that custom receipts comply with local laws and regulations.

📘

Note

When your default receipt selection screen does not appear during the payment flow, your app should launch a Custom Activity if customer input is required.

Get the device printer

Before you can use the print() method, you must:

  1. Retrieve information about the available printer for the device. Your app can retrieve this information after the connection is established and the device is ready for subsequent requests. The following samples from the Remote Pay Android Example POS illustrate how to get the printer information from the connected device.
public static List<Printer> printers;
private Printer printer;

public void onDeviceReady(final MerchantInfo merchantInfo) {
  runOnUiThread(new Runnable() {
    public void run() {
      showMessage("Ready!", Toast.LENGTH_SHORT);
    }
  });
  RetrievePrintersRequest rpr = new RetrievePrintersRequest();
  cloverConnector.retrievePrinters(rpr);
}
  1. Create a listener to handle the response to the RetrievePrinters() call and set the printer for the currently connected device. Use this to confirm that the printer is available before making a print request.
@Override
public void onRetrievePrintersResponse(RetrievePrintersResponse response) {
  printers = response.getPrinters();
  if(printers != null){
    printer = printers.get(0);
  }
}

Print a custom receipt

To send an image to the device printer, use CloverConnector.print(PrintRequest). The first parameter of the PrintRequest can take one of three forms—a bitmap image, the URL (link) of an image, or an array of text strings. The following samples from the Remote Pay Android Example POS illustrate each type of PrintRequest:

  1. Print image
public void printImage(String imgDecodableString){
  Bitmap bitmap = BitmapFactory.decodeFile(imgDecodableString);
  if(this.printer != null){
    PrintRequest pr = new PrintRequest(bitmap);
    lastPrintRequestId = String.valueOf(getNextPrintRequestId());
    pr.setPrintRequestId(lastPrintRequestId);
    pr = new PrintRequest(bitmap, lastPrintRequestId, printer.getId());
    cloverConnector.print(pr);
  }
}
  1. Print an image from a URL (link)
public void printImageURLClick(View view) {
  String URL = ((TextView) findViewById(R.id.PrintImageURLText)).getText().toString();
  if(printer != null){
    PrintRequest pr = new PrintRequest(URL);
    lastPrintRequestId = String.valueOf(getNextPrintRequestId());
    pr.setPrintRequestId(lastPrintRequestId);
    pr = new PrintRequest(URL, lastPrintRequestId, printer.getId());
    cloverConnector.print(pr);
  }
}
  1. Print text on receipt
public void printTextClick(View view) {
  String[] textLines = ((TextView) findViewById(R.id.PrintTextText)).getText().toString().split("\n");
  List<String> lines = Arrays.asList(textLines);
  if(printer != null){
    PrintRequest pr = new PrintRequest(lines);
    lastPrintRequestId = String.valueOf(getNextPrintRequestId());
    pr.setPrintRequestId(lastPrintRequestId);
    pr = new PrintRequest(lines, lastPrintRequestId, printer.getId());
    cloverConnector.print(pr);
}

Guidelines for receipt images

For the best printing performance, Clover recommends the following when constructing a print receipt bitmap:

  • Pre-scale the image to a maximum width of 576 pixels.
  • Use a purely black-and-white image, where the saturation value is zero (0). A gray-scaled image processes more slowly because the device evaluates each pixel.