Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Ask for a menu selection

Use an input request to ask multiple choice questions.

Here we describe how you can use an InputRequest to show a menu with various options or a multiple choice question and let the user select an option. You can use this, for example, to create a customer survey.

To use the payment terminal to show a menu with various options:

  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 containing your own text to show on the terminal. Use this to specify the question or menu name.
    • InputRequest.MenuEntry: An array of up to 15 items representing the options to choose from. The terminal shows these items as a scrollable list of boxes 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 three Text fields with your own text that together form the answer or menu option.
      The first Text field will show in bold. Use an empty string for unused Text fields.
      For example, you could write a short-form answer in the first field, the long-form answer in the second field, and not use the third field. Or you could use the three fields for the article name, description, and label.
    • 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.

    The following example asks the shopper to respond to a survey question.

    {
        "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":"How was your visit?"
                            }
                        ]
                    },
                    "MenuEntry":[
                        {
                            "OutputFormat":"Text",
                            "OutputText":[
                                {
                                    "Text":"Excellent"
                                },
                                {
                                    "Text":"Don't change a thing"
                                },
                                {
                                    "Text":""
                                }
                            ]
                        },
                        {
                            "OutputFormat":"Text",
                            "OutputText":[
                                {
                                    "Text":"Great"
                                },
                                {
                                    "Text":"Would surely come again"
                                },
                                {
                                    "Text":""
                                }
                            ]
                        },
                        {
                            "OutputFormat":"Text",
                            "OutputText":[
                                {
                                    "Text":"Good"
                                },
                                {
                                    "Text":"What I expected"
                                },
                                {
                                    "Text":""
                                }
                            ]
                        },
                        {
                            "OutputFormat":"Text",
                            "OutputText":[
                                {
                                    "Text":"Mweh"
                                },
                                {
                                    "Text":"Could have been better"
                                },
                                {
                                    "Text":""
                                }
                            ]
                        },
                        {
                            "OutputFormat":"Text",
                            "OutputText":[
                                {
                                    "Text":"Terrible"
                                },
                                {
                                    "Text":"Will never go here again"
                                },
                                {
                                    "Text":""
                                }
                            ]
                        }
                    ]
                },
                "InputData":{
                    "Device":"CustomerInput",
                    "InfoQualify":"Input",
                    "InputCommand":"GetMenuEntry",
                    "MaxInputTime":120
                }
            }
        }
    }
    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 outputText = new OutputText();
    outputText.setText("How was your visit?");
    outputContent.getOutputText().add(outputText);
    displayOutput.setOutputContent(outputContent);
    
    MenuEntry menuEntry1 = new MenuEntry();
    menuEntry1.setOutputFormat( OutputFormatType.TEXT );
    OutputText option1Line1 = new OutputText();
    option1Line1.setText("Excellent");
    OutputText option1Line2 = new OutputText();
    option1Line2.setText("Don't change a thing");
    OutputText option1Line3 = new OutputText();
    option1Line3.setText("");
    menuEntry1.getOutputText().add(option1Line1);
    menuEntry1.getOutputText().add(option1Line2);
    menuEntry1.getOutputText().add(option1Line3);
    displayOutput.getMenuEntry().add(menuEntry1);
    
    MenuEntry menuEntry2 = new MenuEntry();
    menuEntry2.setOutputFormat( OutputFormatType.TEXT );
    OutputText option2Line1 = new OutputText();
    option2Line1.setText("Great");
    OutputText option2Line2 = new OutputText();
    option2Line2.setText("Would surely come again");
    OutputText option2Line3 = new OutputText();
    option2Line3.setText("");
    menuEntry2.getOutputText().add(option2Line1);
    menuEntry2.getOutputText().add(option2Line2);
    menuEntry2.getOutputText().add(option2Line3);
    displayOutput.getMenuEntry().add(menuEntry2);
    
    MenuEntry menuEntry3 = new MenuEntry();
    menuEntry3.setOutputFormat( OutputFormatType.TEXT );
    OutputText option3Line1 = new OutputText();
    option3Line1.setText("Good");
    OutputText option3Line2 = new OutputText();
    option3Line2.setText("What I expected");
    OutputText option3Line3 = new OutputText();
    option3Line3.setText("");
    menuEntry3.getOutputText().add(option3Line1);
    menuEntry3.getOutputText().add(option3Line2);
    menuEntry3.getOutputText().add(option3Line3);
    displayOutput.getMenuEntry().add(menuEntry3);
    
    MenuEntry menuEntry4 = new MenuEntry();
    menuEntry4.setOutputFormat( OutputFormatType.TEXT );
    OutputText option4Line1 = new OutputText();
    option4Line1.setText("Mweh");
    OutputText option4Line2 = new OutputText();
    option4Line2.setText("Could have been better");
    OutputText option4Line3 = new OutputText();
    option4Line3.setText("");
    menuEntry4.getOutputText().add(option4Line1);
    menuEntry4.getOutputText().add(option4Line2);
    menuEntry4.getOutputText().add(option4Line3);
    displayOutput.getMenuEntry().add(menuEntry4);
    
    MenuEntry menuEntry5 = new MenuEntry();
    menuEntry5.setOutputFormat( OutputFormatType.TEXT );
    OutputText option5Line1 = new OutputText();
    option5Line1.setText("Terrible");
    OutputText option5Line2 = new OutputText();
    option5Line2.setText("Will never go here again");
    OutputText option5Line3 = new OutputText();
    option5Line3.setText("");
    menuEntry5.getOutputText().add(option5Line1);
    menuEntry5.getOutputText().add(option5Line2);
    menuEntry5.getOutputText().add(option5Line3);
    displayOutput.getMenuEntry().add(menuEntry5);
    
    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(120) );
    inputRequest.setInputData(inputData);
    saleToPOIRequest.setInputRequest(inputRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

    For a complete list of fields you can pass in a menu input request, see the Menu InputRequest API reference.

  2. Wait for the user to supply the requested input.

    The provided input is not validated against a format.

    • 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. You receive an InputResponse indicating that the input request was closed.

    • 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 third option was selected, the third item in the array is 1 and all other array items are 0.
    Example response when the shopper selected an option
    {
      "SaleToPOIResponse": {
        "InputResponse": {
          "InputResult": {
            "Device": "CustomerInput",
            "InfoQualify": "Input",
            "Response": {
              "Result": "Success"
            },
            "Input": {
              "MenuEntryNumber": [
                0,
                0,
                1,
                0,
                0
              ],
              "InputCommand": "GetMenuEntry"
            }
          },
          "OutputResult": {
            "Device": "CustomerDisplay",
            "InfoQualify": "Display",
            "Response": {
              "Result": "Success"
            }
          }
        },
        "MessageHeader": {
          "ProtocolVersion": "3.0",
          "SaleID": "POSSystemID12345",
          "MessageClass": "Device",
          "MessageCategory": "Input",
          "ServiceID": "0207111104",
          "POIID": "V400m-324688179",
          "MessageType": "Response"
        }
      }
    }

    For a complete list of fields you can receive in a survey input response, see the Menu InputResponse API reference.

  3. Pass the relevant data from the InputResult to your system for validation and further use.

See also