Here we describe how you can use an InputRequest
to show a prompt on the payment terminal asking the shopper to confirm something by drawing their signature on the display.
The following examples shows what the screen looks like with a signature drawn on landscape and portrait terminal displays.
Using the on-screen buttons, the shopper can cancel, clear, or confirm their signature.
On some terminal models, you can include additional text below the header, for example, to explain why you are asking the shopper for their signature. On M400, e280, and e285p terminals, the additional text is ignored.
Make a Signature input request
To use the payment terminal to ask a shopper to provide their signature:
-
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
GetSignature OutputContent.OutputText
An array of two Text
fields containing your own text to show on the terminal:- 1: The header. On a portrait display, this is limited to about 20 characters.
- 2: Use an empty value, or specify additional text.
On M400, e280, and e285 terminals terminals, additional text is ignored, but you still need to include the secondText
field with an empty value.
-
InputRequest.InputData
: This part of the request body handles the user input:Parameter Required Description Device
CustomerInput InfoQualify
Input InputCommand
GetConfirmation MaxInputTime
(Integer) Time-out in seconds. This is the time that the user gets to finish their input.
The following example asks the shopper for their signature.
{ "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":"GetSignature" }, "OutputText":[ { "Text":"Please sign" }, { "Text":"" } ] } }, "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("Please sign"); OutputText additionalText = new OutputText(); additionalText.setText(""); 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 Signature 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 input is received from the terminal, the
InputResponse
has anInputResult
with:Response.AdditionalResponse
: The signature provided by the shopper.Input.ConfirmedFlag
: true indicates the shopper confirmed their agreement by selecting Confirm.
Input.ConfirmedFlag
: false means the shopper declined by selecting Cancel.
{ "SaleToPOIResponse": { "InputResponse": { "InputResult": { "Device": "CustomerInput", "InfoQualify": "Input", "Response": { "Result": "Success", "AdditionalResponse": "responseData=%7b%20%22signature%22%3a%20%7b%20%22data...%22signature_format%22%3a%20%22raw%22%20%7d%20%7d" }, "Input": { "ConfirmedFlag": true, "InputCommand": "GetConfirmation" } }, "OutputResult": { "Device": "CustomerDisplay", "InfoQualify": "Display", "Response": { "Result": "Success" } } }, "MessageHeader": {...} } }
For a complete list of fields you can receive in a signature input response, see the Signature InputResponse API reference.
-
- Pass the relevant data from the
InputResult
to your system for validation and further use.