Show a virtual receipt on the terminal

Show a virtual receipt the display of the payment terminal.

On a payment terminal with a large display like the M400, you can show the shopper an overview of their purchase before the payment transaction starts. Here are some examples of such virtual receipts. The receipt lines are scrollable, and you can include a QR code next to the receipt lines.

For a virtual receipt, you need to gather all content in an XML file, convert that to a Base64 string, and pass that string in a display request. The XML file can contain:

<qrcodeblock>: QR code with a header and footer. This only works on terminals with a wide display such as the M400.
<list-header>: The header line of the virtual receipt.
<lines>: Contains line items representing the goods that the shopper is purchasing. Each line item can have a description, price, and count.
<tax>: The amount and type of tax.
<total>: Subtotal and total amount due.

For the full structure, see the example receipt XML file below.

Make a display request for a virtual receipt

Create the virtual receipt:
1. Based on our example XML file, populate an XML file with line items and total amounts from your cash register.
2. Convert the XML content to a Base64 string.

Make a POST request to a Terminal API endpoint, specifying:

MessageHeader: The standard MessageHeader structure, explained in Terminal API fundamentals:

Parameter	Required	Description
`ProtocolVersion`		3.0
`MessageClass`		Device
`MessageCategory`		Display
`MessageType`		Request
`SaleID`		Your unique ID for the cash register.
`ServiceID`		Your unique ID for this request, consisting of 1-10 alphanumeric characters. This value needs to be unique within the last 48 hours.
`POIID`		Unique ID of the terminal that you want to route this request to. Format: [device model]-[serial number].

DisplayRequest.DisplayOutput: An array containing a single array item with:

Parameter Required Description

Device CustomerDisplay

InfoQualify Display

OutputContent.OutputFormat XHTML

OutputContent.OutputXHTML The Base64 string containing the XML content.

https://docs.adyen.com/point-of-sale/display-data/display-receipt#display-virtual-receipts_0

JSON
Java

{
   "SaleToPOIRequest":{
      "DisplayRequest":{
         "DisplayOutput":[
            {
               "Device":"CustomerDisplay",
               "InfoQualify":"Display",
               "OutputContent":{
                  "OutputFormat":"XHTML",
                  "OutputXHTML": "...paste Base64 encoded XML here..."
               }
            }
         ]
      },
      "MessageHeader":{
         "ServiceID":"1116172359",
         "ProtocolVersion":"3.0",
         "MessageClass":"Device",
         "POIID":"M400-284251175",
         "MessageType":"Request",
         "SaleID":"POSSystemID12345",
         "MessageCategory":"Display"
      }
   }
}

String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
String POIID = "YOUR_TERMINAL_ID";
String saleID = "YOUR_CASH_REGISTER_ID";

SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
DisplayRequest displayRequest = new DisplayRequest();
DisplayOutput displayOutput = new DisplayOutput();
displayOutput.setDevice( DeviceType.CUSTOMER_DISPLAY );
displayOutput.setInfoQualify( InfoQualifyType.DISPLAY );
OutputContent outputContent = new OutputContent();
outputContent.setOutputFormat( OutputFormatType.XHTML );
outputContent.setOutputXHTML("...paste base64 encoded XML here...");
displayOutput.setOutputContent(outputContent);
displayRequest.setDisplayOutput(displayOutput);
saleToPOIRequest.setDisplayRequest(displayRequest);

MessageHeader messageHeader = new MessageHeader();
messageHeader.setServiceID(serviceID);
messageHeader.setProtocolVersion("3.0");
messageHeader.setMessageClass( MessageClassType.DEVICE );
messageHeader.setPOIID(POIID);
messageHeader.setMessageType( MessageType.REQUEST );
messageHeader.setSaleID(saleID);
messageHeader.setMessageCategory( MessageCategoryType.DISPLAY );
saleToPOIRequest.setMessageHeader(messageHeader);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

If the request is successful, you receive a display response with:

OutputResult.Response.Result: Success

{
   "SaleToPOIResponse":{
      "DisplayResponse":{
         "OutputResult":[
            {
               "InfoQualify":"Display",
               "Device":"CustomerDisplay",
               "Response":{
                  "Result":"Success"
               }
            }
         ]
      },
      "MessageHeader":{...}
   }
}

If the request is not successful, for example if you sent the DisplayRequest to an incompatible terminal, you receive a display response with:

OutputResult.Response.Result: Failure.
AdditionalResponse and ErrorCondition: More information about why the request failed.

For example:

{
   "SaleToPOIResponse":{
      "DisplayResponse":{
         "OutputResult":[
            {
               "InfoQualify":"Display",
               "Device":"CustomerDisplay",
               "Response":{
                  "Result":"Failure",
                  "AdditionalResponse":"message=DisplayRequest%20API%20cannot%20be%20used%20for%20this%20terminal%20model.",
                  "ErrorCondition":"NotAllowed"
               }
            }
         ]
      },
      "MessageHeader":{...}
   }
}

Receipt XML file

Use this example XML file to populate an XML input file with line items and total amounts from your cash register.

<?xml version="1.0" encoding="UTF-8"?>
<screen name="virtual-receipt-with-qr-code.xslt">
    <receipt>
        <qrcodeblock>
          <qrheader>
            <description>Scan to join the club&#33;</description>
          </qrheader>
          <qrcodedata>
            <call-to-action>Scan</call-to-action>
            <data>https%3A%2F%2Fwww%2Eadyen%2Ecom%2Fsignup%2F%3Flocation%3Damsterdam%26store%3DStore42%26POSID%3DREG0042%26hash%3DAAhbcdfjkbckjwbnadsjkn4%3D</data>
          </qrcodedata>
          <qrfooter>
            <description>&#91;qr-footer&#93;</description>
          </qrfooter>
        </qrcodeblock>
        <list-header>List header</list-header>
        <!-- a receipt can have 0 or 1 lines element -->
        <lines>
            <!-- the lines element can have 0 or more lineitems -->
            <lineitem>
                <!-- all elements (description, count and amount) are optional -->
                <!-- a lineitem could have attributes in the future, such as "format=emphasis" for bold formatting, or returnitem="true" for a returned item -->
                <description>Running shoes</description>
                <count>2</count>
                <amount>
                    <!-- an amount must have a currency (symbol) and a value -->
                    <currency>$</currency>
                    <value>79.99</value>
                </amount>
            </lineitem>
            <lineitem>
              <count>2</count>
                <description>T-shirt</description>
                <amount>
                    <currency>$</currency>
                    <value>18.99</value>
                </amount>
            </lineitem>
            <lineitem>
                <!-- all elements (description, count and amount) are optional -->
                <!-- a lineitem could have attributes in the future, such as "format=emphasis" for bold formatting, or returnitem="true" for a returned item -->
                <description>Running shoes</description>
                <count>2</count>
                <amount>
                    <!-- an amount must have a currency (symbol) and a value -->
                    <currency>$</currency>
                    <value>79.99</value>
                </amount>
            </lineitem>
            <lineitem>
              <count>2</count>
                <description>T-shirt</description>
                <amount>
                    <currency>$</currency>
                    <value>18.99</value>
                </amount>
            </lineitem>
            <lineitem>
                <!-- all elements (description, count and amount) are optional -->
                <!-- a lineitem could have attributes in the future, such as "format=emphasis" for bold formatting, or returnitem="true" for a returned item -->
                <description>Running shoes</description>
                <count>2</count>
                <amount>
                    <!-- an amount must have a currency (symbol) and a value -->
                    <currency>$</currency>
                    <value>79.99</value>
                </amount>
            </lineitem>
            <lineitem>
              <count>2</count>
                <description>T-shirt</description>
                <amount>
                    <currency>$</currency>
                    <value>18.99</value>
                </amount>
            </lineitem>
            <lineitem>
                <!-- all elements (description, count and amount) are optional -->
                <!-- a lineitem could have attributes in the future, such as "format=emphasis" for bold formatting, or returnitem="true" for a returned item -->
                <description>Running shoes</description>
                <count>2</count>
                <amount>
                    <!-- an amount must have a currency (symbol) and a value -->
                    <currency>$</currency>
                    <value>79.99</value>
                </amount>
            </lineitem>
            <lineitem>
              <count>2</count>
                <description>T-shirt</description>
                <amount>
                    <currency>$</currency>
                    <value>18.99</value>
                </amount>
            </lineitem>
        </lines>
        <!-- a receipt can have 0 or 1 tax element -->
        <tax>
            <!-- a tax element can have 0 or 1 taxtotal element -->
            <taxtotal>
                <!-- description and amount are both optional -->
                <description>tax</description>
                <amount>
                    <currency>$</currency>
                    <value>-1010.14</value>
                </amount>
            </taxtotal>
            <!-- the tax element can have 0 or more taxitems -->
            <taxitem>
                <!-- description and amount are both optional -->
                <description>VAT</description>
                <amount>
                    <currency>$</currency>
                    <value>21.34</value>
                </amount>
            </taxitem>
            <taxitem>
                <description>Seasonal TAX: 1.5%</description>
                <amount>
                    <currency>$</currency>
                    <value>0.80</value>
                </amount>
            </taxitem>
        </tax>
        <!-- a receipt can have 0 or 1 total element -->
        <total>
            <!-- description and amount are both optional -->
            <description>Your total amount</description>
            <amount>
                <currency>$</currency>
                <value>-1079.98</value>
            </amount>
        </total>
        <!-- a receipt can have 0 or 1 subtotal element -->
        <subtotal>
            <!-- description and amount are both optional -->
            <description>subtotal</description>
            <amount>
                <currency>$</currency>
                <value>-1219.98</value>
            </amount>
        </subtotal>
    </receipt>
</screen>

Are you looking for test card numbers?

Would you like to contact support?

Show a virtual receipt on the terminal

Make a display request for a virtual receipt

Receipt XML file

See also