Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Ask for a signature

Use an input request to ask a shopper to provide their signature.

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 illustrations show a signature screen on a portrait, small portrait (e285p), and landscape display.


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.

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 Signature input request

To use the payment terminal to ask a shopper to provide their signature:

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

    • InputRequest.DisplayOutput to define what is shown on the terminal:

      Parameter 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 second Text field with an empty value.

    • InputRequest.InputData to handle the user input:

      Parameter 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 GetSignature 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 input is received from the terminal, the InputResponse has an InputResult 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 .
    Example response when the shopper confirmed 
    {
  "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": {...}
  }
}

    • 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.

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

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

See also