Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Ask for a rating—single key press

Use an input request with minimal user interaction to gather ratings.

You can gather ratings from your customers using the default GetRating input request. As an alternative, you can use the GetOneKeyRating input request. The main difference is that with GetOneKeyRating, a single key press answers the question:

  • The user presses a key from 0 to 9 on the terminal keypad.
  • Or the user presses Cancel on the keypad or Skip on the terminal display.

After selecting a key, the answer is confirmed automatically, and the user can't go back to change the answer.

Asking for rating with a single key press requires a physical keypad and is currently available on the following terminals: M400, P400 Plus, and V400m.

The following illustrations show the single key press rating screen on a portrait and landscape display.

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

  • The user selects a value from 0 to 9 on the keypad.
  • The maximum input time expires. You can set this time in the request.
  • The user presses Cancel on the keypad or Skip on the terminal display.
  • The terminal receives a request to cancel collecting input or any other request from your POS app.

Make a Rating input request

To use the payment terminal to ask for a rating:

  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 Description
      Device CustomerDisplay
      InfoQualify Display
      OutputContent.OutputFormat Text
      OutputContent.PredefinedContent.ReferenceID GetOneKeyRating
      OutputContent.OutputText 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 Description
      Device CustomerInput
      InfoQualify Input
      InputCommand 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.

    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Device",
                "MessageCategory":"Input",
                "MessageType":"Request",
                "ServiceID":"040",
                "SaleID":"POSSystemID12345",
                "POIID":"V400m-324688179"
            },
            "InputRequest":{
                "DisplayOutput":{
                    "Device":"CustomerDisplay",
                    "InfoQualify":"Display",
                    "OutputContent":{
                        "OutputFormat":"Text",
                        "PredefinedContent":{
                            "ReferenceID":"GetOneKeyRating"
                        },
                        "OutputText":[
                            {
                                "Text":"From 0 to 9 how was your experience with us?"
                            },
                            {
                                "Text": "Poor: 0-3 \n OK: 4-6 \n Great: 7-9"
                            }
                        ]
                    }
                },
                "InputData":{
                    "Device":"CustomerInput",
                    "InfoQualify":"Input",
                    "InputCommand":"DigitString",
                    "MaxInputTime":30
                }
            }
        }
    }
    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("GetOneKeyRating");
    outputContent.setPredefinedContent(predefinedContent);
    
    OutputText questionLine1 = new OutputText();
    questionLine1.setText("From 0 to 9 how was your experience with us?");
    OutputText questionLine2 = new OutputText();
    questionLine2.setText("Poor: 0-3 \n OK: 4-6 \n Great: 7-9");
    outputContent.getOutputText().add(questionLine1);
    outputContent.getOutputText().add(questionLine2);
    displayOutput.setOutputContent(outputContent);
    inputRequest.setDisplayOutput(displayOutput);
    
    InputData inputData = new InputData();
    inputData.setDevice( DeviceType.CUSTOMER_INPUT );
    inputData.setInfoQualify( InfoQualifyType.INPUT );
    inputData.setInputCommand( InputCommandType.DIGIT_STRING );
    inputData.setMaxInputTime( BigInteger.valueOf(30) );
    inputRequest.setInputData(inputData);
    saleToPOIRequest.setInputRequest(inputRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

    For a complete list of fields you can pass in a GetOneKeyRating 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 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": {...}
        }
    }
    • 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 or Skip on the screen), the InputResult.Input.DigitInput field is empty. The InputResult.Response has Result: Failure and ErrorCondition: Cancel.

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

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

See also