Capture pre-authorized payments

Pre-authorizations

Pre-authorization (pre-auth) allows you to place a temporary hold on a card for a specific amount for predetermined time periods. This process is used to reserve funds that can be captured or refunded later. For example, hotels and car rental companies authorize the initial cost of the service but may capture a different amount if additional charges are incurred, such as minibar usage or car damage.

When you create a payment, you can place a hold on an eligible payment method. The validity of the pre-authorization depends on the transaction and card type, so it's important to capture the funds before the authorization expires

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.