Request a tip

To allow a merchant to request a tip from the customer, use the /v1/device/read-tip endpoint.

📘

NOTE

This endpoint is generally used as part of a transaction flow. See Authorize and capture a tipped payment on screen for instructions to use this endpoint during an auth transaction.

Prerequisites

• POS is connected to the device using a network or cloud connection.
• Clover device is idle; that is, no payment is being taken.

Request a tip with default settings

The simplest request for a tip includes only the baseAmount of the transaction. This type of request uses the merchant's default tip settings and displays options to the customer.

1. Construct a request with the amount of the charge that is not captured (uncaptured charge).

{
  "baseAmount": 3400
}

2. Send the baseAmount as a POST request to /v1/device/read-tip.
3. Required. Include the required headers for your request.
   The tip screen displays the specified amount. After the customer selects a tip amount, a success message displays the tip, and the welcome screen appears.

{
    "response": 680
}

Request a tip with custom settings

If you want to override the default tip amounts or percentages and the on-screen messages, you can include additional information in the request body with the baseAmount.

1. Construct a request with the amount of the uncaptured charge and the custom tipSuggestions you want to display.

{
  "baseAmount": 1400,
  "tipSuggestions": [
    {
      "name": "One dollar",
      "amount": 100
    },
    {
      "name": "Five dollars",
      "amount": 500
    },
    {
      "name": "Ten percent",
      "percentage": 10
    },
    {
      "name": "Twenty percent",
      "percentage": 20
    }
  ]
}

2. Send a POST request to /v1/device/read-tip.
   The tip screen displays for the specified amount with the custom tip information. After the customer selects a tip, a success message displays the tip amount.