Print data on the terminal

A print request allows you to initiate printing on the payment terminal from your POS app outside of a payment flow. You can print text, QR codes, or images. It is not possible to print barcode formats such as EAN-8, EAN-13, UPC-A, Code 25, Code 128 or PDF417.

Here are some examples of how you can use print requests:

• In a Pay at Table flow, print the bill on the terminal before sending a payment request. This lets the customers decide if they want to split the bill, and how they want to pay.
• Print entry tickets at a festival.
• In a quick-service restaurant, print a receipt that allows customers to pick up their order at the counter.
• Print a QR code with a URL to join your loyalty program or to download an app.

If you want to combine text with a QR code, you need to make two consecutive print requests. There is no prompt to tear off the paper following a print request (like after printing a shopper receipt), so you are able to give the shopper a single slip of paper.

A print request only works on payment terminals with a built-in printer. You can use these models:

• V240m Plus (in Brazil)
• V400c Plus
• V400m
• S1F2
• S1F2L

Print text

To use the payment terminal to print text content:

• Make a POST Terminal API request, specifying:

  • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Device and MessageCategory set to Print.

    Parameter	Required	Description
    ProtocolVersion		3.0
    MessageClass		Device
    MessageCategory		Print
    MessageType		Request
    ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
    SaleID		Your unique ID for the POS system component to send this request from.
    POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

  • PrintRequest.PrintOutput: the request body. Specify:

    Parameter	Required	Description
    DocumentQualifier		Document
    ResponseMode		PrintEnd
    OutputContent.OutputFormat		Text
    OutputContent.OutputText		An array with one or more array items containing the text you want to print.

    Each OutputText array item can have:

    Parameter	Required	Description
    CharacterStyle		Allowed values: Normal, Bold, Underline. If not specified, defaults to Normal.
    Alignment		Allowed values: Left, Centred, Justified, Right. If not specified, defaults to Left.
    EndOfLineFlag		If not specified, defaults to true. Use false if you want the next array item to continue on the same line.
    Text		The text you want to print in this array element. For a blank line, specify an empty value.

  Select the tabs below to see how you can use the parameters to print a receipt (with a header, line items, and a footer) or a document (with a title, headings, and paragraphs).

  You receive a PrintResponse with:

  • DocumentQualifier: Document
  • Response.Result: Success

Print a QR code

To use the payment terminal to print a QR code that the shopper can scan with their mobile device:

1. If the QR code needs to contain more than just a URL, convert the content to a URL-encoded string. You'll need to specify the URL-encoded string in the print request.

   For example, if the QR code should have this content:

   Visit www.adyen.com/pos-payments and:
   - Learn about the features we support
   - Choose from a range of terminals

   The resulting URL-encoded string will look like this:

   Visit%20www.adyen.com%2Fpos-payments%20and%3A%0A-%20Learn%20about%20the%20features%20we%20support%0A-%20Choose%20from%20a%20range%20of%20terminals

   If the QR code needs to contain only a URL, for example https://www.adyen.com/pos-payments, there is no need to URL-encode that. You'll specify the URL in the print request as a plain text string.

2. Make a POST Terminal API request, specifying:

   • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Device and MessageCategory set to Print.

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Device
     MessageCategory		Print
     MessageType		Request
     ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
     SaleID		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • PrintRequest.PrintOutput: the request body. Specify:

     Parameter	Required	Description
     DocumentQualifier		CustomerReceipt
     ResponseMode		PrintEnd
     OutputContent.OutputFormat		BarCode
     OutputContent.OutputBarcode.BarcodeType		QRCode
     OutputContent.OutputBarcode.BarcodeValue		The content of the QR code: a URL specified as a plain text string or a URL encoded string.

   You receive a print response with:

   • DocumentQualifier: CustomerReceipt
   • Response.Result: Success

Print an image

To use the payment terminal to print a PNG image:

1. Convert the PNG image to a Base64-encoded string.

   The size limit of the image is 256000 bytes. Therefore, we recommend using 1-bit grayscale images with a maximum width of 384 pixels.

2. In the XML code sample below, replace <IMAGE_DATA> with the Base64-encoded string.

   You must include a space between <img src="data:image/png;base64, and the Base64-encoded <IMAGE_DATA>.

3. Convert the whole XML code sample, including the already Base64-encoded image, to a Base64-encoded string.

4. Make a POST Terminal API request, specifying:

   • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Device and MessageCategory set to Print.

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Device
     MessageCategory		Print
     MessageType		Request
     ServiceID		Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
     SaleID		Your unique ID for the POS system component to send this request from.
     POIID		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

   • PrintRequest.PrintOutput: the request body. Specify:

     Parameter	Required	Description
     DocumentQualifier		Document
     ResponseMode		PrintEnd
     OutputContent.OutputFormat		XHTML
     OutputContent.OutputXHTML		The Base64-encoded XML code sample with the image data.

5. You receive a PrintResponse with:

   • DocumentQualifier: Document
   • Response.Result: Success

Handle print errors

If the print request fails because of a problem with the printer, you receive a PrintResponse containing the following:

• DocumentQualifier: Document or CustomerReceipt
• Response.Result: Failure
• ErrorCondition: DeviceOut
• AdditionalResponse: A description of the problem, for example:
  • Printer is Temporary Out of Service: paper low.
  • Printer is Temporary Out of Service: no more paper.
  • Printer is Temporary Out of Service: paper jam.
  • Printer is Permanently Out of Service: out of order.
  • Printer is Permanently Out of Service: unknown.
  • Printer is Permanently Out of Service: absent.
  • The device has no printer.

The next example shows the response when the terminal has run out of paper.

See also