Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Ask to select one or more answers from a list

Use an input request to ask a multiple-choice question and allow more than one answer.

We describe here how you can use an InputRequest to ask the shopper a question and allow them to select more than one answer. You can use this, for example, to create a customer survey. You can show a header (your question) and up to 15 scrollable option buttons. Each option button can contain one text line.

To allow users to only select one option, you can use a single-answer question.

This example shows a list where the shopper can select more than one of the answers on a portrait, small portrait (e285p), and landscape display


The terminal continues to show your input request until one of these events occurs:

  • The user has provided input.
  • The maximum input time expires. You can set this time in the request.
  • On the terminal, Cancel is selected.
  • The terminal receives a request to cancel collecting input or any other request from the cash register.

We support two MenuButtons input requests:

To enable the selection of multiple answers, your request needs to include the MinLength or MaxLength parameters. However, the values used for these parameters are currently not enforced.

To use the payment terminal to show a menu that allows the user to select more than one option:

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

    • InputRequest.DisplayOutput: This part of the request body defines what is shown on the terminal:

      Parameter Required Description
      Device -white_check_mark- CustomerDisplay
      InfoQualify -white_check_mark- Display
      OutputContent.OutputFormat -white_check_mark- Text
      OutputContent.PredefinedContent.ReferenceID -white_check_mark- MenuButtons
      OutputContent.OutputText -white_check_mark- An array of one Text field to specify the header. For example, to ask a multiple-choice question.}
    • InputRequest.MenuEntry: The terminal shows these items as a scrollable list of buttons that the user can tap to select. Each item in the array has:

      Parameter Required Description
      OutputFormat -white_check_mark- Text
      OutputText -white_check_mark- An array of one Text field to specify the answer or menu button.
    • InputRequest.InputData: This part of the request body handles the user input:

      Parameter Required Description
      Device -white_check_mark- CustomerInput
      InfoQualify -white_check_mark- Input
      InputCommand -white_check_mark- GetMenuEntry
      MaxInputTime (Integer) Time-out in seconds. This is the time that the user gets to finish their input.
      MinLength -white_check_mark- The minimum number of options the user must select.
      MaxLength -white_check_mark- The maximum number of options the user is allowed to select.

To allow selecting multiple answers, you must include the MinLength or MaxLength parameters in the request body. However, the parameter values are not enforced.

The following example asks the shopper to select options from a list.

{
    "SaleToPOIRequest":{
        "MessageHeader":{
            "ProtocolVersion":"3.0",
            "MessageClass":"Device",
            "MessageCategory":"Input",
            "MessageType":"Request",
            "ServiceID":"0207111104",
            "SaleID":"POSSystemID12345",
            "POIID":"V400m-324688179"
        },
        "InputRequest":{
            "DisplayOutput":{
                "Device":"CustomerDisplay",
                "InfoQualify":"Display",
                "OutputContent":{
                    "OutputFormat":"Text",
                    "PredefinedContent":{
                        "ReferenceID":"MenuButtons"
                    },
                    "OutputText":[
                        {
                            "Text": "Subscribe to the following channels?"
                        }
                    ]
                },
                "MenuEntry": [
                    {
                        "OutputFormat": "Text",
                        "OutputText": [
                            {
                                "Text": "Email"
                            }
                        ]
                    },
                    {
                        "OutputFormat": "Text",
                        "OutputText": [
                            {
                                "Text": "SMS"
                            }
                        ]
                    },
                    {
                        "OutputFormat": "Text",
                        "OutputText": [
                            {
                                "Text": "Post"
                            }
                        ]
                    }
                ]
            },
            "InputData": {
                "Device": "CustomerInput",
                "InfoQualify": "Input",
                "InputCommand": "GetMenuEntry",
                "MaxInputTime": 60,
                "MinLength": 0,
                "MaxLength": 3
            }
        }
    }
}
SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
MessageHeader messageHeader = new MessageHeader();
saleToPOIRequest.setMessageHeader(messageHeader);

InputRequest inputRequest = new InputRequest();
DisplayOutput displayOutput = new DisplayOutput();
displayOutput.setDevice( DeviceType.CUSTOMER_DISPLAY );
displayOutput.setInfoQualify( InfoQualifyType.DISPLAY );
OutputContent outputContent = new OutputContent();
outputContent.setOutputFormat( OutputFormatType.TEXT );
PredefinedContent predefinedContent = new PredefinedContent();
predefinedContent.setReferenceID("MenuButtons");
outputContent.setPredefinedContent(predefinedContent);
OutputText headerLine1 = new OutputText();
headerLine1.setText("Subscribe to the following channels?");
outputContent.getOutputText().add(headerLine1);
displayOutput.setOutputContent(outputContent);

MenuEntry menuEntry1 = new MenuEntry();
menuEntry1.setOutputFormat( OutputFormatType.TEXT );
OutputText option1Line1 = new OutputText();
option1Line1.setText("Email");
menuEntry1.getOutputText().add(option1Line1);
displayOutput.getMenuEntry().add(menuEntry1);

MenuEntry menuEntry2 = new MenuEntry();
menuEntry2.setOutputFormat( OutputFormatType.TEXT );
OutputText option2Line1 = new OutputText();
option2Line1.setText("SMS");
menuEntry2.getOutputText().add(option2Line1);
displayOutput.getMenuEntry().add(menuEntry2);

MenuEntry menuEntry3 = new MenuEntry();
menuEntry3.setOutputFormat( OutputFormatType.TEXT );
OutputText option3Line1 = new OutputText();
option3Line1.setText("Post");
menuEntry3.getOutputText().add(option3Line1);
displayOutput.getMenuEntry().add(menuEntry3);

inputRequest.setDisplayOutput(displayOutput);

InputData inputData = new InputData();
inputData.setDevice( DeviceType.CUSTOMER_INPUT );
inputData.setInfoQualify( InfoQualifyType.INPUT );
inputData.setInputCommand( InputCommandType.GET_MENU_ENTRY );
inputData.setMaxInputTime( BigInteger.valueOf(60) );
inputData.setMinLength( Integer.valueOf(0) );
inputData.setMaxLength( Integer.valueOf(3) );
inputRequest.setInputData(inputData);
saleToPOIRequest.setInputRequest(inputRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);
  1. Wait for the user to supply the requested input.

    • If the input request times out, you receive an EventNotification with EventDetails: message=Did+not+receive+a+response+from+the+POI.

    • If you make a payment request while the input request is waiting for input on the terminal, the payment request overrides the input request. The InputResult has Response.Result: Failure, Response.ErrorCondition: Busy, and an AdditionalResponse containing the message A higher priority request has been received.

    • If the user declined to respond (selected the Cancel key ), the InputResult has Response.Result: Failure and Response.ErrorCondition: Cancel.

    • If input is received from the terminal, the InputResponse has an InputResult with:
      • Input.MenuEntryNumber: Array that indicates the option that the user selected. For example, if the shopper selected the first and third options , the first and third items in the array are 1 and all other array items are 0.
      • Additional Response: Contains the warning outputTextWarning=The%20number%20of%20usable%20button%20text%20fields%20is%20three which you can ignore.
    Example response when the shopper selects the first and third options
    {
        "SaleToPOIResponse": {
            "InputResponse": {
                "InputResult": {
                    "Device": "CustomerInput",
                    "InfoQualify": "Input",
                    "Input": {
                        "InputCommand": "GetMenuEntry",
                        "MenuEntryNumber": [
                            1,
                            0,
                            1
                        ]
                    },
                    "Response": {
                        "AdditionalResponse": "outputTextWarning=The%20number%20of%20usable%20button%20text%20fields%20is%20three.",
                        "Result": "Success"
                    }
                },
                "OutputResult": {
                    "Device": "CustomerDisplay",
                    "InfoQualify": "Display",
                    "Response": {
                        "Result": "Success"
                    }
                }
            },
            "MessageHeader": {
                "ProtocolVersion":"3.0",
                "MessageClass":"Device",
                "MessageCategory":"Input",
                "MessageType":"Request",
                "ServiceID":"0207111104",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-324688179"
            }
        }
    }
  2. Pass the relevant data from InputResult.Input to your system for validation and further use.

See also