Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Display data on the terminal

Use display requests to show virtual receipts and other data on the terminal.

Use the DisplayRequest to send data from your cash register to the terminal, to be shown on the terminal screen. For example, you can use it to show a virtual receipt on a large-screen terminal such as the M400. Or you can use it to send a message to the person operating the terminal.

Endpoint

The URL used to send Terminal API messages depends on your type of implementation. For more information on the architectures available, see the Terminal API Overview.

Request

The example below shows the basic fields you specify when making a DisplayRequest call to a Terminal API endpoint.

The SaleID and ServiceID in the MessageHeader should be unique. SaleID and ServiceID combinations are rejected if used recently, within 48 hours.

SaleID and POIID are mandatory.  

You should pass Base64 encoded XML in the OutputXHTML field, and set the OutputFormat to XHTML.

For a complete list of fields you can pass in a display request, see the DisplayRequest API reference.

{  
   "SaleToPOIRequest":{  
      "DisplayRequest":{  
         "DisplayOutput":[  
            {  
               "Device":"CustomerDisplay",
               "InfoQualify":"Display",
               "OutputContent":{  
                  "OutputXHTML": "...paste base64 encoded XML here...",
                  "OutputFormat":"XHTML"
               }
            }
         ]
      },
      "MessageHeader":{  
         "ServiceID":"1116172359",
         "ProtocolVersion":"3.0",
         "MessageClass":"Device",
         "POIID":"MX915-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.setOutputXHTML("...paste base64 encoded XML here...");
outputContent.setOutputFormat( OutputFormatType.XHTML );
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);

Response

For a list of display response fields, see DisplayResponse fields.

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

{  
   "SaleToPOIResponse":{  
      "DisplayResponse":{  
         "OutputResult":[  
            {  
               "InfoQualify":"Display",
               "Device":"CustomerDisplay",
               "Response":{  
                  "Result":"Success"
               }
            }
         ]
      },
      "MessageHeader":{  
         "MessageType":"Response",
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "SaleID":"POSSystemID12345",
         "ServiceID":"1123163504",
         "POIID":"MX925-289173817",
         "ProtocolVersion":"3.0"
      }
   }
}

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

{  
   "SaleToPOIResponse":{  
      "MessageHeader":{  
         "ProtocolVersion":"3.0",
         "ServiceID":"1123161654",
         "SaleID":"POSSystemID12345",
         "MessageClass":"Device",
         "MessageCategory":"Display",
         "MessageType":"Response",
         "POIID":"MX925-289173817"
      },
      "DisplayResponse":{  
         "OutputResult":[  
            {  
               "InfoQualify":"Display",
               "Response":{  
                  "Result":"Failure",
                  "AdditionalResponse":"message=DisplayRequest%20API%20cannot%20be%20used%20for%20this%20terminal%20model.",
                  "ErrorCondition":"NotAllowed"
               },
               "Device":"CustomerDisplay"
            }
         ]
      }
   }
}

Idle the display

Add the following BASE64 encoded xml: 

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4NCjxzY3JlZW4gbmFtZT0iIj4NCiAgDQo8L3NjcmVlbj4NCg==

Example input XML

<?xml version="1.0" encoding="UTF-8"?>

<screen name="virtual_receipt02.xslt">

    <receipt>

        <!-- 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>

                <description>T-shirt</description>

                <amount>

                    <currency>$</currency>

                    <value>18.99</value>

                </amount>

            </lineitem>

<lineitem>

            <description>Loyalty discount: 5%</description>

            <amount>

                        <!-- an amount must have a currency (symbol) and

a value -->

                <currency>$</currency>

                <value>-4.48</value>

            </amount>

        </lineitem>

        <lineitem>

            <description>Just stating something!</description>

        </lineitem>

        <lineitem>

            <description></description><!-- an empty line does not work

out of the box -->

        </lineitem>

        <lineitem>

            <description>***** RETURNS *****</description>

        </lineitem>

        <lineitem>

            <count>1</count>

            <description>grey t-shirt @ 12.99</description>

            <amount>

                <currency>$</currency>

                <value>-12.99</value>

            </amount>

        </lineitem>

        <lineitem>

            <description>____________________</description>

        </lineitem>

        <lineitem>

            <description>***** SALES *****</description>

        </lineitem>

        <lineitem>

            <count>4</count>

            <description>black t-shirt @ 12.99</description>

            <amount>

                <currency>$</currency>

                <value>51.96</value>

            </amount>

        </lineitem>

        <lineitem>

            <count>1</count>

            <description>white sweater @ 29.99</description>

            <amount>

                <currency>$</currency>

                <value>29.99</value>

            </amount>

        </lineitem>

        <lineitem>

            <count>2</count>

            <description>red socks @ 9.99</description>

            <amount>

                <currency>$</currency>

                <value>19.98</value>

            </amount>

        </lineitem>

        <lineitem>

            <count>4</count>

            <description>black t-shirt @ 12.99</description>

            <amount>

                <currency>$</currency>

                <value>51.96</value>

            </amount>

        </lineitem>

        <lineitem>

            <count>1</count>

            <description>white sweater @ 29.99</description>

            <amount>

                <currency>$</currency>

                <value>29.99</value>

            </amount>

        </lineitem>

        <lineitem>

            <count>2</count>

            <description>red socks @ 9.99</description>

            <amount>

                <currency>$</currency>

                <value>19.98</value>

            </amount>

        </lineitem>

        <lineitem>

            <count>4</count>

            <description>black t-shirt @ 12.99</description>

            <amount>

                <currency>$</currency>

                <value>51.96</value>

            </amount>

        </lineitem>

        <lineitem>

            <count>1</count>

            <description>white sweater @ 29.99</description>

            <amount>

                <currency>$</currency>

                <value>29.99</value>

            </amount>

        </lineitem>

        <lineitem>

            <count>2</count>

            <description>red socks @ 9.99</description>

            <amount>

                <currency>$</currency>

                <value>19.98</value>

            </amount>

        </lineitem>

            <!-- an empty lineitem would result in a blank line (taking up vertical space) -->

            <lineitem />

            <lineitem>

                <description>Thanks for shopping with us!</description>

            </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>