Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Ask for confirmation

Use an input request to ask a shopper for confirmation.

Here we describe how you can use an InputRequest to show some information on the display of the payment terminal and ask the shopper to confirm they agree.

The following illustrations show a confirmation screen on a portrait, small portrait (e285p), and landscape display.


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 cash register.

Make a Confirmation input request

To use the payment terminal to ask a shopper to confirm something:

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

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

      Parameter Required Description
      Device -white_check_mark- CustomerDisplay
      InfoQualify -white_check_mark- Display
      OutputContent.OutputFormat -white_check_mark- Text
      OutputContent.PredefinedContent.ReferenceID -white_check_mark- GetConfirmation
      OutputContent.OutputText -white_check_mark- An array of four Text fields containing your own text to show on the terminal:
      1. The title. On a portrait display, this is limited to about 20 characters.
      2. Additional text which can be long. Use \n to add a line break.
      3. The label for the "Cancel" button on the left.
      4. The label for the "Confirm" button on the right.
    • InputRequest.InputData: This part of the request body handles the user input:

      Parameter Required Description
      Device -white_check_mark- CustomerInput
      InfoQualify -white_check_mark- Input
      InputCommand -white_check_mark- 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 to confirm they agree.

    {
        "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":"GetConfirmation"
                        },
                        "OutputText":[
                            {
                                "Text":"Terms & Conditions"
                            },
                            {
                                "Text":"Do you accept our Terms and Conditions? \n The full text is available on our website."
                            },
                            {
                                "Text":"Decline"
                            },
                            {
                                "Text":"Agree"
                            }
                        ]
                    }
                },
                "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("Terms & Conditions");
    OutputText additionalText = new OutputText();
    additionalText.setText("Do you accept our Terms and Conditions? \n The full text is available on our website.");
    OutputText declineAnswer = new OutputText();
    declineAnswer.setText("Decline");
    OutputText agreeAnswer = new OutputText();
    agreeAnswer.setText("Agree");
    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 GetConfirmation 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 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.

    • If input is received from the terminal, the InputResponse has an InputResult with:
      • Input.ConfirmedFlag: true indicates the shopper confirmed their agreement by selecting the right button on the display ("Agree") or the Confirm key on the keypad.
      • Input.ConfirmedFlag: false means the shopper selected the left button on the display ("Decline") or the Cancel key on the keypad.
    Example response when the shopper confirmed
    {
      "SaleToPOIResponse": {
        "InputResponse": {
          "InputResult": {
            "Device": "CustomerInput",
            "InfoQualify": "Input",
            "Response": {
              "Result": "Success"
            },
            "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 GetConfirmation input response, see the API reference.

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

See also