Ask for a rating

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

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:

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

     Parameter	Required	Description
     ProtocolVersion		3.0
     MessageClass		Device
     MessageCategory		Input
     MessageType		Request
     ServiceID		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		Your unique ID for the system where you send this request from.
     POIID		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	GetRating
     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.

   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 input is received from the terminal, the InputResult.Input contains:
     • DigitInput: the numeral that the user entered.

   • 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.

   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