---
title: "Prompt Tip"
method: POST
path: "/devices/prompttip"
tags: ["Devices"]
---

# Prompt Tip

`POST /devices/prompttip`

This function is used to prompt for tip outside of a payment transaction.

**Integration Methods:**
- 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
  - DevicesPrompttipComengdevice
    - `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
    - `amount` AmountPromptTip, required
      - `total` number, required — The total transaction amount. Used as the seed for calculating the tip amount when using preset percentages.
      - `tipBasis` number — The amount Commerce Engine will use to calclulate the tip percentage amounts on the tip screen. This is an optional field that will be used instead of `amount.total` in a scenario where the percentage calculations must be made on an amount other than the total amount. For example, you have a $130 check and you make an initial payment of $30 using a gift card leaving a $100 remaining balance. When you process the remaining balance and you want to calculate the tip percentages based on the original $130 check total you would send `amount.total = 100` and `amount.tipBaiss = 130`
    - `tip` TipObject, required — The optional `tip` object allows integrators to control the display and behavior of the tip screen presented to customers during payment processing.
      - `presetType` 'none' | 'percent' | 'amount', required — The tip option selected by the cardholder. | Value | Description | |---------|--------------------------------------------------------------------------------------------------------------------| | none | Skips the preset screen and goes direclty to the other tip amount screen. | | percent | Display the preset screen showing preset percentages. Must include `tip.preset1`, `tip.preset2`, and `tip.preset3` | | amount | Display the preset screen showing preset amounts. Must include `tip.preset1`, `tip.preset2`, and `tip.preset3`. |
      - `presetDefault` '1' | '2' | '3' | 'none' — The preset value that is selected by default. If not sent in the request it will default to to preset 2. | Value | Description | |-------|-----------------------| | 1 | Preset 1 is selected | | 2 | Preset 2 is selected | | 3 | Preset 3 is selected | | none | No preset is selected |
      - `preset1` number — The preset value for the preset number 1. If `presetType = percent` send the percentage value. If `presetType = amount` send the amount value.
      - `preset2` number — The preset value for the preset number 2. If `presetType = percent` send the percentage value. If `presetType = amount` send the amount value.
      - `preset3` number — The preset value for the preset number 3. If `presetType = percent` send the percentage value. If `presetType = amount` send the amount value.
      - `headerText` string — Optional field to override the header text. If not sent, the header text will display `Add Tip` in the terminal's configured language.
      - `basisNotification` boolean — Send as `true` if you want to display the tip basis notification text on the tip screen. Must also include `amount.tipBasis` in the request if sending as `true`. Default: `false`
      - `displayNoTip` boolean — Send as `true` if you want to display No Tip instead of Cash Tip on the tip entry screen. Default: `false`
    - `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`
  - DevicesPrompttipComengcloud
    - `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
    - `amount` AmountPromptTip, required
      - `total` number, required — The total transaction amount. Used as the seed for calculating the tip amount when using preset percentages.
      - `tipBasis` number — The amount Commerce Engine will use to calclulate the tip percentage amounts on the tip screen. This is an optional field that will be used instead of `amount.total` in a scenario where the percentage calculations must be made on an amount other than the total amount. For example, you have a $130 check and you make an initial payment of $30 using a gift card leaving a $100 remaining balance. When you process the remaining balance and you want to calculate the tip percentages based on the original $130 check total you would send `amount.total = 100` and `amount.tipBaiss = 130`
    - `device` DeviceComEngCloud
      - `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.
    - `tip` TipObject, required — The optional `tip` object allows integrators to control the display and behavior of the tip screen presented to customers during payment processing.
      - `presetType` 'none' | 'percent' | 'amount', required — The tip option selected by the cardholder. | Value | Description | |---------|--------------------------------------------------------------------------------------------------------------------| | none | Skips the preset screen and goes direclty to the other tip amount screen. | | percent | Display the preset screen showing preset percentages. Must include `tip.preset1`, `tip.preset2`, and `tip.preset3` | | amount | Display the preset screen showing preset amounts. Must include `tip.preset1`, `tip.preset2`, and `tip.preset3`. |
      - `presetDefault` '1' | '2' | '3' | 'none' — The preset value that is selected by default. If not sent in the request it will default to to preset 2. | Value | Description | |-------|-----------------------| | 1 | Preset 1 is selected | | 2 | Preset 2 is selected | | 3 | Preset 3 is selected | | none | No preset is selected |
      - `preset1` number — The preset value for the preset number 1. If `presetType = percent` send the percentage value. If `presetType = amount` send the amount value.
      - `preset2` number — The preset value for the preset number 2. If `presetType = percent` send the percentage value. If `presetType = amount` send the amount value.
      - `preset3` number — The preset value for the preset number 3. If `presetType = percent` send the percentage value. If `presetType = amount` send the amount value.
      - `headerText` string — Optional field to override the header text. If not sent, the header text will display `Add Tip` in the terminal's configured language.
      - `basisNotification` boolean — Send as `true` if you want to display the tip basis notification text on the tip screen. Must also include `amount.tipBasis` in the request if sending as `true`. Default: `false`
      - `displayNoTip` boolean — Send as `true` if you want to display No Tip instead of Cash Tip on the tip entry screen. Default: `false`
    - `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`

## 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
    - `amount` object
      - `tip` number — The tip amount of the transaction.
      - `total` number — The amount being charged for a particular transaction. If other amount fields are sent, they must be included in the total amount. Amount cannot be zero.
    - `tip` object
      - `selectedOption` 'preset1' | 'preset2' | 'preset3' | 'other' | 'notip' — The tip option selected by the cardholder. | Value | Description | |---------|------------------------------------------------| | preset1 | The cardholder selected the preset 1 button | | preset2 | The cardholder selected the preset 2 button | | preset3 | The cardholder selected the preset 3 button | | other | The cardholder selected the other button | | notip | The cardholder selected the cash/no tip button |
    - `server` ServerComEng
      - `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)