Capture pre-authorized payments

Pre-authorizations

Pre-authorization allows you to place a temporary hold on a card for predetermined time periods, and the pre-authorized amount is available to capture or refund.
Example: Hotels and car rental companies authorize the initial cost of the service but may capture a different amount where additional charges are required if a guest uses the hotel minibar, or a driver damages a rental car.
In this process:

1. Pre-authorize the card for an initial amount.
2. Add the cost of additional service to the initial amount.
3. Capture the updated amount — initial + additional amount. The balance is refunded.

Incremental authorizations

Incremental authorizations allow you to increase the authorized amount before capturing a payment, for example: when the total price changes or the customer adds a good or service.
Incremental authorizations are only available for:

• Card types—Mastercard^®, Discover^®, and Visa^® cards.
• Merchant types—aircraft rentals, amusement parks, bicycle rentals, boat rentals, car rentals, cruise lines, drinking places, eating places, equipment rentals, lodgings, motor home rentals, motorcycle rentals, trailer parks/campgrounds, and truck rentals.

Prerequisites

• Point of sale (POS) is connected to the device using a network or cloud connection.
• Clover device is idle; that is no payment is being taken.

Pre-authorize without incremented amounts

1. Use the /v1/payments endpoint to start the transaction on the Clover device with the minimum required data:

   • amount to be charged in cents
   • capture indicator set to False
   • externalPaymentId
   json

   {
     "amount": 50000,
     "capture": false,
     "externalPaymentId": "{externalPaymentId}"
   }
   

2. Send a POST request to the /v1/payments endpoint with the required headers:

• X-Clover-Device-Id
• X-POS-Id
• Idempotency-Key

The payment flow is started for the specified amount. After the authorization is complete, a success message appears.

3. Copy and save the id value from the success message.
4. Create a request with the final amount to charge.

{
  "amount": 50000
}

5. Send a POST request to /v1/payments/{authId}/capture, where {authId} is the id value you saved in step 3.
   The system captures the preauthorization and returns the final paymentId.
6. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

Pre-authorize with incremented amounts

1. Use the /v1/payments endpoint to start the transaction on the Clover device with the minimum required data:

• amount to be charged in cents
• capture indicator set to False
• externalPaymentId

{
  "amount": 50000,
  "capture": false
  "externalPaymentId": "{externalPaymentId}"
}

2. Send a POST request to the /v1/payments endpoint with the required headers:

   • X-Clover-Device-Id
   • X-POS-Id
   • Idempotency-Key

   The payment flow is started for the specified amount. After the authorization is complete, a success message appears.

3. Copy and save the id value from the success message.

4. Create a request with the incremented amount to charge.

JSON
{
  "amount": 12000
}

5. Send a POST request to /v1/payments/{paymentId}/increment with the required headers:, where {authId} is the id value you saved in step 3. Required headers are:

   • X-Clover-Device-Id
   • X-POS-Id
   • Idempotency-Key

   The incremented amount is added to the initial authorization amount. After the authorization is complete, a success message appears.

6. Create a request with the final amount you want to capture.

{
  "amount": 62000
}

7. Send a POST request to /v1/payments/{authId}/capture, where {authId} is the id value you saved in step 3.
   The system captures the preauthorization and returns the final paymentId.
8. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.