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 is 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 completes the transaction.

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

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

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.

Steps

To start the payment flow for a tip-on-screen payment:

  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.
  • An externalPaymentId.
{
  "amount": 3440,
  "capture": false,
  "externalPaymentId": "{externalPaymentId}"
}
  1. Send a POST request to the /v1/payments endpoint.
  2. 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.
12801280
  1. Store the returned amount and id values.
  2. Construct a request with the amount of the uncaptured charge.
{
  "baseAmount": 3440
}
  1. Send the baseAmount as a POST request to /device/v1/read-tip.
    The tip screen displays the specified amount.
12801280

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 with 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.
  2. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

Did this page help you?