Point-of-sale icon

Ask to select a single answer from a list

Use an input request to ask a multiple-choice question and allow a single answer.

Here we describe how you can use an InputRequest to ask the shopper or your staff to select a menu option, such as an answer to a multiple choice question. You can use this, for example, to create a customer survey. You can show a header (your question), and optional second header (for example, an instruction), and up to 15 scrollable option buttons. Each option button can contain one or two text lines.

To allow users to select more than one option, you can use a multiple-answer question.

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 POS app.

Examples

The following illustrations show a menu screen on a portrait, small portrait (e285p), and landscape display.


The following illustrations show a menu screen with a second header line on a portrait, small portrait (e285p), and landscape display.


And finally these illustrations show a menu screen where the option buttons have a second line of text.


We support two MenuButtons input requests:

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

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

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Device
      MessageCategory -white_check_mark- Input
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- 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 -white_check_mark- Your unique ID for the system where you send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

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

      Parameter Description
      Device CustomerDisplay
      InfoQualify Display
      OutputContent.OutputFormat Text
      OutputContent.PredefinedContent.ReferenceID MenuButtons
      OutputContent.OutputText An array of one or two Text fields to specify the header. The second text field is optional; you can omit it from the request.
      For example, you can use the first text field to specify the question or menu name, and the second text field to add an instruction.

    • 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 buttons that the user can tap to select. Each item in the array has:

      Parameter Description
      OutputFormat Text
      OutputText An array of one or two Text fields to specify the answer or menu button. The first text field will show in bold. The second text field is optional; you can omit it from the request.
      For example, you could write a short-form answer in the first field, and the long-form answer in the second field.

    • InputRequest.InputData: this part of the request body handles the user input.

      Parameter Description
      Device CustomerInput
      InfoQualify Input
      InputCommand 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. There is a second header below the question, and the answer options have only one line.

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

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

    The provided input is not validated against a format.

    • If there is input provided to the terminal, the InputResult.Input contains:
      • MenuEntryNumber: an array that indicates the option that the user selected. For example, if the third option is selected, the third item in the array is 1 and all other array items are 0.

    • If the input request times out, the InputResult.Response has AdditionalResponse: message=Screen%20timeout, Result: Failure, and ErrorCondition: Cancel.

    • 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.Response has AdditionalResponse: message=A%20higher%20priority%20request%20has%20been%20received, Result: Failure, and ErrorCondition: Busy.

    • If the user declined to respond (selected the Cancel key ), the InputResult.Input.MenuEntryNumber field is empty. The InputResult.Response has Result: Failure and ErrorCondition: Cancel.

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

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

See also