Requesting 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 Authorizing and capturing a tipped payment on screen for instructions on using this endpoint during an auth transaction.

Prerequisites

  • The POS is connected to the device using a network or cloud connection
  • The Clover device is in an idle state (that is, no payment is being taken)

Tip with default settings

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

  1. Construct a request containing the amount of the uncaptured charge.
{
  "baseAmount": 3400
}
  1. Send the baseAmount as a POST request to /v1/device/read-tip. Be sure to include the required headers for the request you are making.

The tip screen is shown for the specified amount. After the customer selects a tip amount, a success message is returned with the tip amount and the welcome screen is shown.

{
    "response": 680
}

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 containing 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
    }
  ]
}
  1. Send a POST request to /v1/device/read-tip.

The tip screen is shown for the specified amount with the custom tip information. After the customer selects a tip amount, a success message is returned with the tip amount.


Did this page help you?