---
title: "Prompt for Input"
method: POST
path: "/devices/promptinput"
tags: ["Devices"]
---

# Prompt for Input

`POST /devices/promptinput`

This function is used to prompt a Commerce Engine or UTG-controlled PIN pad to collect a specified value from a consumer. The interface will specify the value based on the `device.promptInput.index` field. Each request will collect one specified value; when multiple values need to be collected, separate requests must be sent.

**Integration Methods:**
- Commerce Engine For On Premise
- Commerce Engine For Cloud
- Locally Installed UTG

See the [Integration Methods](/guides/quickstart#integration-methods) and [URLs Section](/guides/quickstart#urls) sections of the Development Quick Start guide for details regarding each processing option.

## Headers

- `InterfaceVersion` string, required
- `InterfaceName` string, required
- `CompanyName` string, required
- `AccessToken` string, uuid, required

## Request body

- union
  - DevicesPromptinputComengdevice
    - `dateTime` string, ISO 8601, required — The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm). Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
    - `device` object, required
      - `promptInput` DevicePromptInput, required
        - `index` string, required — This field specifies a value to be collected from a consumer using a UTG-controlled PIN pad. Value| Description | Return Format -----|--------------------------------------|------------------------- 001 | Card Security Code | Numeric 002 | Street Number | Numeric 003 | ZIP Code | Numeric 004 | Social Security Number (SSN) | Numeric, no formatting 005 | Last 4 of SSN | Numeric 006 | Date of Birth | MM/DD/YYYY 007 | Annual Income | Numeric, no formatting 008 | Home Phone Number | Numeric, no formatting 009 | Business Phone Number | Numeric, no formatting 010 | Email Address (Requires Touchscreen) | Alphanumeric 011 | Driver's ID (Requires Touchscreen) | Alphanumeric 012 | Tip | Numeric
        - `result` string — This field contains the value collected from a consumer using a UTG-controlled PIN pad.
      - `nextStep` DeviceNextStep — An optional object used to control the device behavior after processing the request. If included in the request, the `type` sub-field is required
        - `type` 'idle' | 'none' | 'displayWait' | 'displayText' — Determines the device behavior after processing the request. If no additional request is received after 120 seconds the device will return to idle as a failsafe. | Value | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | idle | Return back to the idle screen | | none | Stay on the same screen. A subsequent message must be immediately sent or else the device will appear frozen to the user. | | displayWait | Displays a please wait screen | | displayText | Displays custom text. The request must include at least one of the following fields: `device.nextStep.header.value`, `device.nextStep.subHeader.value` or `device.nextStep.text.value`. |
        - `header` DeviceFormHeader
          - `value` string — Header text. Add `\r\n` to force a new line.
        - `subHeader` DeviceFormSubHeader
          - `value` string — Sub Header text. Add `\r\n` to force a new line.
        - `text` DeviceFormText
          - `value` string — Body text. Add `\r\n` to force a new line.
      - `terminalId` string — To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in this field.
    - `ui` UIRequest
      - `language` string — ISO 639-1 2-letter language code specifying the UI display language for the transaction (e.g. "en", "fr", "de"). When provided, overrides the device's configured default language for the duration of the session. Value persists across transactions until a new value is passed. Send default to reset the device back to its default language.
      - `mode` 'light' | 'dark' — Set the UI to light mode by sending `light` or dark mode by sending `dark`
  - DevicesPromptinputComengcloud
    - `dateTime` string, ISO 8601, required — The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm). Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
    - `device` object, required
      - `cloud` boolean, required — Indicates the transaction will be processed via the Commerce Engine solution for cloud based POS/PMS systems. Value must be sent as `true` in order to route the request to the payment device at the merchant location.
      - `manufacturer` 'Ingenico' | 'Innowi' | 'PAX' | 'Verifone' | 'Castles' | 'Miura', required — Specifies the company which manufactured the device.
      - `serialNumber` string, required — Specifies the serial number of the device.
      - `promptInput` DevicePromptInput, required
        - `index` string, required — This field specifies a value to be collected from a consumer using a UTG-controlled PIN pad. Value| Description | Return Format -----|--------------------------------------|------------------------- 001 | Card Security Code | Numeric 002 | Street Number | Numeric 003 | ZIP Code | Numeric 004 | Social Security Number (SSN) | Numeric, no formatting 005 | Last 4 of SSN | Numeric 006 | Date of Birth | MM/DD/YYYY 007 | Annual Income | Numeric, no formatting 008 | Home Phone Number | Numeric, no formatting 009 | Business Phone Number | Numeric, no formatting 010 | Email Address (Requires Touchscreen) | Alphanumeric 011 | Driver's ID (Requires Touchscreen) | Alphanumeric 012 | Tip | Numeric
        - `result` string — This field contains the value collected from a consumer using a UTG-controlled PIN pad.
      - `nextStep` DeviceNextStep — An optional object used to control the device behavior after processing the request. If included in the request, the `type` sub-field is required
        - `type` 'idle' | 'none' | 'displayWait' | 'displayText' — Determines the device behavior after processing the request. If no additional request is received after 120 seconds the device will return to idle as a failsafe. | Value | Description | | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | idle | Return back to the idle screen | | none | Stay on the same screen. A subsequent message must be immediately sent or else the device will appear frozen to the user. | | displayWait | Displays a please wait screen | | displayText | Displays custom text. The request must include at least one of the following fields: `device.nextStep.header.value`, `device.nextStep.subHeader.value` or `device.nextStep.text.value`. |
        - `header` DeviceFormHeader
          - `value` string — Header text. Add `\r\n` to force a new line.
        - `subHeader` DeviceFormSubHeader
          - `value` string — Sub Header text. Add `\r\n` to force a new line.
        - `text` DeviceFormText
          - `value` string — Body text. Add `\r\n` to force a new line.
    - `ui` UIRequest
      - `language` string — ISO 639-1 2-letter language code specifying the UI display language for the transaction (e.g. "en", "fr", "de"). When provided, overrides the device's configured default language for the duration of the session. Value persists across transactions until a new value is passed. Send default to reset the device back to its default language.
      - `mode` 'light' | 'dark' — Set the UI to light mode by sending `light` or dark mode by sending `dark`
  - DevicesPromptinputUtgdevice
    - `dateTime` string, ISO 8601, required — The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm). Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
    - `device` object, required
      - `terminalId` string, required — To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in this field.
      - `promptInput` DevicePromptInput, required
        - `index` string, required — This field specifies a value to be collected from a consumer using a UTG-controlled PIN pad. Value| Description | Return Format -----|--------------------------------------|------------------------- 001 | Card Security Code | Numeric 002 | Street Number | Numeric 003 | ZIP Code | Numeric 004 | Social Security Number (SSN) | Numeric, no formatting 005 | Last 4 of SSN | Numeric 006 | Date of Birth | MM/DD/YYYY 007 | Annual Income | Numeric, no formatting 008 | Home Phone Number | Numeric, no formatting 009 | Business Phone Number | Numeric, no formatting 010 | Email Address (Requires Touchscreen) | Alphanumeric 011 | Driver's ID (Requires Touchscreen) | Alphanumeric 012 | Tip | Numeric
        - `result` string — This field contains the value collected from a consumer using a UTG-controlled PIN pad.

## Response `200`

Request was processed

- object
  - `result` object[]
    - `dateTime` string, ISO 8601 — The date and time in ISO 8601 format including the timezone offset (yyyy-mm-ddThh:mm:ss.nnn+hh:mm). Must be sent as the local date/time of the merchant. For example, a request processed at a merchant in the Pacific time zone at 9:18am on April 15th 2021 would be sent as 2021-04-15T09:18:23.283-07:00
    - `device` object
      - `terminalId` string — To prompt a specific UTG-controlled PIN pad in a request, the API Terminal ID configured in UTG TuneUp must be specified in this field.
      - `promptInput` DevicePromptInput
        - `index` string, required — This field specifies a value to be collected from a consumer using a UTG-controlled PIN pad. Value| Description | Return Format -----|--------------------------------------|------------------------- 001 | Card Security Code | Numeric 002 | Street Number | Numeric 003 | ZIP Code | Numeric 004 | Social Security Number (SSN) | Numeric, no formatting 005 | Last 4 of SSN | Numeric 006 | Date of Birth | MM/DD/YYYY 007 | Annual Income | Numeric, no formatting 008 | Home Phone Number | Numeric, no formatting 009 | Business Phone Number | Numeric, no formatting 010 | Email Address (Requires Touchscreen) | Alphanumeric 011 | Driver's ID (Requires Touchscreen) | Alphanumeric 012 | Tip | Numeric
        - `result` string — This field contains the value collected from a consumer using a UTG-controlled PIN pad.
    - `server` Server
      - `name` string — The name of the server that processed the request.

## Other responses

- `400` — Error
- `504` — Timeout

---

[API](https://skmtc.dev/shift4/apis/shift4-payment-api.md) · [All operations](https://skmtc.dev/shift4/apis/shift4-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/shift4/shift4-payment-api/revisions/b923fc55b203/schema)