--- title: "Request Signature" method: POST path: "/devices/promptsignature" tags: ["Devices"] --- # Request Signature `POST /devices/promptsignature` This function is used to request a prompt for signature on a UTG or Commerce Engine controlled PIN pad and returns the signature. **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. See the [JSON Body Schemas](/guides/quickstart#json-body-schemas) for more details on the various JSON body formats. ## Headers - `InterfaceVersion` string, required - `InterfaceName` string, required - `CompanyName` string, required - `AccessToken` string, uuid, required ## Request body - union - DevicesPromptsignatureComengdevice - `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 - `displayText` string — Optional field that specifies the text to display on 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. - `terminalId` string — This field is optional and is for backwards compatibility with existing vendors that are used to processing via UTG controlled devices. Since Commerce Engine is running directly on the payment device it does not require a `device.terminalId` to be specified. - `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` - DevicesPromptsignatureComengcloud - `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. - `displayText` string — Optional field that specifies the text to display on 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. - `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` - DevicesPromptsignatureUtgdevice - `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` DeviceOnlyTID, 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. ## 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` DeviceOnlyTIDResponse - `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. - `server` Server - `name` string — The name of the server that processed the request. - `signature` Signature - `data` string — The base64-encoded data sent when a signature is captured as a Portable Network Graphics (PNG) file. - `format` 'P' — The data format the signature data will be in. "P" for PNG format. ## Other responses - `400` — Error - `504` — Timeout --- [API](https://skmtc.net/shift4/apis/shift4-payment-api.md) · [All operations](https://skmtc.net/shift4/apis/shift4-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shift4/shift4-payment-api/versions/b923fc55b203/schema)