---
title: "Prompt Card Read"
method: POST
path: "/devices/promptcardread"
tags: ["Devices"]
---

# Prompt Card Read

`POST /devices/promptcardread`

This function is used to prompt a P2PE-enabled, Commerce Engine or UTG controlled PIN pad to request a pass-through card swipe, causing the output of the swipe to be returned directly to the interface without any action or validation by Shift4 or the processor.

**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
  - DevicesPromptcardreadComengdevice
    - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information.
    - `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
      - `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.
      - `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.
      - `displayText` string — Optional field that specifies the text to display on the device.
    - `ui` object
      - `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`
      - `suppressAll` boolean — When `true`, the terminal suppresses all UI. Example use case: capturing employee/badge swipe data without displaying Commerce Engine UI.
    - `volume` Volume
      - `suppressBeeper` boolean — When `true`, the terminal suppresses all audible beeper output during the card-read window only — Contactless tap confirmation, MSR swipe, error/decline tones.
    - `timeout` number — Optional field that will set the timeout value in seconds. Sending `0` will set an indefinite timeout that can only be cancelled by sending a /devices/reset request. Commerce Engine will use its default value if not sent.
  - DevicesPromptcardreadComengcloud
    - `apiOptions` string[] — API Options modify the request being made. See the [API Options](/guides/appendices/api-options.md) section for more information.
    - `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.
      - `displayText` string — Optional field that specifies the text to display on the device.
    - `ui` object
      - `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`
      - `suppressAll` boolean — When `true`, the terminal suppresses all UI. Example use case: capturing employee/badge swipe data without displaying Commerce Engine UI.
    - `volume` Volume
      - `suppressBeeper` boolean — When `true`, the terminal suppresses all audible beeper output during the card-read window only — Contactless tap confirmation, MSR swipe, error/decline tones.
  - DevicesPromptcardreadUtgdevice
    - `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.

## Response `200`

Request was processed

- union
  - 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
      - `card` object
        - `entryMode` '1' | '2' — The method used to capture a payment card in an authorization/sale request. Value|Description -----|----------- 1 | Track 1 Only or Dual Track (Track 1 & 2) 2 | Track 2 Only
        - `expirationDate` integer — Card expiration date in MMYY format. This will only be returned for non-card brand cards such as gift cards and employee badge cards. This field will not be returned if the swipe data received is in a non-standard format.
        - `number` string — The unencrypted card number. This will only be returned for non-card brand cards such as gift cards and employee badge cards. This field will not be returned if the swipe data received is in a non-standard format.
        - `trackData` string — The raw track data read from the card swipe. This can contain track 1 data, track 2 data, or both. This will only be returned for non-card brand cards such as gift cards and employee badge cards.
      - `server` Server
        - `name` string — The name of the server that processed the request.
  - 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
      - `card` object
        - `entryMode` '1' | '2' — The method used to capture a payment card in an authorization/sale request. Value|Description -----|----------- 1 | Track 1 Only or Dual Track (Track 1 & 2) 2 | Track 2 Only
        - `number` string — The card number field will always be masked when returned in a response.
        - `type` 'AX' | 'AP' | 'BC' | 'CI' | 'DB' | 'GC' | 'JC' | 'MC' | 'NS' | 'PL' | 'SC' | 'VS' | 'WP' | 'YC' — An abbreviation used to specify the type of card that was used when processing a transaction. Value| Description -----|------------ AX | American Express AP | Alipay BC | Backed Card CI | Citgo DB | Debit card GC | Gift Card JC | JCB MC | Mastercard NS | Discover/JCB/Novus PL | Private Label SC | Sears Canada VS | Visa WP | WeChat Pay YC | IT’S YOUR CARD
      - `p2pe` P2PE
        - `data` string, required — The full output of a P2PE keypad/magnetic swipe reader (MSR).
        - `format` '01' | '02' | '03' | '04' | '05', required — Classifies the type of payment device being used for P2PE. Value|Description -----|----------- 01 | IDTech Enhanced Encryption format 02 | IDTech Enhanced Encryption format USB HID 03 | Ingenico format 04 | VeriFone format 05 | Shift4 TDES DUKPT format 07 | AES 128 or 256
        - `ksn` string — The key serial number which was used to encrypt the P2PE data.
      - `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/2f85c87cc9e5/schema)