Authorizing and capturing a tipped payment on screen

Some merchants, such as quick-service restaurants or coffee shops, may want to give the customer the opportunity to tip before submitting the transaction. The order subtotal must be calculated by the POS and then used as the baseAmount for the /device/v1/read-tip request. Once the customer tips, the POS calculates the order total (the amount) and finishes the transaction.

Use the /v1/payments, /v1/device/read-tip, and /v1/payments/{paymentId}/capture endpoints to do the following:

  • Authorize the customer's card for an amount
  • Allow the customer to add a tip
  • Capture the final amount (original amount plus the tip)


  • 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 start the payment flow for a tip-on-screen 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 not be captured, and an externalPaymentId).
  "amount": 3440,
  "capture": 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 amount and id values.

  2. Construct a request containing the amount of the uncaptured charge.

  "baseAmount": 3440
  1. Send the baseAmount as a POST request to /device/v1/read-tip.

The tip screen is shown for the specified amount.

Once the customer selects a tip amount, a success message is returned with the tip amount.

  1. Save the response value.

  2. To finalize the charge, construct a request containing the amount as total charge amount. Optionally, include the receipt type in the request.

    "amount": 4128,
    "receipt_email" : "[email protected]"
  1. Send a POST request to /v1/payments/{paymentId}/capture (where {paymentId} is the final charge amount as the request body.

The capture request is sent and returns "captured": true for the charge ID.

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?