Terminal-2 icon

Ask for phone number input

Use an input request to ask a shopper for their phone number.

Here we describe how you can use an InputRequest 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.

The following illustrations show a digit input screen on a portrait, small portrait, 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 POS app.

Make a PhoneNumber input request

To use the payment terminal to ask for a phone number:

  1. Make a Terminal API input request, specifying:

    • The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Device and MessageCategory set to Input.

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Device
      MessageCategory -white_check_mark- Input
      MessageType -white_check_mark- Request
      ServiceID -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- Your unique ID for the system where you send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • InputRequest.DisplayOutput: This object defines 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.

    • InputRequest.InputData: This object 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.
      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.

  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 numerals (phone number) 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.

  3. Pass the phone number from the DigitInput field to your system for validation and further use.

See also