Authorize and capture a tipped payment on screen

Some merchants, such as quick service restaurants or coffee shops, may want to allow the customer 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—the original amount plus the tip.

Prerequisites

• POS is connected to the device using a network or cloud connection.
• Clover device is idle; 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}"
}

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 amount and id values.
5. Construct a request with the amount of the uncaptured charge.

{
  "baseAmount": 3440
}

6. Send the baseAmount as a POST request to /device/v1/read-tip.
   The tip screen displays the specified amount.

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

7. Save the response value.
8. To finalize the charge, construct a request with the amount as the total charge amount. Optionally, include the receipt type in the request.

{
	"amount": 4128,
	"receipt_email" : "[email protected]"
}

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