--- title: "Ask for phone number input" description: "Use an input request to ask a shopper for their phone number." url: "https://docs.adyen.com/point-of-sale/shopper-engagement/shopper-input/phone-number" source_url: "https://docs.adyen.com/point-of-sale/shopper-engagement/shopper-input/phone-number.md" canonical: "https://docs.adyen.com/point-of-sale/shopper-engagement/shopper-input/phone-number" last_modified: "2025-03-14T16:17:00+01:00" language: "en" --- # Ask for phone number input Use an input request to ask a shopper for their phone number. [View source](/point-of-sale/shopper-engagement/shopper-input/phone-number.md) Here we describe how you can use an input request to ask the shopper to enter their phone number. The country code is prefilled based on the location of the terminal, but can be changed on the terminal. ## 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 **GetPhoneNumber** `InputRequest`, the terminal prompts the shopper or your staff to enter a phone number. 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/e/b/5/8/6/eb5864c171bd3eac47d4a415a1f7e5dc0b075c28-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/c/b/e/0/1/cbe0164bda7078c18458ddb42a4fcbc9a5a85d79-screen-engetphonenumberportrait-small.png) ![](/images/b/c/f/2/c/bcf2cf1b1c4eea2a25d81c0570136030ddad8b0b-screen-engetphonenumberkeyboard.png) ![](/images/4/6/4/8/8/46488c5bf1e784d435f12d685e1fa856432c2c55-screen-engetphonenumberlandscape.png) ## Make a PhoneNumber input request To use the payment terminal to ask for a phone number: 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` | **GetPhoneNumber** | | `OutputContent.OutputText` | An array of one `Text` field containing your own text to show on the terminal. 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 phone number. #### 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":"GetPhoneNumber" }, "OutputText":[ { "Text":"Enter your phone number:" } ] } }, "InputData":{ "Device":"CustomerInput", "InfoQualify":"Input", "InputCommand":"DigitString", "MaxInputTime":40, "DefaultInputString":"0123456789", "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("GetPhoneNumber"); outputContent.setPredefinedContent(predefinedContent); OutputText outputText = new OutputText(); outputText.setText("Enter your phone number:"); 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(40) ); inputData.setDefaultInputString("0123456789"); 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 (phone number) that the user entered. **Example response when the shopper entered a phone number** ```json { "SaleToPOIResponse": { "InputResponse": { "InputResult": { "Device": "CustomerInput", "InfoQualify": "Input", "Input": { "DigitInput": "+31 0690758074", "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 **![](/images/e/b/5/8/6/eb5864c171bd3eac47d4a415a1f7e5dc0b075c28-cancel2x.png)**), the `InputResult.Input.DigitInput` field is empty. The `InputResult.Response` has `Result`: **Failure** and `ErrorCondition`: **Cancel**. 3. Pass the phone number from the `DigitInput` field 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)