Ask for numeric input

Here we describe how you can use an InputRequest to ask the shopper or your staff to enter a numerical value. You can use this, for example, to obtain the zip code of a shopper.

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

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 Digit input request

To use the payment terminal to ask for numerical input:

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

   • MessageHeader: The standard SaleToPOIRequest.MessageHeader object. This includes:

     Parameter	Required	Description
     MessageClass		Device
     MessageCategory		Input

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

     Parameter	Required	Description
     Device		CustomerDisplay
     InfoQualify		Display
     OutputContent.OutputFormat		Text
     OutputContent.PredefinedContent.ReferenceID		GetDigit
     OutputContent.OutputText		An array of one Text field containing your own text to show on the terminal. On a portrait display, limited to about 20 characters. 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		CustomerInput
     InfoQualify		Input
     InputCommand		DigitString
     MaxInputTime		(Integer) Time-out in seconds. This is the time that the user gets to finish their input.
     InputData.DefaultInputString		Placeholder text for the input box, to let the user know what input format you are expecting.

   The following example asks the shopper for their zip code.

   https://docs.adyen.com/point-of-sale/shopper-input/digit#shopper-input_4

   • JSON
   • Java

   JSON Java

   {
       "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":"GetDigit"
                       },
                       "OutputText":[
                           {
                               "Text":"Enter your zip code:"
                           }
                       ]
                   }
               },
               "InputData":{
                   "Device":"CustomerInput",
                   "InfoQualify":"Input",
                   "InputCommand":"DigitString",
                   "MaxInputTime":30,
                   "DefaultInputString":"e.g. 10003"
               }
           }
       }
   }

   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("GetDigit");
   outputContent.setPredefinedContent(predefinedContent);
   
   OutputText outputText = new OutputText();
   outputText.setText("Enter your zip code:");
   outputContent.getOutputText().add(outputText);
   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) );
   inputData.setDefaultInputString("e.g. 10003");
   inputRequest.setInputData(inputData);
   saleToPOIRequest.setInputRequest(inputRequest);
   terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

   For a complete list of fields you can pass in a GetDigit 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 numerals that the user entered.
   https://docs.adyen.com/point-of-sale/shopper-input/digit#example-response-when-the-shopper-entered-a-zip-code

   Example response when the shopper entered a zip code

   {
       "SaleToPOIResponse": {
           "InputResponse": {
               "InputResult": {
                   "Device": "CustomerInput",
                   "InfoQualify": "Input",
                   "Response": {
                       "Result": "Success",
                       "AdditionalResponse": "responseData=%7b%20%20%7d"
                   },
                   "Input": {
                       "DigitInput": "94107",
                       "InputCommand": "DigitString"
                   }
               },
               "OutputResult": {
                   "Device": "CustomerDisplay",
                   "InfoQualify": "Display",
                   "Response": {
                       "Result": "Success"
                   }
               }
           },
           "MessageHeader": {...}
       }
   }

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

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

See also