Authorizing and capturing a tip-adjusted payment on paper

Some transactions, like those in full-service restaurants, require a two-step charging process. First, a card is authorized for an amount, the customer adds a tip, and then the final total (original plus tip) is captured at a later time. Tip adjustments can be made without requiring the customer's payment method (physical card or digital wallet) to interact with the Clover device for a second time.

📘

NOTE

  • The most recent tip adjustment overrides all previous tipAmount values. Tip adjustments are not summed.
  • Clover does not place a limit on tip adjustment amounts. However, if merchants adjust amounts to greater than 20% of the authorization, funds are not guaranteed subject to the rules set by card schemes (such as Visa and Mastercard) and electronic payment associations.

Use the /v1/payments and /v1/payments/{paymentId}/tip-adjust endpoints to perform these transactions on the Clover device.

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)

To process a tipped transaction, you use two endpoints to do the following:

  • Authorize the customer's card for an amount
  • Add a customer-provided tipAmount to the payment

To start the payment flow for a tip-adjusted payment, do the following:

  1. Construct a request with the minimum required data (the amount to be charged in cents, a flag to indicate the charge should be captured, the final flag set to false, and an externalPaymentId).
{
  "amount": 9900,
  "capture": true,
  "final": false,
  "externalPaymentId": "{externalPaymentId}"
}
  1. Send a POST request to the /v1/payments endpoint. Be sure to include the required headers for the request you are making.

The payment flow is started for the specified amount. After the authorization is complete, a success message is returned.

  1. Store the returned id value.

  2. Construct a request with the tipAmount set to the value of tip.

{
  "tipAmount" : 1980
}
  1. Send a POST request to /v1/payments/{paymentId}/tip-adjust (where {paymentId} is the id of the original transaction).
    The tip is added to the payment.

  2. (Optional) If you need to retrieve complete data about the auth, send an empty GET request to /v1/payments/{paymentId}.

{
  "payment": {
    "amount": 9900,
    "cardTransaction": {
      "authCode": "308606",
      "begBalance": 0,
      "captured": false,
      "cardType": "DISCOVER",
      "cardholderName": "Cardholder Name",
      "currency": "usd",
      "endBalance": 0,
      "entryType": "SWIPED",
      "extra": {
        "routingIndicator": "C",
        "balanceInfo": "{\"begBal\":0,\"endingBal\":0}",
        "cvmResult": "SIGNATURE",
        "authorizingNetworkId": "Interlink"
      },
      "first6": "601136",
      "last4": "6668",
      "referenceId": "975124104",
      "state": "PENDING",
      "transactionNo": "000130",
      "type": "PREAUTH"
    },
    "cashbackAmount": 0,
    "createdTime": 1617215626000,
    "device": {
      "id": "30882305-e65b-c597-4d3b-849a6ca3f402"
    },
    "employee": {
      "id": "F5CH2S3JWH84T"
    },
    "externalPaymentId": "{externalPaymentId}",
    "id": "B3QQZ4GVEWZ3R",
    "modifiedTime": 1617215785000,
    "offline": false,
    "order": {
      "id": "7EXK4YN3RWSKP"
    },
    "result": "SUCCESS",
    "taxAmount": 0,
    "tipAmount": 1980
  }
}

After closeout, the state changes from PENDING to CLOSED.

  1. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

Did this page help you?