Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Ask for amount input

Use an input request to ask a shopper to enter an amount.

Here we describe how you can use an InputRequest to ask the customer to enter an amount. For example, the amount they want to pay when splitting the bill. The terminal shows the currency and a placeholder amount with two decimals.

The next illustrations show the amount input screen on a portrait and landscape display.

The following illustrations show the amount input screen on a small portrait display (e285) and a portrait display without a keypad (e280).

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.

Entering an amount

As the customer enters their input, the amount is populated from right to left. For example:
The placeholder amount is EUR 0.00.
To enter an amount of EUR 36.59 the customer successively selects 3, 6, 5, and 9.
After entering 3 the display shows EUR 0.03
After entering 6 the display shows EUR 0.36
After entering 5 the display shows EUR 3.65
After entering 9 the display shows EUR 36.59

Currency

By default, the currency is set to the first one specified for your store in the Customer Area. To check your settings, go to Point of sale > Stores, select your store, and go to Payment features.
If you use a merchant account to represent a physical store, it is the first currency defined for the merchant account in your Customer Area under Point of sale > Terminal settings > Payment features.

Make an Amount input request

To use the payment terminal to ask for an amount input:

  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- GetAmount
      OutputContent.OutputText -white_check_mark- An array of one Text field containing your own text to show on the terminal. On a portrait display, limited to about 20 characters. Apart from the text you specify, the terminal will show the currency and an instruction for how to confirm the input.
    • 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- DecimalString
      MaxInputTime (Integer) Time-out in seconds. This is the time that the user gets to finish their input.
      DefaultInputString Placeholder text for the input box, to let the user know what input format you are expecting. For example: 0.00

    This example asks the shopper to enter the amount they want to pay.

    {
        "SaleToPOIRequest":{
            "MessageHeader":{
                "ProtocolVersion":"3.0",
                "MessageClass":"Device",
                "MessageCategory":"Input",
                "MessageType":"Request",
                "SaleID":"POSSystemID12345",
                "ServiceID":"185341262",
                "POIID":"V400m-346937816"
            },
            "InputRequest":{
                "DisplayOutput":{
                    "Device":"CustomerDisplay",
                    "InfoQualify":"Display",
                    "OutputContent":{
                        "OutputFormat":"Text",
                        "PredefinedContent":{
                            "ReferenceID":"GetAmount"
                        },
                        "OutputText":[
                            {
                                "Text":"Enter Amount:"
                            }
                        ]
                    }
                },
                "InputData":{
                    "Device":"CustomerInput",
                    "InfoQualify":"Input",
                    "InputCommand":"DecimalString",
                    "MaxInputTime": 30,
                    "DefaultInputString":"0.00"
                }
            }
        }
    }
    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("GetAmount");
    outputContent.setPredefinedContent(predefinedContent);
    
    OutputText outputText = new OutputText();
    outputText.setText("Enter Amount:");
    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.DIGIT_DECIMAL );
    inputData.setMaxInputTime( BigInteger.valueOf(30) );
    inputData.setDefaultInputString("0.00");
    inputRequest.setInputData(inputData);
    saleToPOIRequest.setInputRequest(inputRequest);
    terminalAPIRequest.setSaleToPOIRequest(saleToPOIRequest);

    For a complete list of fields you can pass in a GetAmount input request, see the API reference.

  2. Wait for the user to supply the requested input.

    • If input is received from the terminal, the InputResult.Input contains:
      • DigitInput: The amount that the user entered.
    Example response when the shopper entered an amount
    {
        "SaleToPOIResponse": {
            "InputResponse": {
                "InputResult": {
                    "Device": "CustomerInput",
                    "InfoQualify": "Input",
                    "Input": {
                      "InputCommand": "DecimalString",
                      "DigitInput": "36.59"
                    },
                    "Response": {
                        "Result": "Success",
                        "AdditionalResponse": "responseData=%7b%20%20%7d",
                    }
                },
                "OutputResult": {
                    "Device": "CustomerDisplay",
                    "InfoQualify": "Display",
                    "Response": {
                        "Result": "Success"
                    }
                }
            },
            "MessageHeader": {
               "ProtocolVersion": "3.0",
               "MessageClass": "Device",
               "MessageCategory": "Input",
               "MessageType": "Response",
               "SaleID": "POSSystemID12345",
               "ServiceID": "185341262",
               "POIID": "V400m-346937816"
            }
        }
    • 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 the user declined to respond (selected the Cancel key ), the InputResult.Input.DigitInput field is empty. The InputResult.Response has Result: Failure and ErrorCondition: Cancel.

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

  3. Pass the DigitInput value to your system for validation and further use.

See also