--- title: "Ask for numeric input" description: "Use an input request to ask a shopper for numeric input." url: "https://docs.adyen.com/point-of-sale/shopper-engagement/shopper-input/digit" source_url: "https://docs.adyen.com/point-of-sale/shopper-engagement/shopper-input/digit.md" canonical: "https://docs.adyen.com/point-of-sale/shopper-engagement/shopper-input/digit" last_modified: "2026-05-25T12:55:00+02:00" language: "en" --- # Ask for numeric input Use an input request to ask a shopper for numeric input. [View source](/point-of-sale/shopper-engagement/shopper-input/digit.md) Here we describe how you can use an input request 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. ## Requirements Before you begin, take into account the following requirement. | Requirement | Description | | -------------------- | -------------------------------------------------------------------------------- | | **Integration type** | A [Terminal API integration](/point-of-sale/get-started) with payment terminals. | ## How it works When you use a **GetDigit** `InputRequest`, the terminal prompts the shopper or your staff to enter a numerical value. 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** **![](/images/3/b/6/5/7/3b657d104227ab25898170e9a0479e90f2e27867-cancel2x.png)** is selected. * The terminal receives a [request to cancel collecting input](/point-of-sale/shopper-engagement/shopper-input/cancel-input) or any other request from the POS app. ### Examples The following illustrations show a digit input screen on a portrait, small portrait, and landscape display. ![](/images/b/d/1/1/7/bd11715d0379e210cc615c75c0c704c4eeb6b176-screen-engetdigitportrait.png) ![](/images/c/5/d/6/f/c5d6f71691c9954c14485f1e4d603fb511a3d643-screen-engetdigitportrait-small.png) ![](/images/d/9/1/8/1/d91810831ab829413cda81ae2e4dacd764160a0f-screen-engetdigitlandscape.png) ## Make a Digit input request To use the payment terminal to ask for numerical input: 1. Make a [Terminal API](/point-of-sale/design-your-integration/terminal-api) input request, specifying: * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Device** and `MessageCategory` set to **Input**. | Parameter | Required | Description | | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0** | | `MessageClass` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Device** | | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Input** | | `MessageType` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request** | | `ServiceID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the system where you send this request from. | | `POIID` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*. | - The [InputRequest.DisplayOutput](https://docs.adyen.com/api-explorer/terminal-api/latest/post/input#request-DisplayOutput) object to define what is shown on the terminal: | Parameter | 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. | - The [InputRequest.InputData](https://docs.adyen.com/api-explorer/terminal-api/latest/post/input#request-InputData) object to handle 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. | | `DefaultInputString` | Placeholder text for the input box, to let the user know what input format you are expecting. | | `MaskChararctersFlag` | Mask user input. Allowed values are **true** and **false**. | The following example asks the shopper for their zip code. #### JSON ```json { "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", "MaskCharactersFlag": true } } } } ``` #### Java ```java 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); ``` 2. Wait for the user to supply the requested input. The input is not validated against a format. If input is received from the terminal, the input response includes an [InputResult](https://docs.adyen.com/api-explorer/terminal-api/latest/post/input#responses-200-InputResult) object with: * `Input.DigitInput`: The numerals that the user entered. **Example response when the shopper entered a zip code** ```json { "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": {...} } } ``` * 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 **![](/images/3/b/6/5/7/3b657d104227ab25898170e9a0479e90f2e27867-cancel2x.png)**), the `InputResult.Input.DigitInput` field is empty. The `InputResult.Response` has `Result`: **Failure** and `ErrorCondition`: **Cancel**. 3. Pass `DigitInput` value to your system for validation and further use. ## See also * [Cancel an input request](/point-of-sale/shopper-engagement/shopper-input/cancel-input) * [Ask for another type of input](/point-of-sale/shopper-engagement/shopper-input/select-input-request) * [Create a session](/point-of-sale/shopper-engagement/create-session)