Printing a receipt

The API provides two options for printing receipts with the built-in printer:

  • Print a standard Clover receipt which complies with card brand requirements
  • Print a text- or image-based receipt if your integration has specific design needs not provided on a standard receipt

For most merchants, the receipt customization options provided by Clover are sufficient. These options include the merchant's logo, custom header and footer text, and other modifications commonly requested by merchants. Using Clover's system also gives the merchant more control than a receipt generated by an integrated POS.

📘

NOTE

If your transaction request includes a receipt_email, a web receipt will be sent to the customer automatically when the transaction is finalized.

Prerequisites

  • The POS is connected to the device using a network or cloud connection
  • The Clover device is in an idle state (that is, no payment is being taken)
  • The ID of the printer receiving the request is known

Standard receipts

You can print a standard receipt for any payment, credit, or refund by sending a POST request with the following body to the associated endpoint for a given transaction:

{
  "deliveryOption": {
    "method": "PRINT"
  }
}

For example, if your refund UUID is 45YIYT7B1ABYE, send the request to /v1/refunds/45YQVE7B1ABYE/receipt and the Clover device will automatically print the receipt.

📘

NOTE

Email and text receipts can also be sent using these endpoints by changing the deliveryOption.method to EMAIL or SMS and including the email address or phone number as additionalData. See the REST API Reference for more information

Custom receipts

Getting the printer ID

Both /v1/device/print endpoints require the printer's identifier in the request. To retrieve this ID from a Clover device, do the following.

  • Send an empty POST request to the /v1/device/printers endpoint.
    A message is returned containing the ID and name of the printer.
{
    "printers": [
        {
            "id": "YR8P3KTEW2182",
            "name": "Mini"
        }
    ]
}

Printing a text-based receipt

A basic receipt can be printed by providing an array of strings in your request. To print a text-based receipt, complete the following steps.

🚧

IMPORTANT

You are responsible for ensuring the receipts printed by your app comply with all card brand rules and all laws and regulations for the locale where the merchant operates.

  1. Construct a request body containing the required data (printDeviceId and text). The text field is an array of strings that will be printed in order. Blank array values can be used to create space between different sections of the receipt.
{
  "printDeviceId": "{{printerid}}",
  "text": [
    "SANDBOX SUPPLIES",
    "415 N Mathilda Ave",
    "Sunnyvale, CA 94085",
    "{{currentDateTime}}",
    "",
    "Order number: {{orderId}}",
    "Items:",
    "1 shovel @ $29.00",
    "20 lbs sand @ $0.69/lb",
    "",
    "Subtotal: 42.80",
    "Tax: 3.42",
    "Total: 46.22",
    "",
    "Please sign below",
    "",
    "________________________",
    "{{cardholderName}}",
    "",
    "I agree to pay the above total amount according to my card issuer agreement.",
    "{{cardBrand}}"
    ]
}
  1. Send a POST request to /v1/device/print/text. Be sure to include the required headers for the request you are making.

The text is printed on the receipt.

Printing an image-based receipt

You can customize your receipts by generating an Base-64 encoded PNG of the final receipt and using the device printer to print it. Note the following guidelines for receipt images:

  • Images must be Base-64 encoded PNG files. The encoding should be generated without newline/line feeds, and the result must be properly escaped in the JSON request body.
  • For the best performance, images should be optimized for size before encoding
  • Images should be black and white
  • Transparency (alpha channel) should not be used because the printer interprets transparent as black

🚧

IMPORTANT

You are responsible for ensuring the receipts printed by your app comply with all card brand rules and all laws and regulations for the locale where the merchant operates.

To print an image-based receipt, complete the following steps.

  1. Construct a request body containing the required data (printDeviceId and image). The image field is a Base64-encoded representation of the PNG file.
{
  "printDeviceId": "{{printerid}}",
  "image": "{{base64image}}"
}
  1. Send a POST request to /v1/device/print/image.

The image is printed on the receipt.


Did this page help you?