Place a hold on a payment method
When you create a payment, you can place a hold on an eligible payment method to reserve the funds for a few days and capture them later. The payment will stay in “Authorized” status during this period.
Authorization helps guarantee the payment amount by holding it on the customer’s payment method. A typical use case is that hotels would normally ask the guest to authorize a deposit at arrival to cover any potential additional charges and then capture the actual charges during checkout. During the whole stay, the funds will be held on the guest’s credit card.
You need to capture the funds before the authorization expires. You can capture less than the original amount, but cannot capture more. If the authorization expires before you capture the funds, the funds are released and the payment status changes to “Cancelled”.
Please note that placing a hold is currently only supported for cards (including Apple Pay and Google Pay) and Klarna payment methods and the authorization expiry window differs by payment method:
- Card payments: By default the authorization expires in 7 days. You can request extended authorization time-periods for the following cases (see more details in step 2):
- Visa: Up to 31 days for cruise, lodging, or vehicle rental businesses
- MasterCard: 30 days for all businesses
- Klarna: 28 days for all businesses
By default, we will automatically capture your payment to request the funds immediately at the end of a successful payment flow. To indicate that you want to delay the capture, specify
false when you are confirming the PaymentIntent with the eligible payment method. This parameter instructs us to only authorize the amount but not capture it in the real-time payment flow.
- If you are integrating via Hosted Payment Page JS, Drop-in or Embedded Elements JS, please refer to the detailed guidance on how to specify auto-capture value (for embedded elements, please refer to the guidance on the specific element type that you are using)
- Currently, you cannot place a hold on payments collected via Payment Links
When you are ready to request the funds, you can instruct the capture request for your payment. You can capture less than the original authorized amount by specifying the actual figure in your request.