Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Point-of-sale icon

Ask for a rating

Use an input request to ask a shopper for a rating from 0 to 10.

Here we describe how you can use an InputRequest to ask the shopper or your staff to enter a numerical value from 0 to 10. You can use this, for example, to conduct a Net Promoter Score (NPS) survey.

The following illustrations show a rating input screen on a portrait and landscape display.

On a small portrait display, the information is divided over two screens. The user needs to select Enter rating before entering a value using the keypad.

On a portrait terminal without keypad, an on-screen keyboard appears after the user selects Enter rating.

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.

Make a Rating input request

To use the payment terminal to ask for a rating from 0 to 10:

  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- GetRating
      OutputContent.OutputText -white_check_mark- An array of one or two Text fields containing your own text to show on the terminal. The first text is shown in bold. Use \n for a new line. Apart from the text you specify, the terminal will show an instruction for how to confirm the input.
    • 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- DigitString
      MaxInputTime (Integer) Time-out in seconds. This is the time that the user gets to finish their input.

    The following example asks the shopper for a rating using the first Text field for the core question and the second Text field to explain the scoring.

                                "Text":"How was your experience with us?"
                                "Text": "Poor: 0-3 \n OK: 4-6 \n Great: 7-9"
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new 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();
    OutputText questionLine1 = new OutputText();
    questionLine1.setText("How was your experience with us?");
    OutputText questionLine2 = new OutputText();
    questionLine2.setText("Poor: 0-3 \n OK: 4-6 \n Great: 7-9");
    InputData inputData = new InputData();
    inputData.setDevice( DeviceType.CUSTOMER_INPUT );
    inputData.setInfoQualify( InfoQualifyType.INPUT );
    inputData.setInputCommand( InputCommandType.DIGIT_STRING );
    inputData.setMaxInputTime( BigInteger.valueOf(30) );

    For a complete list of fields you can pass in a GetRating 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 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.DigitInput field is empty. The InputResult.Response has Result: Failure and ErrorCondition: Cancel.

    • If input is received from the terminal, the InputResult.Input contains:
      • DigitInput: The numeral that the user entered.
    Example response when the shopper entered a rating of 9
        "SaleToPOIResponse": {
            "InputResponse": {
                "InputResult": {
                    "Device": "CustomerInput",
                    "InfoQualify": "Input",
                    "Input": {
                        "DigitInput": "9",
                        "InputCommand": "DigitString"
                    "Response": {
                        "AdditionalResponse": "responseData=%7b%20%20%7d",
                        "Result": "Success",
                "OutputResult": {
                    "Device": "CustomerDisplay",
                    "InfoQualify": "Display",
                    "Response": {
                        "Result": "Success"
            "MessageHeader": {...}

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

  3. Pass the DigitInput value to your system for validation and further use.

See also