Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Collect input

Learn how to use the payment terminal to collect input from your customers or staff.

In addition to making payments, Adyen's point of sale terminals can request input from your shopper or staff. This allows you to collect the shopper's email address for example, or perform a survey. The communication flow is between your cash register and the terminal, and does not involve the Adyen backend. You need to process the collected input with your own business logic.

There are several types of InputRequest:

  • Confirmation - Show some information and ask the shopper to confirm they agree.
  • Signature - Show some information and ask the shopper to confirm by supplying their signature.
  • Menu - Show a multiple choice question and let the user select one of the answers. You can use this for NPS surveys, order lists, and such.
  • Numeric - You'd typically use this to ask the shopper for their phone number. Another example is a pay-at-table flow where you ask your staff for the table number.
  • Text - You'd typically use this to ask the shopper for their email address.

For each input type, we provide predefined elements to show on the terminal display, and fields that you need to populate with your own text. The user enters a response with the terminal keypad or the on-screen keyboard and buttons.

You cannot use shopper input requests on (legacy) terminals that do not support Terminal API or on terminals that support only a subset of Terminal API.

Collect user input

This is the general procedure for asking the shopper or your staff a question and collecting the reply. Refer to the input types for specific details.

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

    • MessageHeader object: This follows the standard MessageHeader structure, explained in Terminal API fundamentals:

      • ProtocolVersion: 3.0
      • MessageClass: Device
      • MessageCategory: Input
      • MessageType: Request
      • SaleID: Your unique ID for the cash register.
      • ServiceID: Your unique ID for the transaction attempt, consisting of 1-10 alphanumeric characters. This value needs to be unique within the last 48 hours.
      • POIID: Unique ID of the terminal.¬†This indicates which terminal the payment will be routed to.

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

      • Device: CustomerDisplay
      • InfoQualify: Display
      • OutputContent.OutputFormat: Text.
      • OutputContent.PredefinedContent.ReferenceID: The set of predefined elements you want to use:

        • GetConfirmation: predefined elements to ask for confirmation.
        • GetSignature: predefined elements to ask for a signature.
        • MenuButtons: predefined elements to let the user select an answer.
        • GetDigit: predefined elements to ask for numeric input.
        • GetText: predefined elements to ask for text input.

      • OutputContent.OutputText: An array of one or more Text fields containing your own text to show on the terminal. Refer to the input types below to learn how to use these fields.

    • InputRequest.InputData: This part of the request body handles the user input:

      • Device: CustomerInput.
      • InfoQualify: Input.
      • InputCommand: Command for handling the user input type:

      • MaxInputTime: Time-out in seconds. This is the time that the user gets to finish their input.

    The following example shows the common fields for all input types.

    {
         "SaleToPOIRequest": {
           "MessageHeader": {
             "ProtocolVersion": "3.0",
             "MessageClass": "Device",
             "MessageCategory": "Input",
             "MessageType": "Request",
             "ServiceID": "0207111104",
             "SaleID": "POSSystemID12345",
             "POIID": "V400m-324688179"
           },
           "InputRequest": {
             "DisplayOutput": {
               "Device": "CustomerDisplay",
               "InfoQualify": "Display",
               "OutputContent": {
                 "OutputFormat": "Text",
                 "PredefinedContent": {
                   "ReferenceID": "PREDEFINED_ELEMENTS_ID"
                 },
                 "OutputText": [
                   {"Text": "Your own text"}
                 ]
               }
             },
             "InputData": {
               "Device": "CustomerInput",
               "InfoQualify": "Input",
               "InputCommand": "INPUT_TYPE",
               "MaxInputTime": 30
             }
           }
         }
       }
    String serviceID = "YOUR_UNIQUE_ATTEMPT_ID";
    String saleID = "YOUR_CASH_REGISTER_ID";
    String POIID = "YOUR_TERMINAL_ID";
    
    SaleToPOIRequest saleToPOIRequest = new SaleToPOIRequest();
    MessageHeader messageHeader = new MessageHeader();
    messageHeader.setProtocolVersion("3.0");
    messageHeader.setMessageClass( MessageClassType.DEVICE );
    messageHeader.setMessageCategory( MessageCategoryType.INPUT );
    messageHeader.setMessageType( MessageType.REQUEST );
    messageHeader.setServiceID(serviceID);
    messageHeader.setSaleID(saleID);
    messageHeader.setPOIID(POIID);
    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("PREDEFINED_ELEMENTS_ID");
    outputContent.setPredefinedContent(predefinedContent);
    
    OutputText outputText = new OutputText();
    outputText.setText("Your own text");
    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.INPUT_TYPE );
    inputData.setMaxInputTime( BigInteger.valueOf(30) );
    inputRequest.setInputData(inputData);
    saleToPOIRequest.setInputRequest(inputRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

    Some input types require additional fields or specific values. Refer to the input types below.

  2. Wait for the user to supply the requested input using the on-screen keyboard and buttons or the terminal keypad.

    The input supplied by the shopper or your staff is not validated against a format.

    In the response, the InputResult shows whether the user agreed or disagreed, provided a signature, selected an answer to the multiple choice question, entered numerals or text, or declined to provide input.
    If the request timed out, the response will contain an EventNotification with EventDetails: message=Did+not+receive+a+response+from+the+POI.

  3. Pass the relevant data from the InputResult to your system for validation and further use.

Confirmation

In an InputRequest asking the shopper to confirm something, you need to specify the common fields for collecting user input as well as the following specific values and fields:

  • DisplayOutput.OutputContent.PredefinedContent.ReferenceID: GetConfirmation.
  • DisplayOutput.OutputContent.OutputText: An array of four Text fields containing your own text to show on the terminal.

    1. The first Text field is the title.
    2. The second Text fields represents additional text which can be long and is scrollable.
    3. The third Text field is the label for the 'decline' button on the left.
    4. The fourth Text field is the label for the 'agree' button on the right.

  • InputData.InputCommand: GetConfirmation

The following example asks the shopper to confirm they agree.

{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "GetConfirmation"
          },
          "OutputText": [
            {"Text": "Do you accept our Terms and Conditions?"},
            {"Text": "The full Terms and Conditions are available on our website."},
            {"Text": "No"},
            {"Text": "Yes"}
          ]
        }
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "GetConfirmation",
        "MaxInputTime": 30
      }
    }
  }
}
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("GetConfirmation");
outputContent.setPredefinedContent(predefinedContent);

OutputText title = new OutputText();
title.setText("Do you accept our Terms and Conditions?");
OutputText additionalText = new OutputText();
additionalText.setText("The full Terms and Conditions are available on our website.");
OutputText declineAnswer = new OutputText();
declineAnswer.setText("NO");
OutputText agreeAnswer = new OutputText();
agreeAnswer.setText("YES");
outputContent.getOutputText().add(title);
outputContent.getOutputText().add(additionalText);
outputContent.getOutputText().add(declineAnswer);
outputContent.getOutputText().add(agreeAnswer);
displayOutput.setOutputContent(outputContent);
inputRequest.setDisplayOutput(displayOutput);

InputData inputData = new InputData();
inputData.setDevice( DeviceType.CUSTOMER_INPUT );
inputData.setInfoQualify( InfoQualifyType.INPUT );
inputData.setInputCommand( InputCommandType.GET_CONFIRMATION );
inputData.setMaxInputTime( BigInteger.valueOf(30) );
inputRequest.setInputData(inputData);
saleToPOIRequest.setInputRequest(inputRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

For a complete list of fields you can pass in a confirmation input request, see the ConfirmationEntry InputRequest API reference.

In the response, ConfirmedFlag: true indicates the shopper tapped the 'agree' button on the right or pressed to confirm their agreement. ConfirmedFlag: false means the shopper tapped the 'decline' button on the left or pressed .

Example response when the shopper confirmed
{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560867383%22%20%7d"
        },
        "Input": {
          "ConfirmedFlag": true,
          "InputCommand": "GetConfirmation"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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

Signature

In an InputRequest asking the shopper to sign for something and confirm, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • DisplayOutput.OutputContent.PredefinedContent.ReferenceID: GetSignature. Apart from the text you specify, the terminal will show an input box for the shopper to draw their signature.
  • DisplayOutput.OutputContent.OutputText: An array of four Text fields containing your own text to show on the terminal.

    1. The first Text field is the title.
    2. The second Text field contains additional information.
    3. The third Text field is the label for the 'decline' button on the left.
    4. The fourth Text field is the label for the 'agree' button on the right.

  • InputData.InputCommand: GetConfirmation

The following example asks the shopper for their signature.

{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "GetSignature"
          },
          "OutputText": [
            {"Text": "Do you accept the Delivery Waver Form?"},
            {"Text": "Please Sign"},
            {"Text": "No"},
            {"Text": "Yes"}
          ]
        }
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "GetConfirmation",
        "MaxInputTime": 30
      }
    }
  }
}
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("GetSignature");
outputContent.setPredefinedContent(predefinedContent);

OutputText title = new OutputText();
title.setText("Do you accept the Delivery Waver Form?");
OutputText additionalText = new OutputText();
additionalText.setText("Please Sign");
OutputText declineAnswer = new OutputText();
declineAnswer.setText("NO");
OutputText agreeAnswer = new OutputText();
agreeAnswer.setText("YES");
outputContent.getOutputText().add(title);
outputContent.getOutputText().add(additionalText);
outputContent.getOutputText().add(declineAnswer);
outputContent.getOutputText().add(agreeAnswer);
displayOutput.setOutputContent(outputContent);
inputRequest.setDisplayOutput(displayOutput);

InputData inputData = new InputData();
inputData.setDevice( DeviceType.CUSTOMER_INPUT );
inputData.setInfoQualify( InfoQualifyType.INPUT );
inputData.setInputCommand( InputCommandType.GET_CONFIRMATION );
inputData.setMaxInputTime( BigInteger.valueOf(30) );
inputRequest.setInputData(inputData);
saleToPOIRequest.setInputRequest(inputRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

For a complete list of fields you can pass in a signature input request, see the SignatureEntry InputRequest API reference.

In the response, the AdditionalResponse contains the signature provided by the shopper. ConfirmedFlag: true indicates the shopper tapped the 'agree' button on the right or pressed to confirm their agreement. ConfirmedFlag: false means the shopper tapped the 'decline' button on the left or pressed .

Example response when the shopper supplied a signature
{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560864516%22%2c%20%22signature%22%3a%20%7b%20%22data%22%3a%20%5b%20%7b%20%22x%22%3a%20%2249%22%2c%20%22y...signature_format%22%3a%20%22raw%22%20%7d%20%7d"
        },
        "Input": {
          "ConfirmedFlag": true,
          "InputCommand": "GetConfirmation"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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

Menu selection

In an InputRequest asking the shopper to answer a multiple choice question, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • DisplayOutput.OutputContent.PredefinedContent.ReferenceID: MenuButtons. The terminal shows the answers to choose from as a scrollable list of boxes that the user can tap to select.
  • DisplayOutput.OutputContent.OutputText: An array of only one Text field containing your own text to show on the terminal. Use this to specify the question.
  • MenuEntry: An array of up to 15 items representing the answers to choose from. Each answer has:

    • OutputFormat: Text
    • OutputText: an array of three Text fields with your own text that together form the answer.
      The first Text field will show in bold. Use an empty string for unused Text fields.
      For example, you could write a short-form answer in the first field, the long-form answer in the second field, and not use the third field. Or you could use the three fields for the article name, description, and label.

  • InputData.InputCommand: GetMenuEntry

The following example asks the shopper to respond to a survey question.

{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "MenuButtons"
          },
          "OutputText": [
            {"Text": "How was your visit?"}
          ]
        },
        "MenuEntry": [
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Excellent"},
              {"Text": "Don't change a thing"},
              {"Text": ""}
            ]
          },
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Great"},
              {"Text": "Would surely come again"},
              {"Text": ""}
            ]
          },
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Good"},
              {"Text": "What I expected"},
              {"Text": ""}
            ]
          },
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Mweh"},
              {"Text": "Could have been better"},
              {"Text": ""}
            ]
          },
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Terrible"},
              {"Text": "Will never go here again"},
              {"Text": ""}
            ]
          }
        ]
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "GetMenuEntry",
        "MaxInputTime": 120
      }
    }
  }
}
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("MenuButtons");
outputContent.setPredefinedContent(predefinedContent);

OutputText outputText = new OutputText();
outputText.setText("How was your visit?");
outputContent.getOutputText().add(outputText);
displayOutput.setOutputContent(outputContent);

MenuEntry menuEntry1 = new MenuEntry();
menuEntry1.setOutputFormat( OutputFormatType.TEXT );
OutputText option1Line1 = new OutputText();
option1Line1.setText("Excellent");
OutputText option1Line2 = new OutputText();
option1Line2.setText("Don't change a thing");
OutputText option1Line3 = new OutputText();
option1Line3.setText("");
menuEntry1.getOutputText().add(option1Line1);
menuEntry1.getOutputText().add(option1Line2);
menuEntry1.getOutputText().add(option1Line3);
displayOutput.getMenuEntry().add(menuEntry1);

MenuEntry menuEntry2 = new MenuEntry();
menuEntry2.setOutputFormat( OutputFormatType.TEXT );
OutputText option2Line1 = new OutputText();
option2Line1.setText("Great");
OutputText option2Line2 = new OutputText();
option2Line2.setText("Would surely come again");
OutputText option2Line3 = new OutputText();
option2Line3.setText("");
menuEntry2.getOutputText().add(option2Line1);
menuEntry2.getOutputText().add(option2Line2);
menuEntry2.getOutputText().add(option2Line3);
displayOutput.getMenuEntry().add(menuEntry2);

MenuEntry menuEntry3 = new MenuEntry();
menuEntry3.setOutputFormat( OutputFormatType.TEXT );
OutputText option3Line1 = new OutputText();
option3Line1.setText("Good");
OutputText option3Line2 = new OutputText();
option3Line2.setText("What I expected");
OutputText option3Line3 = new OutputText();
option3Line3.setText("");
menuEntry3.getOutputText().add(option3Line1);
menuEntry3.getOutputText().add(option3Line2);
menuEntry3.getOutputText().add(option3Line3);
displayOutput.getMenuEntry().add(menuEntry3);

MenuEntry menuEntry4 = new MenuEntry();
menuEntry4.setOutputFormat( OutputFormatType.TEXT );
OutputText option4Line1 = new OutputText();
option4Line1.setText("Mweh");
OutputText option4Line2 = new OutputText();
option4Line2.setText("Could have been better");
OutputText option4Line3 = new OutputText();
option4Line3.setText("");
menuEntry4.getOutputText().add(option4Line1);
menuEntry4.getOutputText().add(option4Line2);
menuEntry4.getOutputText().add(option4Line3);
displayOutput.getMenuEntry().add(menuEntry4);

MenuEntry menuEntry5 = new MenuEntry();
menuEntry5.setOutputFormat( OutputFormatType.TEXT );
OutputText option5Line1 = new OutputText();
option5Line1.setText("Terrible");
OutputText option5Line2 = new OutputText();
option5Line2.setText("Will never go here again");
OutputText option5Line3 = new OutputText();
option5Line3.setText("");
menuEntry5.getOutputText().add(option5Line1);
menuEntry5.getOutputText().add(option5Line2);
menuEntry5.getOutputText().add(option5Line3);
displayOutput.getMenuEntry().add(menuEntry5);

inputRequest.setDisplayOutput(displayOutput);

InputData inputData = new InputData();
inputData.setDevice( DeviceType.CUSTOMER_INPUT );
inputData.setInfoQualify( InfoQualifyType.INPUT );
inputData.setInputCommand( InputCommandType.GET_MENU_ENTRY );
inputData.setMaxInputTime( BigInteger.valueOf(120) );
inputRequest.setInputData(inputData);
saleToPOIRequest.setInputRequest(inputRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

For a complete list of fields you can pass in a menu input request, see the MenuEntry InputRequest API reference.

In the response, the MenuEntryNumber array indicates the answer that the user selected. For example, if the third answer was selected, the third item in the array is 1 and all other array items are 0.
If the user declined to answer (pressed ), the InputResult has Response.Result: Failure and Response.ErrorCondition: Cancel.

Example response when the shopper selected an answer option
{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560869035%22%20%7d"
        },
        "Input": {
          "MenuEntryNumber": [
            0,
            0,
            1,
            0,
            0
          ],
          "InputCommand": "GetMenuEntry"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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

Numeric input

In an InputRequest asking the shopper to enter numerals, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • DisplayOutput.OutputContent.PredefinedContent.ReferenceID: GetDigit. Apart from the text you specify, the terminal will show an instruction for how to confirm the input.
  • DisplayOutput.OutputContent.OutputText: An array of only one Text field containing your own text to show on the terminal.
  • InputData.InputCommand: DigitString
  • 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": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "GetDigit"
          },
          "OutputText": [
            {"Text": "Please enter your phone number"}
          ]
        }
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "DigitString",
        "MaxInputTime": 30,
        "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("GetDigit");
outputContent.setPredefinedContent(predefinedContent);

OutputText outputText = new OutputText();
outputText.setText("Please 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(30) );
inputData.setDefaultInputString("0612345678");
inputRequest.setInputData(inputData);
saleToPOIRequest.setInputRequest(inputRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

For a complete list of fields you can pass in a numeric input request, see the DigitEntry InputRequest API reference.

In the response, the DigitInput field contains the numerals that the user entered. If the user declined to provide input (pressed ), the InputResult has Response.Result: Failure, Response.ErrorCondition: Cancel, and an empty DigitInput field.

Example response when the shopper entered a phone number
{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560761701%22%20%7d"
        },
        "Input": {
          "DigitInput": "0687164125",
          "InputCommand": "DigitString"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
         }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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

Text input

In an InputRequest asking the user to enter text, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • DisplayOutput.OutputContent.PredefinedContent.ReferenceID: GetText. Apart from the text you specify, the terminal will show an instruction for how to confirm the input.
  • DisplayOutput.OutputContent.OutputText: An array of only one Text field containing your own text to show on the terminal.
  • InputData.InputCommand: TextString
  • 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 email address

{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "GetText"
          },
          "OutputText": [
            {"Text": "Enroll in our program"}
          ]
        }
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "TextString",
        "MaxInputTime": 120,
        "DefaultInputString": "name@domain.com"
      }
    }
  }
}
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("GetText");
outputContent.setPredefinedContent(predefinedContent);

OutputText outputText = new OutputText();
outputText.setText("Enroll in our program");
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.TEXT_STRING );
inputData.setMaxInputTime( BigInteger.valueOf(120) );
inputData.setDefaultInputString("name@domain.com");
inputRequest.setInputData(inputData);
saleToPOIRequest.setInputRequest(inputRequest);
terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

For a complete list of fields you can pass in a text input request, see the TextEntry InputRequest API reference.

In the response, the TextInput field contains the text that the user entered. If the user declined to provide input (pressed ), the InputResult has Response.Result: Failure, Response.ErrorCondition: Cancel, and an empty TextInput field.

Example response when the shopper entered an email address
{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560763410%22%20%7d"
        },
        "Input": {
          "TextInput": "resultingemail@gmail.com",
          "InputCommand": "TextString"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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