REST Pay payment flows

United States

Canada

Europe

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 may not offer the best customer or merchant experience.

Sale flow without tipping—Retail store

The most straightforward flow is a transaction where the customer does not add a tip. The final amount to charge 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—Quick service restaurant

Some merchants, such as quick service restaurants or coffee shops, may want to give the customer a chance to tip before submitting the transaction. The POS must calculate the order subtotal and then use it as the baseAmount for the /device/v1/read-tip request. Once the customer tips, the POS calculates the order total or the amount, and completes 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—full service restaurants

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. Since the customer does 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 may 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