Ask for a signature

Here we describe how you can use an InputRequest to show a prompt on the payment terminal asking the shopper to confirm by drawing their signature on the display.

The screen will contain a header with your own text, a box for drawing a signature, and two buttons labeled Cancel and Confirm.

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:

   • MessageHeader: The standard SaleToPOIRequest.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 title. This is limited to 28 characters on a landscape display, or 14 characters on a portrait display. 2: Additional text which can be long and is scrollable.

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

   https://docs.adyen.com/point-of-sale/shopper-input/signature#shopper-input_2

   • JSON
   • Java

   JSON Java

   {
       "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":"Do you accept the Delivery Waver form?"
                           }
                       ]
                   }
               },
               "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("Do you accept the Delivery Waver form?");
   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.

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. You receive an InputResponse indicating that the input request was closed.

   • 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 .
   https://docs.adyen.com/point-of-sale/shopper-input/signature#example-response-when-the-shopper-confirmed

   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": {...}
     }
   }

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

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

See also