Authorize and capture a tip-adjusted payment on paper

Some transactions, like those in full service restaurants, require a two-step charging process.

1. Card is authorized for an amount, and the customer adds a tip.
2. Total amount of the original plus tip is captured later. Tip adjustments do not require the customer's payment method—a physical card or digital wallet—to interact with the Clover device for a second time.

📘

NOTE

• 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 Mastercard© and Visa©, and electronic payment associations.

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

Prerequisites

• POS is connected to the device using a network or cloud connection.
• Clover device is idle; that is, no payment is being taken.
  To process a tipped transaction, use two endpoints to:
  • Authorize the customer's card for an amount.
  • Add a customer-provided tipAmount to the payment.

Steps

To start the payment flow for a tip-adjusted payment:

1. Construct a request with the minimum required data:

• The amount to be charged in cents.
• The flag indicates the charge should be captured.
• The final flag set to false.
• The `externalPaymentId.

{
  "amount": 9900,
  "capture": true,
  "final": false,
  "externalPaymentId": "{externalPaymentId}"
}

2. Send a POST request to the /v1/payments endpoint.
3. Required. Include the required headers for your request.
   The payment flow is started for the specified amount. After the authorization is complete, a success message appears.
4. Store the returned id value.
5. Construct a request with the tipAmount set to the value of tip.

{
  "tipAmount" : 1980
}

5. 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.
6. 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.

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