--- title: "Display Custom Form" method: POST path: "/devices/processform" tags: ["Devices"] --- # Display Custom Form `POST /devices/processform` This function is used to display a custom form and text for a consumer’s input on a Commerce Engine or UTG controlled PIN pad. **Integration Methods:** - Locally Installed UTG - Commerce Engine For On Premise - Commerce Engine For Cloud 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 - DevicesProcessformComengdevice - `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 - `form` union, required - DeviceProcessFormTypeMultiButtonScrollingText - `type` 'multiButtonScrollingText', required — Displays a form with header text, subheader text, scrolling body text and up to 4 buttons. When using this custom form type at least one of the following fields must also be included in the request: - `form.header` - `form.subHeader` - `form.text` - `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. - `buttons` object[], required — Array of 1 - 4 buttons to be displayed on the device. - `id` string, required — ID value used to identify which button is pressed. The ID of the button the user selected is returned in the `result.form.buttonSelected.id` response field. - `text` string, required — Text to display on the button. The text of the button the user selected is returned in the `result.form.buttonSelected.text` response field. - `timeout` number — The number of seconds until the custom form will timeout. Defaults to 120 seconds if `form.timeout` is not sent in the request. - DeviceProcessFormTypeMessage - `type` 'message', required — Displays a message based form with header text, subheader text, and body text. When using this custom form type at least one of the following fields must also be included in the request: - `form.header` - `form.subHeader` - `form.text` - `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. - `timeout` number — The number of seconds until the custom form will timeout. Defaults to 120 seconds if `form.timeout` is not sent in the request. - DeviceProcessFormTypeQRDisplay - `type` 'qrDisplay', required — Displays a QR code based form with header text, a QR code image and footer text. - `qrCode` DeviceFormQRCode, required - `value` string — Contains the QR Code URL string. This value will be converted to a QR code and displayed on the device. - `header` DeviceFormHeader - `value` string — Header text. Add `\r\n` to force a new line. - `footer` DeviceFormFooter - `value` string — Footer text. Add `\r\n` to force a new line. - `timeout` number — The number of seconds until the custom form will timeout. Defaults to 120 seconds if `form.timeout` is not sent in the request. - `device` object - `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` - DevicesProcessformComengcloud - `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. - `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. - `form` union, required - DeviceProcessFormTypeMultiButtonScrollingText - `type` 'multiButtonScrollingText', required — Displays a form with header text, subheader text, scrolling body text and up to 4 buttons. When using this custom form type at least one of the following fields must also be included in the request: - `form.header` - `form.subHeader` - `form.text` - `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. - `buttons` object[], required — Array of 1 - 4 buttons to be displayed on the device. - `id` string, required — ID value used to identify which button is pressed. The ID of the button the user selected is returned in the `result.form.buttonSelected.id` response field. - `text` string, required — Text to display on the button. The text of the button the user selected is returned in the `result.form.buttonSelected.text` response field. - `timeout` number — The number of seconds until the custom form will timeout. Defaults to 120 seconds if `form.timeout` is not sent in the request. - DeviceProcessFormTypeMessage - `type` 'message', required — Displays a message based form with header text, subheader text, and body text. When using this custom form type at least one of the following fields must also be included in the request: - `form.header` - `form.subHeader` - `form.text` - `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. - `timeout` number — The number of seconds until the custom form will timeout. Defaults to 120 seconds if `form.timeout` is not sent in the request. - DeviceProcessFormTypeQRDisplay - `type` 'qrDisplay', required — Displays a QR code based form with header text, a QR code image and footer text. - `qrCode` DeviceFormQRCode, required - `value` string — Contains the QR Code URL string. This value will be converted to a QR code and displayed on the device. - `header` DeviceFormHeader - `value` string — Header text. Add `\r\n` to force a new line. - `footer` DeviceFormFooter - `value` string — Footer text. Add `\r\n` to force a new line. - `timeout` number — The number of seconds until the custom form will timeout. Defaults to 120 seconds if `form.timeout` is not sent in the request. - `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` - DevicesProcessformUtgdevice - `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. - `form` DeviceFormUTG, required - `name` string, required — Specifies a 12-character, alphanumeric string containing the form name to display on a UTG-controlled PIN pad. The file extension should not be included in the value. - `items` DeviceFormItems[] — An array of key/value pairs used to populate fields on the custom form - `key` string — A five-character, alphanumeric string containing the ID of the field which you want to display a custom value on. - `value` string — The value that should be displayed in the field specified by the key. ## Response `200` Request was processed - union - DevicesProcessformResponseUtg - `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. - `form` DeviceFormResponse - `name` string — Specifies a 12-character, alphanumeric string containing the form name to display on a UTG-controlled PIN pad. The file extension should not be included in the value. - `result` string — A five-character, alphanumeric string containing the ID of the button pressed by the consumer on a UTG-controlled PIN pad. - `server` Server - `name` string — The name of the server that processed the request. - DevicesProcessformResponseComengMessage - `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 - `server` Server - `name` string — The name of the server that processed the request. - DevicesProcessformResponseComengMultiButtonScrollingText - `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 - `server` Server - `name` string — The name of the server that processed the request. - `form` object - `buttonSelected` object - `id` string — ID value identifying which button was selected. Matches the value recieved in the `form.buttons.id` request field. - `text` string — Button text value of the button that was selected. Matches the value recieved in the `form.buttons.text` request field. ## 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/2f85c87cc9e5/schema)