REST Pay payment flows

The REST Pay interface supports three transaction types (sale, auth, and pre-auth) by using endpoints in a specific order. This reference provides sample requests for the /v1/payments endpoint and explains the recommended flow to perform each type of transaction. Apps deviating from these flows will not provide the best customer or merchant experience.

Sale flow without tipping (retail store)

The simplest flow is a transaction where the customer does not add a tip. The final amount to be charged is known when the payment request is sent to the device, and the customer only needs to present their card to complete the transaction.

This flow uses the following endpoints:

  • /v1/payments
  • (Optional) /v1/payments/{paymentId}/receipt
  • /v1/device/welcome

Auth flow with tipping (QSR)

Some merchants, such as quick-service restaurants or coffee shops, may want to give the customer the chance 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.

{
    "amount": 5100,
    "capture": false,
  "externalPaymentId": "{externalId}"
}

This flow uses the following endpoints:

  • /v1/device/read-tip
  • /v1/payments
  • (Optional) /v1/payments/{paymentId}/receipt
  • /v1/device/welcome

Auth flow with tipping (FSR)

Full-service restaurants usually allow the customer to provide a tip on a paper receipt. The original transaction amount is later adjusted to include the tip before finalizing the payment. Because the customer will not select a tip on the Clover device, the POS must provide functions for the merchant to print the required receipts and then update the transaction with the customer's tip.

This flow uses the following endpoints:

  • /v1/payments
  • /v1/payments/{paymentId}/receipt
  • /v1/payments/{paymentId}/tip-adjust
  • /v1/device/welcome

Pre-auth flow (hotels and rental cars)

Hotels and rental car companies often pre-authorize a customer's card for the expected amount to be charged. The final charge amount can differ if the merchant needs to add incidental charges.

This flow uses the following endpoints:

  • /v1/payments
  • /v1/payments/{paymentId}/capture
  • (Optional) /v1/payments/{paymentId}/receipt
  • /v1/device/welcome

Did this page help you?