Here we describe how you can use an InputRequest
to ask the shopper or your staff to enter text. You can use this, for example, to obtain the email address of a shopper.
Make a Text input request
To use the payment terminal to ask for text input:
-
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader
: The standardSaleToPOIRequest.MessageHeader
object. This includes:Parameter Required Description MessageClass
Device MessageCategory
Input
-
InputRequest.DisplayOutput
: This part of the request body defines what is shown on the terminal:Parameter Required Description Device
CustomerDisplay InfoQualify
Display OutputContent.OutputFormat
Text OutputContent.PredefinedContent.ReferenceID
GetText OutputContent.OutputText
An array of one Text
field containing your own text to show on the terminal. -
InputRequest.InputData
: This part of the request body handles the user input:Parameter Required Description Device
CustomerInput InfoQualify
Input InputCommand
TextString 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 email address.
{ "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":"GetText" }, "OutputText":[ { "Text":"Your email address:" } ] } }, "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("Your email address:); 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 Text InputRequest API reference.
-
-
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
withEventDetails
: 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. You receive an
InputResponse
indicating that the input request was closed. -
If the user declined to respond (selected the Cancel key
), the
InputResult
hasResponse.Result
: Failure,Response.ErrorCondition
: Cancel, and an emptyTextInput
field. - If input is received from the terminal, the
InputResponse.InputResult
contains:Input.TextInput
: The text that the user entered.
{ "SaleToPOIResponse": { "InputResponse": { "InputResult": { "Device": "CustomerInput", "InfoQualify": "Input", "Response": { "Result": "Success", "AdditionalResponse": "responseData=%7b%20%20%7d" }, "Input": { "TextInput": "resultingemail@example.com", "InputCommand": "TextString" } }, "OutputResult": { "Device": "CustomerDisplay", "InfoQualify": "Display", "Response": { "Result": "Success" } } }, "MessageHeader": {...} } }
For a complete list of fields you can receive in a text input response, see the Text InputResponse API reference.
-
- Pass the relevant data from the
InputResult
to your system for validation and further use.