Search

Are you looking for test card numbers?

Would you like to contact support?

Shopper input

Learn how to use the payment terminal to collect input from your customers.

In addition to making payments, Adyen's point of sale terminals can request input from your shopper. This allows you to collect the shopper's email address for example, or perform a survey. The communication flow is between your cash register and the terminal, and does not involve the Adyen backend. You need to process the collected input with your own business logic.

There are several types of InputRequest:

  • Confirmation - Show some information and ask the shopper to confirm they agree.
  • Signature - Show some information and ask the shopper to confirm by supplying their signature.
  • Survey input - Show a multiple choice question and let the shopper select one of the answers. You can use this for NPS surveys, order lists, and such.
  • Numeric input - You'd typically use this to ask the shopper for their phone number.
  • Text input - You'd typically use this to ask the shopper for their email address.

For each type of shopper input, we provide predefined elements to show on the terminal display, and fields that you need to populate with your own text. The shopper uses the terminal keypad or on-screen keyboard to respond.

You cannot use shopper input requests on (legacy) terminals that do not support Terminal API or on terminals that support only a subset of Terminal API.

Collect shopper input

This is the general procedure for asking the shopper to supply some input. Refer to the shopper input types for specific details.

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

    • content-type: application/json
    • x-api-key: API key that you generated when configuring your Adyen account

      An API key is only required if you're using cloud-based communications.

    • MessageHeader:
      • ProtocolVersion: 3.0
      • MessageClass: Device
      • MessageCategory: Input
      • MessageType: Request
      • SaleID: Your unique ID for the cash register.
      • ServiceID: Your unique ID generated by this cash register for this transaction. This needs to be unique within the last 48 hours.
      • POIID: Unique ID of the terminal. 

        The POIID = [Terminal model]-[Serial number], for example: P400Plus-123456789

    • InputRequest.DisplayOutput:

      • Device: CustomerDisplay.
      • InfoQualify: Display.
      • OutputContent.OutputFormat: Text.
      • OutputContent.PredefinedContent.ReferenceID: The set of predefined elements to use:

      • OutputText: An array of one or more Text fields containing your own text to display to the shopper. Refer to the shopper input types below to learn how to use these fields.
    • InputData:

      • Device: CustomerInput.
      • InfoQualify: Input.
      • InputCommand: Command for the shopper input type:

      • MaxInputTime: Time-out in seconds. This is time that the shopper gets to finish their input.
    
    {
     "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": "PREDEFINED_ELEMENTS_ID"
             },
             "OutputText": [
               {"Text": "Your own text"}
             ]
           }
         },
         "InputData": {
           "Device": "CustomerInput",
           "InfoQualify": "Input",
           "InputCommand": "INPUT_TYPE",
           "MaxInputTime": 30
         }
       }
     }
    }

    Some input types require additional fields or specific values. Refer to the shopper input types below.

  2. Wait for the shopper to supply the requested input using the on-screen keyboard or terminal keypad.

    The shopper input is not validated against a format.

    In the response, the InputResult shows whether the shopper agreed or disagreed, provided a signature, selected an answer to the multiple choice question, entered numerals or text, or declined to provide input.
    If the request timed out, the response will contain an EventNotificiation with EventDetails: message=Did+not+receive+a+response+from+the+POI.

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

Confirmation

In an InputRequest asking the shopper to confirm something, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • InputRequest:

    • PredefinedContent.ReferenceID: GetConfirmation.
    • OutputText: An array of four Text fields containing your own text to display to the shopper.

      1. The first Text field is the title.
      2. The second Text fields represents additional text which can be long and is scrollable.
      3. The third Text field is the label for the 'decline' button on the left.
      4. The fourth Text field is the label for the 'agree' button on the right.
  • InputData:

    • InputCommand: GetConfirmation.
{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "GetConfirmation"
          },
          "OutputText": [
            {"Text": "Do you accept our Terms and Conditions?"},
            {"Text": "The full Terms and Conditions are available on our website."},
            {"Text": "No"},
            {"Text": "Yes"}
          ]
        }
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "GetConfirmation",
        "MaxInputTime": 30
      }
    }
  }
}

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

In the response, ConfirmedFlag: true indicates the shopper tapped the 'agree' button on the right or pressed to confirm their agreement. ConfirmedFlag: false means the shopper tapped the 'decline' button on the left or pressed .

{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560867383%22%20%7d"
        },
        "Input": {
          "ConfirmedFlag": true,
          "InputCommand": "GetConfirmation"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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

Signature

In an InputRequest asking the shopper to sign for something and confirm, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • InputRequest:

    • PredefinedContent.ReferenceID: GetSignature. Apart from the text you specify, the terminal display will show an input box for the shopper to draw their signature.
    • OutputText: An array of four Text fields containing your own text to display to the shopper.

      1. The first Text field is the title.
      2. The second Text field contains additional information.
      3. The third Text field is the label for the 'decline' button on the left.
      4. The fourth Text field is the label for the 'agree' button on the right.
  • InputData:

    • InputCommand: GetConfirmation.
{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "GetSignature"
          },
          "OutputText": [
            {"Text": "Do you accept the Delivery Waver Form?"},
            {"Text": "Please Sign"},
            {"Text": "No"},
            {"Text": "Yes"}
          ]
        }
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "GetConfirmation",
        "MaxInputTime": 30
      }
    }
  }
}

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

In the response, the AdditionalResponse contains the signature provided by the shopper. ConfirmedFlag: true indicates the shopper tapped the 'agree' button on the right or pressed to confirm their agreement. ConfirmedFlag: false means the shopper tapped the 'decline' button on the left or pressed .

{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560864516%22%2c%20%22signature%22%3a%20%7b%20%22data%22%3a%20%5b%20%7b%20%22x%22%3a%20%2249%22%2c%20%22y...signature_format%22%3a%20%22raw%22%20%7d%20%7d"
        },
        "Input": {
          "ConfirmedFlag": true,
          "InputCommand": "GetConfirmation"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",        
      "MessageType": "Response"
    }
  }
}

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

Survey input

In an InputRequest asking the shopper to answer a multiple choice question, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • InputRequest:

    • PredefinedContent.ReferenceID: MenuButtons. The terminal will display the answers to choose from as a scrollable list of boxes that the shopper can tap to select.
    • OutputText: An array of only one Text field containing your own text to display to the shopper. Use this to specify the question.
  • MenuEntry: An array of up to 15 items representing the answers to choose from. Each answer has:

    • OutputFormat: Text
    • OutputText: an array of three Text fields with your own text that together form the answer.
      The first Text field will show in bold. Use an empty string for unused Text fields.
      For example, you could write a short-form answer in the first field, the long-form answer in the second field, and not use the third field. Or you could use the three fields for the article name, description, and label.
  • InputData:

    • InputCommand: GetMenuEntry.
{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "MenuButtons"
          },
          "OutputText": [
            {"Text": "How was your visit?"}
          ]
        },
        "MenuEntry": [
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Excellent"},
              {"Text": "Don't change a thing"},
              {"Text": ""}
            ]
          },
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Great"},
              {"Text": "Would surely come again"},
              {"Text": ""}
            ]
          },
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Good"},
              {"Text": "What I expected"},
              {"Text": ""}
            ]
          },
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Mweh"},
              {"Text": "Could have been better"},
              {"Text": ""}
            ]
          },
          {
            "OutputFormat": "Text",
            "OutputText": [
              {"Text": "Terrible"},
              {"Text": "Will never go here again"},
              {"Text": ""}
            ]
          }
        ]
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "GetMenuEntry",
        "MaxInputTime": 120
      }
    }
  }
}

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

In the response, the MenuEntryNumber array indicates the answer that the shopper selected. For example, if the shopper selected the third answer, the third item in the array is 1 and all other array items are 0.
When the customer declined to answer (pressed , the InputResult has Response.Result: Failure and Response.ErrorCondition: Cancel.

{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560869035%22%20%7d"
        },
        "Input": {
          "MenuEntryNumber": [
            0,
            0,
            1,
            0,
            0
          ],
          "InputCommand": "GetMenuEntry"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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

Numeric input

In an InputRequest asking the shopper to enter numerals, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • InputRequest:

    • PredefinedContent.ReferenceID: GetDigit. Apart from the text you specify, the terminal will display an instruction for how to confirm the input.
    • OutputText: An array of only one Text field containing your own text to display to the shopper.
  • InputData:

    • InputCommand: DigitString.
    • DefaultInputString: Placeholder text for the input box, to let the shopper know what input format you are expecting.

{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "GetDigit"
          },
          "OutputText": [
            {"Text": "Please enter your phone number"}
          ]
        }
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "DigitString",
        "MaxInputTime": 30,
        "DefaultInputString": "0612345678"
      }
    }
  }
}

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

In the response, the DigitInput field contains the numerals that the shopper entered. When the customer declined to provide input (pressed ), the InputResult has Response.Result: Failure, Response.ErrorCondition: Cancel, and an empty DigitInput field.

{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560761701%22%20%7d"
        },
        "Input": {
          "DigitInput": "0687164125",
          "InputCommand": "DigitString"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
         }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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

Text input

In an InputRequest asking the shopper to enter text, you need to specify the common fields for collecting shopper input as well as the following specific values and fields:

  • InputRequest:

    • PredefinedContent.ReferenceID: GetText. Apart from the text you specify, the terminal will display an instruction for how to confirm the input.
    • OutputText: An array of only one Text field containing your own text to display to the shopper.
  • InputData:

    • InputCommand: TextString.
    • DefaultInputString: Placeholder text for the input box, to let the shopper know what input format you are expecting.
{
  "SaleToPOIRequest": {
    "MessageHeader": {...},
    "InputRequest": {
      "DisplayOutput": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "OutputContent": {
          "OutputFormat": "Text",
          "PredefinedContent": {
            "ReferenceID": "GetText"
          },
          "OutputText": [
            {"Text": "Enroll in our program"}
          ]
        }
      },
      "InputData": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "InputCommand": "TextString",
        "MaxInputTime": 120,
        "DefaultInputString": "name@domain.com"
      }
    }
  }
}

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

In the response, the TextInput field contains the text that the shopper entered. When the customer declined to provide input (pressed ), the InputResult has Response.Result: Failure, Response.ErrorCondition: Cancel, and an empty TextInput field.

{
  "SaleToPOIResponse": {
    "InputResponse": {
      "InputResult": {
        "Device": "CustomerInput",
        "InfoQualify": "Input",
        "Response": {
          "Result": "Success",
          "AdditionalResponse": "responseData=%7b%20%22unique_id%22%3a%20%22001560763410%22%20%7d"
        },
        "Input": {
          "TextInput": "resultingemail@gmail.com",
          "InputCommand": "TextString"
        }
      },
      "OutputResult": {
        "Device": "CustomerDisplay",
        "InfoQualify": "Display",
        "Response": {
          "Result": "Success"
        }
      }
    },
    "MessageHeader": {
      "ProtocolVersion": "3.0",
      "SaleID": "POSSystemID12345",
      "MessageClass": "Device",
      "MessageCategory": "Input",
      "ServiceID": "0207111104",
      "POIID": "V400m-324688179",
      "MessageType": "Response"
    }
  }
}

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