Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
Point-of-sale 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 the phone number input screen on a portrait display. The second image is for a portrait terminal without keypad (e280).

The next illustrations show the phone number input screen on a small portrait display (e285p) and a 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 PhoneNumber input request

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

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

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

      Parameter Required Description
      Device -white_check_mark- CustomerDisplay
      InfoQualify -white_check_mark- Display
      OutputContent.OutputFormat -white_check_mark- Text
      OutputContent.PredefinedContent.ReferenceID -white_check_mark- GetPhoneNumber
      OutputContent.OutputText -white_check_mark- 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 part of the request body handles the user input:

      Parameter Required Description
      Device -white_check_mark- CustomerInput
      InfoQualify -white_check_mark- Input
      InputCommand -white_check_mark- 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 phone number.

    {
        "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":"0612345678"
                }
            }
        }
    }
    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("0612345678");
    inputRequest.setInputData(inputData);
    saleToPOIRequest.setInputRequest(inputRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

    For a complete list of fields you can pass in the GetPhoneNumber 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, you receive an EventNotification with EventDetails: message=Did+not+receive+a+response+from+the+POI.

    • 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 has Response.Result: Failure, Response.ErrorCondition: Busy, and an AdditionalResponse containing the message A higher priority request has been received.

    • If the user declined to respond (selected the Cancel key ), the InputResult has Response.Result: Failure, Response.ErrorCondition: Cancel, and an empty DigitInput field.

    • If input is received from the terminal, the InputResponse.InputResult contains:
      • Input.DigitInput: The numerals (phone number) that the user entered.
    Example response when the shopper entered a phone number
    {
        "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": {...}
        }
    }

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

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

See also